# 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 border styles, thickness, length, alignment, and spacing through props and CSS variables.

## Component Structure

```
Divider/
├── index.tsx                     # Main component with render logic
├── types.ts                      # TypeScript type definitions
├── ContentFields.tsx             # HubSpot field definitions for content
├── 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?: 'stretch' | 'start' | 'center' | 'end';    // Alignment within parent container (default: 'stretch')
  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)
  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:**
- `stretch` (default): Divider uses full available space
- `start`: Aligns to the start of the container (left for horizontal, top for vertical)
- `center`: Centers within the container
- `end`: Aligns to the end of the container (right for horizontal, bottom for vertical)

## Usage Examples

### Basic Horizontal Divider

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

// Default horizontal divider
<Divider />
```

### Basic Vertical Divider

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

### Horizontal Divider with Custom Spacing

```tsx
// Divider with more spacing above and below
<Divider
  orientation="horizontal"
  spacing="32px"
/>
```

### Vertical Divider with Custom Height

```tsx
// Vertical divider at 80% height
<Divider
  orientation="vertical"
  length={80}
  alignment="center"
/>
```

### Customized Divider with Dashed Style

```tsx
<Divider
  orientation="horizontal"
  borderStyle="dashed"
  thickness={2}
  length={75}
  alignment="center"
  spacing="24px"
/>
```

### Thick Divider for Emphasis

```tsx
<Divider
  orientation="horizontal"
  thickness={4}
  borderStyle="solid"
/>
```

### Dotted Divider

```tsx
<Divider
  orientation="horizontal"
  borderStyle="dotted"
  thickness={2}
/>
```

### Short Centered Divider

```tsx
// Decorative short divider, centered
<Divider
  orientation="horizontal"
  length={50}
  alignment="center"
  spacing="16px"
/>
```

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

The Divider component provides field definitions for easy integration with HubSpot CMS modules.

#### ContentFields

Configurable props for divider appearance:

```tsx
<Divider.ContentFields
  orientationLabel="Divider Orientation"
  orientationName="orientation"
  orientationDefault="horizontal"
  alignmentLabel="Divider Alignment"
  alignmentName="alignment"
  alignmentDefault="stretch"
  lengthLabel="Divider Length"
  lengthName="length"
  lengthDefault={100}
  thicknessLabel="Divider Thickness"
  thicknessName="thickness"
  thicknessDefault={1}
/>
```

**Fields:**
- `orientation`: ChoiceField for selecting horizontal or vertical orientation
- `alignment`: ChoiceField for alignment (stretch, start, center, end)
- `length`: NumberField for length percentage (1-100)
- `thickness`: NumberField for thickness in pixels (minimum: 1)

#### StyleFields

Configurable props for divider border style:

```tsx
<Divider.StyleFields
  borderStyleLabel="Border Style"
  borderStyleName="borderStyle"
  borderStyleDefault="solid"
/>
```

**Fields:**
- `borderStyle`: ChoiceField for selecting border style (solid, dotted, dashed, double)

**Note:** The `spacing` prop must be set directly on the Divider component, as there is no field definition for it in StyleFields or ContentFields.

### Module Usage Example

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

export default function SectionDividerModule({ fieldValues }) {
  return (
    <Divider
      orientation={fieldValues.orientation}
      alignment={fieldValues.alignment}
      borderStyle={fieldValues.borderStyle}
      length={fieldValues.length}
      thickness={fieldValues.thickness}
      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>
    <Divider.ContentFields />
    <FieldGroup label="Style" name="style" tab="STYLE">
      <Divider.StyleFields />
    </FieldGroup>
  </ModuleFields>
);
```

## Styling

### CSS Variables

The Divider component uses CSS variables for theming and customization:

**Base Styles:**
- `--hscl-divider-borderColor`: Border color (default: currentColor)
- `--hscl-divider-borderStyle`: Border style (default: solid)
- `--hscl-divider-length`: Length as percentage (default: 100%)
- `--hscl-divider-thickness`: Border thickness as pixel value (default: 1px)
- `--hscl-divider-alignment`: Flex alignment value (default: stretch)

**Spacing:**
- `--hscl-divider-spacing`: Spacing around the divider
  - Horizontal: Applied as `margin-block` (top and bottom)
  - Vertical: Applied as `margin-inline` (left and right)


## 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
- **Visual Separation**: Provides clear visual boundaries between content sections
- **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**:
  - Use `stretch` (default) for full-width/height separators
  - Use `center` for decorative short dividers
  - Use `start` or `end` for aligned content sections
- **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)
- **Border styles**: Choose appropriate border style for visual hierarchy:
  - `solid`: Default, clear separation
  - `dashed`: Less prominent, informal
  - `dotted`: Subtle, minimal separation
  - `double`: Emphasis, formal
