# Separator

Visually or semantically separates content. Use Separator for subtle section
breaks, split navigation rows, compact menu metadata, and stacked definition
lists.

## Import

```ts
import { SeparatorComponent } from '@edsis/component/separator';
```

## Basic usage

Use the default separator for purely visual breaks. When the divider carries
structure that assistive technology should announce, set
`[decorative]="false"`.

```html
<Separator class="my-4" /> <Separator [decorative]="false" class="my-4" />
```

## Common patterns

### Preview card

This mirrors the upstream shadcn hero example: title block, separator, then the
supporting description.

```html
<div
  class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-sm"
>
  <div class="flex flex-col gap-1.5">
    <div class="leading-none font-medium">shadcn/ui</div>
    <div class="text-muted-foreground">The Foundation for your Design System</div>
  </div>
  <Separator />
  <div class="text-muted-foreground">
    A set of beautifully designed components that you can customize, extend, and build on.
  </div>
</div>
```

### Vertical row

Use `orientation="vertical"` when the separator sits inside a horizontal flex
row. Give the host an explicit height, or inherit it from a parent with defined
cross-axis size.

```html
<div class="flex h-5 items-center gap-4 text-sm">
  <div>Blog</div>
  <Separator orientation="vertical" class="h-5" />
  <div>Docs</div>
  <Separator orientation="vertical" class="h-5" />
  <div>Source</div>
</div>
```

### Menu metadata

Vertical separators work well between compact description groups.

```html
<div class="flex w-full max-w-2xl items-center gap-2 text-sm md:gap-4">
  <div class="flex flex-col gap-1">
    <span class="font-medium">Settings</span>
    <span class="text-xs text-muted-foreground">Manage preferences</span>
  </div>
  <Separator orientation="vertical" class="h-10" />
  <div class="flex flex-col gap-1">
    <span class="font-medium">Account</span>
    <span class="text-xs text-muted-foreground">Profile &amp; security</span>
  </div>
  <Separator orientation="vertical" class="hidden h-10 md:block" />
  <div class="hidden flex-col gap-1 md:flex">
    <span class="font-medium">Help</span>
    <span class="text-xs text-muted-foreground">Support &amp; docs</span>
  </div>
</div>
```

### List rows

Horizontal separators are the lightest-weight way to split dense stacked rows.

```html
<div class="flex w-full max-w-sm flex-col gap-2 text-sm">
  <dl class="flex items-center justify-between gap-4">
    <dt class="font-medium">Item 1</dt>
    <dd class="text-muted-foreground">Value 1</dd>
  </dl>
  <Separator />
  <dl class="flex items-center justify-between gap-4">
    <dt class="font-medium">Item 2</dt>
    <dd class="text-muted-foreground">Value 2</dd>
  </dl>
  <Separator />
  <dl class="flex items-center justify-between gap-4">
    <dt class="font-medium">Item 3</dt>
    <dd class="text-muted-foreground">Value 3</dd>
  </dl>
</div>
```

### RTL

The separator itself does not need an RTL-specific API. Set `dir="rtl"` on the
surrounding container and translate neighboring content.

```html
<section
  dir="rtl"
  lang="ar"
  class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-right text-sm"
>
  <div class="flex flex-col gap-1.5">
    <div class="leading-none font-medium">shadcn/ui</div>
    <div class="text-muted-foreground">الأساس لنظام التصميم الخاص بك</div>
  </div>
  <Separator />
  <div class="text-muted-foreground">
    مجموعة من المكونات المصممة بشكل جميل يمكنك تخصيصها وتوسيعها والبناء عليها.
  </div>
</section>
```

## API reference

| Input         | Type                         | Default        | Description                                                    |
| ------------- | ---------------------------- | -------------- | -------------------------------------------------------------- |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of the divider.                                           |
| `decorative`  | `boolean`                    | `true`         | When `false`, sets `role="separator"` plus `aria-orientation`. |
| `class`       | `string`                     | `''`           | Width, height, spacing, and visibility utilities.              |

Native host attributes such as `dir`, `data-*`, and `id` still pass through to
the custom element host.

## Styling and theming

Tokens consumed:

- `bg-border` for the rule itself.

Horizontal mode applies `h-px w-full`. Vertical mode applies `h-full w-px`.
The host renders as a block-level custom element so width and height utilities
behave predictably on the separator itself.

## Accessibility

- Separators are decorative by default and render with `role="none"`.
- When the divider carries structure, set `[decorative]="false"` so assistive
  technology sees a real `separator` with the correct `aria-orientation`.
- Keep accessible names on the surrounding content; separators themselves do not
  require labels.

## Keyboard interactions

Separator is not interactive and has no keyboard behavior of its own.

## Angular notes

- Because `Separator` is a custom element, vertical examples need a height
  source from the parent or the host `class` input.
- The block-level host class is intentional. It ensures horizontal separators
  honor `w-full` and other layout utilities that would otherwise be unreliable
  on an inline custom element.

## Source parity

This Angular implementation follows the shadcn separator preview plus the
vertical, menu, list, and RTL examples. It adds Angular-specific guidance for
semantic separators and for the custom-element host layout behavior needed to
match the upstream visuals.