# Divider Component

A visual separator component that can be oriented horizontally or vertically to divide content sections. Creates semantic separation using native HTML elements with customizable styling.

## Import path
```tsx
import Divider from '@hubspot/cms-component-library/Divider';
```

## Purpose

The Divider component provides a consistent way to create visual separators in HubSpot CMS projects. It renders semantic HTML elements (`<hr>` for horizontal, `<div role="separator">` for vertical) with flexible styling options. Developers should use this component when they need to visually separate content sections, whether between stacked content (horizontal) or side-by-side content (vertical). The component supports customizable line type, thickness, length, alignment, color, and spacing through props and CSS variables.

## Component Structure

```
Divider/
├── index.tsx                     # Main component with render logic
├── types.ts                      # TypeScript type definitions
├── StyleFields.tsx               # HubSpot field definitions for styling
├── index.module.scss             # CSS module with design tokens
└── stories/
    ├── Divider.stories.tsx       # Component usage examples
    ├── DividerDecorator.tsx      # Storybook decorator
    └── DividerDecorator.module.css  # Decorator styles
```

## Components

### Divider (Main Component)

**Purpose:** Renders a visual separator that adapts its HTML element and styling based on orientation.

**Props:**
```tsx
{
  orientation?: 'horizontal' | 'vertical';                     // Divider orientation (default: 'horizontal')
  alignment?: {                                                 // Alignment within parent container
    horizontal_align?: 'LEFT' | 'CENTER' | 'RIGHT';
    vertical_align?: 'TOP' | 'MIDDLE' | 'BOTTOM';
  };
  spacing?: string;                                            // Margin spacing in pixel format (e.g., '16px', '24px')
  borderStyle?: 'solid' | 'dotted' | 'dashed' | 'double';     // Border line style (default: 'solid')
  length?: number;                                             // Length as percentage (1-100) of available space (default: 100)
  thickness?: number;                                          // Border thickness in pixels (default: 1)
  color?: { rgba?: string; color?: string; opacity?: number }; // Line color (from ColorField or rgba value)
  className?: string;                                          // Additional CSS classes
  style?: React.CSSProperties;                                 // Inline styles (including CSS variables)
}
```

**Rendering Behavior:**
- `orientation="horizontal"`: Renders as `<hr>` element with top border
- `orientation="vertical"`: Renders as `<div role="separator">` with left border

**Alignment Behavior:**

When no `alignment` is passed, the divider stretches to fill the available space (default).

For horizontal dividers, use `horizontal_align`:
- `'LEFT'`: Aligns to the left (`flex-start`)
- `'CENTER'`: Centers within the container
- `'RIGHT'`: Aligns to the right (`flex-end`)

For vertical dividers, use `vertical_align`:
- `'TOP'`: Aligns to the top (`flex-start`)
- `'MIDDLE'`: Centers vertically
- `'BOTTOM'`: Aligns to the bottom (`flex-end`)

## Usage Examples

### Basic Horizontal Divider

```tsx
import Divider from '@hubspot/cms-component-library/Divider';

// Default horizontal divider (full width, stretch)
<Divider />
```

### Basic Vertical Divider

```tsx
// Vertical separator between content
<Divider orientation="vertical" />
```

### Horizontal Divider with Custom Spacing

```tsx
<Divider spacing="32px" />
```

### Short Centered Divider

```tsx
<Divider length={50} alignment={{ horizontal_align: 'CENTER' }} spacing="16px" />
```

### Customized Divider

```tsx
<Divider
  borderStyle="dashed"
  thickness={2}
  length={75}
  alignment={{ horizontal_align: 'CENTER' }}
  spacing="24px"
/>
```

### Colored Divider

```tsx
// color.rgba is populated by the ColorField in a module context
<Divider color={{ rgba: 'rgba(59, 130, 246, 1)' }} thickness={2} />
```

### Vertical Divider with Alignment

```tsx
<Divider
  orientation="vertical"
  length={50}
  alignment={{ vertical_align: 'MIDDLE' }}
/>
```

### Vertical Divider in Flex Layout

```tsx
import Flex from '@hubspot/cms-component-library/Flex';
import Divider from '@hubspot/cms-component-library/Divider';

<Flex direction="row" gap="16px" alignItems="center">
  <div>Left Content</div>
  <Divider orientation="vertical" />
  <div>Right Content</div>
</Flex>
```

## HubSpot CMS Integration

### Field Definitions

All Divider fields are style fields. The Divider component exposes only `StyleFields` — there are no content fields.

#### StyleFields

All configurable style props for the divider:

```tsx
<Divider.StyleFields
  borderStyleLabel="Line type"
  borderStyleName="borderStyle"
  borderStyleDefault="solid"
  thicknessLabel="Line thickness"
  thicknessName="thickness"
  thicknessDefault={1}
  lengthLabel="Line length"
  lengthName="length"
  lengthDefault={100}
  alignmentLabel="Line alignment"
  alignmentName="alignment"
  alignmentDefault={{ horizontal_align: 'CENTER', vertical_align: 'MIDDLE' }}
  alignmentDirection="HORIZONTAL"
  colorLabel="Line color"
  colorName="color"
  colorDefault={{ color: '#000000', opacity: 100 }}
/>
```

**Fields:**
- `borderStyle`: ChoiceField for line type (solid, dotted, dashed, double)
- `thickness`: NumberField for thickness in pixels (minimum: 1, suffix: px)
- `length`: NumberField for length as a percentage (1–100, suffix: %)
- `alignment`: AlignmentField for alignment within the container
- `color`: ColorField for line color (opacity hidden — color only)

**Developer-only props (not user-facing):**
- `alignmentDirection`: Controls whether the AlignmentField shows horizontal or vertical options. Accepts `'HORIZONTAL'` (default) or `'VERTICAL'`. Set this based on how the divider will be used — developers consuming the component set this, not end users.
- `hideFields`: An array of field names to opt out of rendering. All fields are shown by default (opt-out). Accepts an array of `StyleFieldName` values: `'borderStyle' | 'color' | 'thickness' | 'length' | 'alignment'`.

**Hiding fields example:**

```tsx
<FieldGroup label="Style" name="style" tab="STYLE">
  <Divider.StyleFields hideFields={['alignment', 'length']} />
</FieldGroup>
```

**Note:** The `orientation` and `spacing` props must be set directly on the Divider component — there are no field definitions for them.

### Module Usage Example

```tsx
import Divider from '@hubspot/cms-component-library/Divider';

export default function SectionDividerModule({ fieldValues }) {
  const { borderStyle, thickness, length, alignment, color } = fieldValues.style;

  return (
    <Divider
      borderStyle={borderStyle}
      thickness={thickness}
      length={length}
      alignment={alignment}
      color={color}
      spacing="24px"
    />
  );
}
```

### Module Fields Example

```tsx
import { FieldGroup, ModuleFields } from '@hubspot/cms-components/fields';
import Divider from '@hubspot/cms-component-library/Divider';

export const fields = (
  <ModuleFields>
    <FieldGroup label="Style" name="style" tab="STYLE">
      <Divider.StyleFields />
    </FieldGroup>
  </ModuleFields>
);
```

For a vertical divider module, pass `alignmentDirection` to expose vertical alignment options:

```tsx
<FieldGroup label="Style" name="style" tab="STYLE">
  <Divider.StyleFields alignmentDirection="VERTICAL" />
</FieldGroup>
```

## Styling

The Divider component applies all styling via inline styles derived from props. The CSS module provides hardcoded defaults (1px solid currentColor, stretch alignment, 16px margin) which are overridden by prop values when provided. No CSS variables are used.

## Accessibility

The Divider component follows accessibility best practices:

- **Semantic HTML**:
  - Horizontal: Uses native `<hr>` element, recognized by screen readers as thematic break
  - Vertical: Uses `<div role="separator">` for proper ARIA semantics
- **Keyboard Navigation**: Does not interfere with keyboard navigation as it's non-interactive
- **Screen Reader Support**: Properly announced by assistive technologies as content separators

## Best Practices

- **Choose the right orientation**:
  - Use `horizontal` for separating stacked content sections (most common)
  - Use `vertical` for separating side-by-side content within a Flex or Grid layout
- **Alignment considerations**:
  - Omit `alignment` for full-width/height stretch behavior (default)
  - Use `{ horizontal_align: 'CENTER' }` for decorative short horizontal dividers
  - Use `{ vertical_align: 'MIDDLE' }` for centered vertical dividers
  - Set `alignmentDirection` on `StyleFields` to match the intended orientation so users see the right alignment options
- **Spacing guidelines**:
  - Use `spacing` prop to control margin around the divider
  - For horizontal dividers, spacing controls top/bottom margin
  - For vertical dividers, spacing controls left/right margin
- **Length as percentage**: The `length` prop accepts 1–100 as a percentage, not pixel values
- **Thickness control**: Use the `thickness` prop for border thickness (in pixels). Double border style requires at least 3px
- **Color**: The `color` prop is populated from the `ColorField` in a module context. In non-module usage, pass `{ rgba: 'rgba(...)' }` directly
- **Line type**: Choose appropriate border style for visual hierarchy:
  - `solid`: Default, clear separation
  - `dashed`: Less prominent, informal
  - `dotted`: Subtle, minimal separation
  - `double`: Emphasis, formal
