# 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)
  variant?: 'primary' | 'secondary' | 'tertiary';             // Visual style variant (default: 'primary')
  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

### CSS Variables

The Divider component uses CSS variables for theming and customization:

- `--hscl-divider-borderColor`: Border color (default: currentColor)
- `--hscl-divider-borderStyle`: Border style (default: solid)
- `--hscl-divider-borderWidth`: Border thickness as pixel value (default: 1px)
- `--hscl-divider-alignment`: Flex alignment value (default: stretch)
- `--hscl-divider-width`: Width for horizontal dividers (default: 100%)
- `--hscl-divider-height`: Height for vertical dividers (default: 100%)
- `--hscl-divider-marginBlock`: Top/bottom margin for horizontal dividers (default: 16px)
- `--hscl-divider-marginInline`: Left/right margin for vertical dividers (default: 16px)

## 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
