# Specification

## Overview

A Divider is a single line to separate or group content.

## Use Cases

The divider accommodates several use-cases:

- Dividers are used to divide sections of content from each other.
- Dividers helps categorize and organize the content in a page.
- Use the divider when there is a need to separate content into clear groups.

## Non-goals

- Divider is a static structure that provides a visible boundary for elements and hence is non interactive.
- Customizations made outside of [Styling Hooks](#styling-hooks-jump) are not supported.

## Features

- The API design of the divider inherits [global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes). All methods and properties of the HTML element are as the web platform designed it.
- The "default" appearance is a single straight line with two end points.
- The "default" appearance comes with default branding.
- [Styling hooks](#styling-hooks-jump) should be used to customize the appearance of the divider.
- Customization beyond Styling Hooks can be achieved through the [CSS Shadow Parts API](#css-shadow-parts). The addition of CSS is allowed through `::part` but falls outside the support matrix of WES.

## Prior Art/Examples

- [Clarity Design System](https://clarity.design/core-components/divider/)
- [Duet Design System](https://www.duetds.com/components/divider/#top)
- [Vuetify Design System](https://vuetifyjs.com/en/components/dividers/)

---

## API

The divider component should support all [global attributes](https://html.spec.whatwg.org/multipage/dom.html#global-attributes) of HTML elements.

## Anatomy and Appearance

#### Diagram

![Example Diagram](images/wes-divider.diagram.png)

### DOM Structure

```html
<host>
  <div part="divider">
    <div part="content">
      <slot name="icon"></slot>
      <span part="label">
        <slot></slot>
      </span>
    </div>
  </div>
</host>
```

### Slots

| Slot Name | Description      | Fallback Content |
| --------- | ---------------- | ---------------- |
| `icon`    | Icon placeholder | empty            |
| `default` | Text placeholder | empty            |

### Parts

| Part Name | Description                      |
| --------- | -------------------------------- |
| `divider` | Outer container of the component |
| `content` | Container of icon and text       |
| `label`   | Container of the text            |

### Properties & Attributes

| Attribute          | Type                                                                                                       | Default Value | Description                             |
| ------------------ | ---------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------- |
| `color`            | `red`/`pink`/`violet`/`purple`/`indigo`/`blue`/`cloud-blue`/`teal`/`green`/`yellow`/`orange`/ `hot-orange` | `empty`       | Defines the color of the divider.       |
| `direction`        | `horizontal`/`vertical`                                                                                    | `horizontal`  | Defines the orientation of the divider. |
| `variant`          | `primary`/`secondary`                                                                                      | `primary`     | Defines the type of the divider.        |
| `role`             | `enum`                                                                                                     | `separator`   | Defines ARIA role semantics.            |
| `aria-orientation` | `enum`                                                                                                     | `horizontal`  | Indicates the element's orientation.    |

### Styling Hooks

#### Color

| Property Name            | CSS Property       | Fallback Value | Description                   |
| ------------------------ | ------------------ | -------------- | ----------------------------- |
| `--wes-c-divider-color` | `background-color` | `#c9c9c9`      | Sets the color of the divider |

#### Spacing

| Property Name                           | CSS Property                     | Fallback Value           | Description                          |
| --------------------------------------- | -------------------------------- | ------------------------ | ------------------------------------ |
| `--wes-c-divider-spacing-inline-start` | `padding-left`/`margin-left`     | `var(--wes-g-spacing-4)` | Sets the left space of the divider   |
| `--wes-c-divider-spacing-inline-end`   | `padding-right`/`margin-right`   | `var(--wes-g-spacing-4)` | Sets the right space of the divider  |
| `--wes-c-divider-spacing-block-top`    | `padding-top`/`margin-top`       | `var(--wes-g-spacing-4)` | Sets the top space of the divider    |
| `--wes-c-divider-spacing-block-bottom` | `padding-bottom`/`margin-bottom` | `var(--wes-g-spacing-4)` | Sets the bottom space of the divider |

## Events

N/A

## Behavior

N/A

## Accessibility

### Roles

By default, wes-divider component is assigned the ARIA role of ['separator'](https://www.w3.org/TR/wai-aria/#separator) which denotes that the divider “separates and distinguishes sections of content or groups of menu items.” However, sometimes a divider is just a way to make an interface look nice. In those cases, the role of `presentation` should be used which denotes “an element whose implicit native role semantics will not be mapped to the accessibility API”. To override the default separator role in a wes-divider, simply add a `role="presentation"` prop to your component. In addition, wes-divider components have an `aria-orientation="horizontal"`. If direction="vertical", then `aria-orientation="vertical"` will be set automatically as well. If role="presentation", then `aria-orientation=undefined` is its default value.

## Internationalization

All slotted content inside the divider should adhere to bi-directional languages such as `ltr` (left to right) and `rtl` (right to left).

## Test Plan

- All dividers should have visual regression tests to catch any unintended modifications to the visuals of the divider
- All dividers should have a test to catch color contrast regressions that, at a minimum, fulfill the requirements of WCAG 2.1.