# Breadcrumb

Displays the path to the current resource using a hierarchy of links.

Use Breadcrumb for hierarchical navigation trails in docs, account areas, settings surfaces, and deep app routes where users need a quick sense of where they are.

## Import

```ts
import {
  BreadcrumbComponent,
  BreadcrumbEllipsisComponent,
  BreadcrumbItemComponent,
  BreadcrumbLinkComponent,
  BreadcrumbListComponent,
  BreadcrumbPageComponent,
  BreadcrumbSeparatorComponent,
} from '@edsis/component/breadcrumb';
import { RouterLink } from '@angular/router';
```

## Composition

The Angular structure matches the shadcn breadcrumb composition while translating it to Angular selectors and native router-friendly anchors.

```text
Breadcrumb
└── ol[BreadcrumbList]
    ├── li[BreadcrumbItem]
    │   └── a[BreadcrumbLink]
    ├── li[BreadcrumbSeparator]
    ├── li[BreadcrumbItem]
    │   └── a[BreadcrumbLink]
    ├── li[BreadcrumbSeparator]
    └── li[BreadcrumbItem]
        └── span[BreadcrumbPage]
```

## Basic usage

Prefer a semantic `<nav Breadcrumb>` root, then build the trail from list, item, link, separator, and current-page parts.

```html
<nav Breadcrumb>
  <ol BreadcrumbList>
    <li BreadcrumbItem>
      <a BreadcrumbLink routerLink="/">Home</a>
    </li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem>
      <a BreadcrumbLink routerLink="/ui/shadcn/button">Components</a>
    </li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem>
      <span BreadcrumbPage>Breadcrumb</span>
    </li>
  </ol>
</nav>
```

## Common patterns

### Custom separator

Project custom children into `BreadcrumbSeparator` to swap the default chevron for a slash, dot, brand icon, or other neutral divider.

```html
<nav Breadcrumb>
  <ol BreadcrumbList>
    <li BreadcrumbItem><a BreadcrumbLink href="/">Home</a></li>
    <li BreadcrumbSeparator>
      <svg class="h-2.5 w-2.5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
        <circle cx="12" cy="12" r="3"></circle>
      </svg>
    </li>
    <li BreadcrumbItem><a BreadcrumbLink href="/components">Components</a></li>
    <li BreadcrumbSeparator>
      <svg class="h-2.5 w-2.5" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
        <circle cx="12" cy="12" r="3"></circle>
      </svg>
    </li>
    <li BreadcrumbItem><span BreadcrumbPage>Breadcrumb</span></li>
  </ol>
</nav>
```

### Collapsed trail

Use `BreadcrumbEllipsis` when the trail is too long to show in full. Wrap it in a labeled button when the ellipsis should open an overflow menu.

```html
<nav Breadcrumb>
  <ol BreadcrumbList>
    <li BreadcrumbItem><a BreadcrumbLink routerLink="/">Home</a></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><span BreadcrumbEllipsis></span></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><a BreadcrumbLink routerLink="/docs/components">Components</a></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><span BreadcrumbPage>Breadcrumb</span></li>
  </ol>
</nav>
```

### Dropdown composition

Compose a breadcrumb item with the local menu primitives when an intermediate node should expose related destinations instead of linking directly.

```html
<nav Breadcrumb>
  <ol BreadcrumbList>
    <li BreadcrumbItem><a BreadcrumbLink routerLink="/">Home</a></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem>
      <button
        Button
        type="button"
        variant="ghost"
        class="h-auto gap-1 px-2 py-1 font-normal text-muted-foreground hover:text-foreground"
        [MenuTrigger]="componentsMenu"
      >
        Components
        <svg
          class="h-3.5 w-3.5"
          viewBox="0 0 24 24"
          fill="none"
          stroke="currentColor"
          stroke-width="2"
        >
          <polyline points="6 9 12 15 18 9"></polyline>
        </svg>
      </button>

      <ng-template MenuContent #componentsMenu="MenuContent">
        <MenuSurface class="w-44">
          <MenuLabel>Components</MenuLabel>
          <button MenuItem>Documentation</button>
          <button MenuItem>Themes</button>
          <button MenuItem>GitHub</button>
        </MenuSurface>
      </ng-template>
    </li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><span BreadcrumbPage>Breadcrumb</span></li>
  </ol>
</nav>
```

### RouterLink integration

The shadcn React examples use `asChild` for custom routing components. In Angular, apply `routerLink` or `href` directly to the anchor that carries `BreadcrumbLink`.

```html
<a BreadcrumbLink routerLink="/ui/shadcn">Components</a>
<a BreadcrumbLink href="https://ui.shadcn.com/docs/components/radix/breadcrumb">shadcn docs</a>
```

### RTL

Set `dir="rtl"` on the breadcrumb root or an ancestor container. The structure stays the same while the visual flow shifts to right-to-left.

```html
<nav Breadcrumb dir="rtl" lang="ar">
  <ol BreadcrumbList class="justify-end">
    <li BreadcrumbItem><a BreadcrumbLink href="/">الرئيسية</a></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><a BreadcrumbLink href="/components">المكونات</a></li>
    <li BreadcrumbSeparator></li>
    <li BreadcrumbItem><span BreadcrumbPage>مسار التنقل</span></li>
  </ol>
</nav>
```

## API reference

### `BreadcrumbComponent`

| Input   | Type     | Default |
| ------- | -------- | ------- |
| `class` | `string` | `''`    |

Use on `Breadcrumb` or `nav[Breadcrumb]`. The root always emits `aria-label="breadcrumb"` and keeps the custom-element form block-level.

### Parts

| Part                           | Selector                   | Input   |
| ------------------------------ | -------------------------- | ------- |
| `BreadcrumbListComponent`      | `ol[BreadcrumbList]`       | `class` |
| `BreadcrumbItemComponent`      | `li[BreadcrumbItem]`       | `class` |
| `BreadcrumbLinkComponent`      | `a[BreadcrumbLink]`        | `class` |
| `BreadcrumbPageComponent`      | `span[BreadcrumbPage]`     | `class` |
| `BreadcrumbSeparatorComponent` | `li[BreadcrumbSeparator]`  | `class` |
| `BreadcrumbEllipsisComponent`  | `span[BreadcrumbEllipsis]` | `class` |

`BreadcrumbSeparatorComponent` accepts projected children to replace the default chevron icon.

## Styling and theming

The breadcrumb follows the shared theme tokens for foreground and muted text. Pass `class` to the list or individual parts to control spacing, alignment, color, and embedded layouts.

For example, use `class="justify-end"` on `BreadcrumbList` for RTL alignment or `class="max-w-full"` on the root to fit a constrained header.

## Accessibility

- Root `<nav>` exposes `aria-label="breadcrumb"`.
- The current page uses `<span BreadcrumbPage>` which emits `role="link"`, `aria-current="page"`, and `aria-disabled="true"` so the trail announces the current location.
- Separators and ellipses are `aria-hidden` and `role="presentation"`.
- If `BreadcrumbEllipsis` becomes interactive, wrap it in a labeled button so the overflow action is announced correctly.

## Keyboard interactions

- Links use native anchor keyboard behavior.
- Overflow menu buttons rely on the local `Button` and `MenuTrigger` primitives for Enter, Space, ArrowDown, and Escape handling.

## Angular notes

- Prefer `<nav Breadcrumb>` for a semantic navigation landmark.
- `<Breadcrumb>` is also supported and renders as a block-level host by default.
- The React `asChild` examples map to Angular-native composition: put `routerLink` or `href` directly on `<a BreadcrumbLink>`.

## Source parity

This Angular implementation follows the shadcn breadcrumb information architecture while translating React-specific patterns such as `asChild` and dropdown composition into Angular RouterLink, button, and menu primitives.
