@malva-ui/core 0.1.12

package/docs/ai/badge.md

@@ -0,0 +1,163 @@
+# Library: badge
+
+## Overview
+
+The Badge library (`@malva-ui/core/badge`) provides a compact `mlv-badge` element component for displaying short status labels, counts, category tags, and other inline metadata. It uses the new design system color tokens — `--mlv-color-*` for solid fills and `--mlv-color-*-muted-*-surface` / `--mlv-color-*-muted-*-text` for soft tinted modes — and integrates with the Malva UI density system via `MlvDensityDirective`.
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/badge`:
+
+| Export                 | Kind      | Description                                                                 |
+| ---------------------- | --------- | --------------------------------------------------------------------------- |
+| `MlvBadge`             | Component | `mlv-badge` — projects content, applies tone and muted styling              |
+| `MlvBadgeTone`         | Type      | `MlvTone \| 'default' \| 'primary' \| 'secondary' \| 'accent'`              |
+| `MlvBadgeIcon`         | Directive | `[mlvBadgeIcon]` — marks the projected icon slot; `position` picks the side |
+| `MlvBadgeIconPosition` | Type      | `'start' \| 'end'`                                                          |
+
+---
+
+## Components
+
+### `MlvBadge`
+
+**Selector:** `mlv-badge` | **Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+#### Inputs
+
+| Name                               | Type                      | Default     | Description                                                                                                           |
+| ---------------------------------- | ------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| `tone`                             | `MlvBadgeTone`            | `'default'` | Semantic tone. Maps to `--mlv-color-{tone}` (solid) or `--mlv-color-{tone}-muted-2-surface` (muted) for background.   |
+| `muted`                            | `BooleanInput`            | `false`     | When true, uses muted tint tokens instead of solid fill. Supports attribute syntax: `<mlv-badge muted>`.              |
+| `rounded`                          | `BooleanInput`            | `false`     | **Deprecated no-op.** Badges are always pill-shaped (`--mlv-radius-full`); kept only so `[rounded]` bindings compile. |
+| `mlvDensity` _(via hostDirective)_ | `MlvDensity \| undefined` | —           | Explicit density override; falls back to `MlvDensityService`.                                                         |
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-badge',
+  '[class]': '"mlv-badge--tone-" + tone()',
+  '[class.mlv-badge--muted]': 'muted()',
+  '[class.mlv-badge--with-icon]': '!!_iconRef()',
+}
+```
+
+#### Content Children (protected)
+
+| Name       | Directive      | Description                                                                                                                                        |
+| ---------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_iconRef` | `MlvBadgeIcon` | Presence-only — drives `mlv-badge--with-icon`, which is what turns on the label `gap`. Badges without an icon keep their previous spacing exactly. |
+
+#### Density
+
+Uses `MlvDensityDirective` as a `hostDirective` supporting all three levels (`compact`, `comfortable`, `spacious`). Provides `MLV_DENSITY_ELEMENT = 'badge'`.
+
+CSS density classes applied: `mlv-badge--compact`, `mlv-badge--comfortable`, `mlv-badge--spacious`.
+
+Density scales `padding-block` and `padding-inline` using the `density-scale()` SCSS mixin.
+
+#### Content Projection
+
+```html
+<ng-content select="[mlvBadgeIcon]" /> <ng-content />
+```
+
+Everything that is not marked `mlvBadgeIcon` lands in the default slot — text, numbers, or unmarked icons — exactly as before. The icon slot comes first in the template, so a projected icon is always the badge's first DOM child; `position="end"` moves it visually with CSS `order` rather than a second projection point.
+
+---
+
+## Directives
+
+### `MlvBadgeIcon`
+
+**Selector:** `[mlvBadgeIcon]`
+
+Marks a projected element as the badge's icon slot.
+
+| Name       | Type                   | Default   | Description                                                                        |
+| ---------- | ---------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `position` | `MlvBadgeIconPosition` | `'start'` | `'end'` adds `mlv-badge__icon--end` (CSS `order: 1`), rendering it after the label |
+
+```ts
+host: {
+  class: 'mlv-badge__icon',
+  '[class.mlv-badge__icon--end]': "position() === 'end'",
+  'aria-hidden': 'true',
+}
+```
+
+The icon is decorative by default — a badge normally repeats its meaning in the label. When the icon is the badge's only content, put an accessible name on the badge itself.
+
+Sizing is `width: var(--mlv-badge-icon-size); height: var(--mlv-badge-icon-size)`, which overrides the intrinsic `width`/`height` attributes an icon set ships with (`24px` for a Lucide default).
+
+---
+
+## Usage Examples
+
+```html
+<!-- Solid color variants -->
+<mlv-badge tone="success">Active</mlv-badge>
+<mlv-badge tone="danger">Error</mlv-badge>
+<mlv-badge tone="primary">New</mlv-badge>
+
+<!-- Muted (soft tint) -->
+<mlv-badge tone="warning" muted>Pending</mlv-badge>
+<mlv-badge tone="info" muted>Queued</mlv-badge>
+
+<!-- Dynamic binding -->
+<mlv-badge [tone]="task.statusTone" [muted]="useMuted">{{ task.status }}</mlv-badge>
+
+<!-- Density override -->
+<mlv-badge tone="primary" mlvDensity="compact">New</mlv-badge>
+
+<!-- Leading icon -->
+<mlv-badge tone="success" muted>
+  <svg lucideCheck mlvBadgeIcon />
+  Published
+</mlv-badge>
+
+<!-- Trailing icon -->
+<mlv-badge tone="info">
+  Syncing
+  <svg lucideRefreshCw mlvBadgeIcon position="end" />
+</mlv-badge>
+```
+
+---
+
+## CSS Custom Properties
+
+| Property                | Default                       | Description                                                                                            |
+| ----------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `--mlv-badge-bg`        | `var(--mlv-color-default)`    | Badge background; overridden by tone modifier                                                          |
+| `--mlv-badge-color`     | `var(--mlv-color-on-default)` | Badge text color; overridden by tone modifier                                                          |
+| `--mlv-badge-gap`       | `0.25rem`                     | Gap between the icon slot and the label; scaled per density, applied only under `mlv-badge--with-icon` |
+| `--mlv-badge-icon-size` | `1em`                         | Icon slot width/height; `em` so it tracks the density-driven font size                                 |
+
+---
+
+## Tone Token Mapping
+
+| `tone` value                   | Solid background      | Solid text               | Muted background                      | Muted text                         |
+| ------------------------------ | --------------------- | ------------------------ | ------------------------------------- | ---------------------------------- |
+| `default`                      | `--mlv-color-default` | `--mlv-color-on-default` | `--mlv-color-default-muted-2-surface` | `--mlv-color-default-muted-2-text` |
+| `primary`                      | `--mlv-color-primary` | `--mlv-color-on-primary` | `--mlv-color-primary-muted-2-surface` | `--mlv-color-primary-muted-2-text` |
+| `success`                      | `--mlv-color-success` | `--mlv-color-on-success` | `--mlv-color-success-muted-2-surface` | `--mlv-color-success-muted-2-text` |
+| _(others follow same pattern)_ |                       |                          |                                       |                                    |
+
+---
+
+## Dependencies
+
+| Package                 | Version   | Role                                         |
+| ----------------------- | --------- | -------------------------------------------- |
+| `@angular/core`         | `^22.0.0` | Signals, DI, component                       |
+| `@angular/cdk/coercion` | `^22.0.0` | `BooleanInput`, `coerceBooleanProperty`      |
+| `@malva-ui/cdk/density` | `*`       | `MlvDensityDirective`, `MLV_DENSITY_ELEMENT` |
+
+---
+
+## File Structure

package/docs/ai/bottom-nav.md

@@ -0,0 +1,267 @@
+# @malva-ui/bottom-nav
+
+All navigation overflow controls explicitly use `type="button"` to remain
+form-safe.
+
+**Import path:** `@malva-ui/core/bottom-nav`
+**Selector:** `mlv-bottom-nav`
+
+Fixed bottom navigation bar for mobile contexts. Renders up to 5 navigation items as icon + label links. When more than 5 items are provided, the first 4 are shown and the fifth slot becomes a "More" button that opens a menu with the overflow items. Supports two activation modes: router-based (default, uses `routerLink`/`routerLinkActive`) and managed (via `activeIndex` input + `itemClick` output). Items can be individually disabled. Typically paired with `*mlvBreakpointDown="'md'"` to show only on small viewports.
+
+---
+
+## Public API
+
+| Export                        | Kind      | Description                                             |
+| ----------------------------- | --------- | ------------------------------------------------------- |
+| `MlvBottomNav`                | Component | Mobile bottom navigation bar (`mlv-bottom-nav`)         |
+| `MlvBottomNavStacking`        | Type      | `'vertical' \| 'horizontal'` — item layout direction    |
+| `MlvBottomNavLabelVisibility` | Type      | `'always' \| 'active-only'` — label visibility strategy |
+
+---
+
+## Components
+
+### `MlvBottomNav`
+
+- **Selector:** `mlv-bottom-nav`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- 
+- 
+- **Host class:** `mlv-bottom-nav`
+- **Host role:** `navigation`
+
+#### Inputs
+
+| Name              | Type                          | Required | Default               | Description                                                                                                                                                        |
+| ----------------- | ----------------------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `items`           | `MlvNavItem[]`                | ✅       | —                     | Navigation items to display. Up to 5 shown; if more than 5 are provided, first 4 are rendered and a "More" button opens a menu with the overflow items.            |
+| `ariaLabel`       | `string`                      |          | `"Bottom navigation"` | Accessible label for the `navigation` landmark.                                                                                                                    |
+| `stacking`        | `MlvBottomNavStacking`        |          | `'vertical'`          | Layout direction for icon and label: `'vertical'` (icon above text) or `'horizontal'` (icon beside text, vertically centered).                                     |
+| `labelVisibility` | `MlvBottomNavLabelVisibility` |          | `'always'`            | When labels are visible: `'always'` (all items) or `'active-only'` (hidden by default, smoothly revealed on the active item). The "More" label is always visible.  |
+| `activeIndex`     | `number`                      |          | `undefined`           | Index of the active item. When provided, activates managed mode: items render as `<button>` instead of `<a routerLink>`, and active class is driven by this index. |
+
+#### Outputs
+
+| Name        | Type                | Description                                                                          |
+| ----------- | ------------------- | ------------------------------------------------------------------------------------ |
+| `itemClick` | `OutputRef<number>` | Emits the index of the clicked item in managed mode. Not emitted for disabled items. |
+
+#### Protected Properties
+
+| Property         | Type                           | Description                                                          |
+| ---------------- | ------------------------------ | -------------------------------------------------------------------- |
+| `_isManaged`     | `computed(() => boolean)`      | Whether the component is in managed (non-router) mode.               |
+| `_displayItems`  | `computed(() => MlvNavItem[])` | Items rendered as direct nav links. All if ≤ 5, first 4 if overflow. |
+| `_overflowItems` | `computed(() => MlvNavItem[])` | Items shown in the "More" menu. Empty if ≤ 5, items 5+ if overflow.  |
+| `_hasOverflow`   | `computed(() => boolean)`      | Whether there are overflow items requiring the "More" button.        |
+
+#### Protected Methods
+
+| Method                                        | Description                                                                      |
+| --------------------------------------------- | -------------------------------------------------------------------------------- |
+| `_onItemClick(index: number)`                 | Emits the clicked item's index on `itemClick` (managed mode).                    |
+| `_onOverflowItemClick(overflowIndex: number)` | Handles overflow menu item click — emits on `itemClick` or navigates via router. |
+
+#### Host Bindings
+
+| Binding                                     | Value                                  |
+| ------------------------------------------- | -------------------------------------- |
+| `class`                                     | `mlv-bottom-nav` (always)              |
+| `[class.mlv-bottom-nav--horizontal]`        | `stacking() === "horizontal"`          |
+| `[class.mlv-bottom-nav--label-active-only]` | `labelVisibility() === "active-only"`  |
+| `role`                                      | `navigation`                           |
+| `[attr.aria-label]`                         | `ariaLabel() \|\| "Bottom navigation"` |
+
+---
+
+## Template Structure
+
+```
+<!-- Inner container is a plain <div>: the host already provides the
+     role="navigation" landmark, so a nested <nav> would duplicate it. -->
+<div class="mlv-bottom-nav__bar">
+  @for (item of _displayItems(); track item.label) {
+    <a class="mlv-bottom-nav__item" [routerLink]="item.route"
+       routerLinkActive="mlv-bottom-nav__item--active"
+       ariaCurrentWhenActive="page" ...>
+      <svg class="mlv-bottom-nav__icon" [lucideIcon]="item.icon" ... />
+      <span class="mlv-bottom-nav__label">{{ item.label }}</span>
+    </a>
+  }
+
+  @if (_hasOverflow()) {
+    <button class="mlv-bottom-nav__item mlv-bottom-nav__more"
+            [mlvMenuTrigger]="overflowMenu" ...>
+      <svg class="mlv-bottom-nav__icon" lucideIcon="ellipsis" ... />
+      <span class="mlv-bottom-nav__label">More</span>
+    </button>
+
+    <mlv-menu #overflowMenu label="More navigation">
+      @for (item of _overflowItems(); track item.label) {
+        <mlv-list-item mlvMenuItem (itemClick)="_navigateTo(item.route)">
+          <svg mlvListItemPrefix [lucideIcon]="item.icon" ... />
+          {{ item.label }}
+        </mlv-list-item>
+      }
+    </mlv-menu>
+  }
+</nav>
+```
+
+- The single navigation landmark is the host element (`role="navigation"`). The inner bar is a plain `<div class="mlv-bottom-nav__bar">` — **not** a `<nav>` — to avoid duplicate nested landmarks.
+- Regular items are `<a>` elements with `routerLink` and `routerLinkActive`; `ariaCurrentWhenActive="page"` sets `aria-current="page"` on the active route link.
+- The "More" button is a `<button>` with `[mlvMenuTrigger]` that opens a `mlv-menu`.
+- Overflow menu items use `mlv-list-item[mlvMenuItem]` with programmatic navigation on click.
+- Icons use `LucideDynamicIcon` (`[lucideIcon]`) with `aria-hidden="true"`.
+
+---
+
+## CSS Classes (BEM)
+
+| Class                                | Description                                                                                               |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `.mlv-bottom-nav`                    | Host element — fixed bar at bottom of viewport                                                            |
+| `.mlv-bottom-nav--horizontal`        | Modifier: horizontal stacking (items in row layout instead of column)                                     |
+| `.mlv-bottom-nav--label-active-only` | Modifier: labels hidden by default, revealed on the active item with smooth animation                     |
+| `.mlv-bottom-nav__bar`               | Inner flex row (`display: flex; justify-content: space-around`)                                           |
+| `.mlv-bottom-nav__item`              | Individual navigation link or button (flex column by default, flex row when horizontal)                   |
+| `.mlv-bottom-nav__item--active`      | Applied by `routerLinkActive` (router mode) or `activeIndex` match (managed mode)                         |
+| `.mlv-bottom-nav__item--disabled`    | Visually muted (`--mlv-disabled-opacity`) and non-interactive (`pointer-events: none`)                    |
+| `.mlv-bottom-nav__more`              | Additional class on the "More" overflow button                                                            |
+| `.mlv-bottom-nav__icon`              | Icon wrapper (`display: flex; align-items: center`)                                                       |
+| `.mlv-bottom-nav__label`             | Text label (xs font size, no wrap); animated via `max-height`/`max-width` + `opacity` in active-only mode |
+| `.mlv-bottom-nav__label--always`     | Forces label to stay visible regardless of `label-active-only` mode (used on "More" button)               |
+
+---
+
+## Interactive States
+
+| State            | Visual feedback                                                  |
+| ---------------- | ---------------------------------------------------------------- |
+| `:hover`         | `--mlv-background-subtle` background, `--mlv-text-primary` color |
+| `:active`        | `--mlv-background-subtle` background, `scale(0.95)` transform    |
+| `--active`       | `--mlv-text-action` color (via `routerLinkActive`)               |
+| `:focus-visible` | `--mlv-border-focus` outline ring                                |
+
+---
+
+## Design Tokens Used
+
+| Token                          | Usage                                    |
+| ------------------------------ | ---------------------------------------- |
+| `--mlv-background-raised`      | Bar background                           |
+| `--mlv-background-subtle`      | Item hover/pressed background            |
+| `--mlv-border-subtle`          | Top border                               |
+| `--mlv-stroke-width`           | Top border width                         |
+| `--mlv-z-sticky` (`200`)       | Z-index so the bar overlays page content |
+| `--mlv-text-secondary`         | Default item color                       |
+| `--mlv-text-primary`           | Hovered item color                       |
+| `--mlv-text-action`            | Active item color                        |
+| `--mlv-radius-m`               | Item border radius (focus/hover shape)   |
+| `--mlv-duration-fast`          | Color/background/transform transition    |
+| `--mlv-duration-s`             | Label reveal animation duration          |
+| `--mlv-ease-default`           | Transition easing                        |
+| `--mlv-stroke-width-medium`    | Focus ring width                         |
+| `--mlv-border-focus`           | Focus ring color                         |
+| `--mlv-font-size-xs`           | Label font size                          |
+| `--mlv-line-height-tight`      | Label line height                        |
+| `--mlv-typography-family-text` | Font family (via `mixins.base()`)        |
+| `--mlv-font-size-m`            | Base font size (via `mixins.base()`)     |
+| `--mlv-disabled-opacity`       | Opacity for disabled items               |
+
+The bar uses `padding-bottom: env(safe-area-inset-bottom)` to account for notched devices (iPhone home indicator area).
+
+---
+
+## Usage Examples
+
+```ts
+import { MlvBottomNav } from '@malva-ui/core/bottom-nav';
+import { MlvBreakpointDown } from '@malva-ui/cdk/utils';
+import type { MlvNavItem } from '@malva-ui/cdk/utils';
+
+@Component({
+  imports: [MlvBottomNav, MlvBreakpointDown],
+})
+export class AppShellComponent {
+  readonly navItems: MlvNavItem[] = [
+    { icon: 'home', label: 'Home', route: '/home' },
+    { icon: 'search', label: 'Search', route: '/search' },
+    { icon: 'bell', label: 'Alerts', route: '/alerts', badge: 3 },
+    { icon: 'settings', label: 'Settings', route: '/settings' },
+  ];
+}
+```
+
+```html
+<!-- Show only below md breakpoint (tablet + desktop use sidebar instead) -->
+<mlv-bottom-nav *mlvBreakpointDown="'md'" [items]="navItems" ariaLabel="Main navigation" />
+```
+
+### Managed mode (no router)
+
+```ts
+readonly activeIndex = signal(0);
+
+readonly navItems: MlvNavItem[] = [
+  { icon: 'home',     label: 'Home',     route: '' },
+  { icon: 'search',   label: 'Search',   route: '' },
+  { icon: 'bell',     label: 'Alerts',   route: '', disabled: true },
+  { icon: 'settings', label: 'Settings', route: '' },
+];
+```
+
+```html
+<mlv-bottom-nav [items]="navItems" [activeIndex]="activeIndex()" (itemClick)="activeIndex.set($event)" />
+```
+
+### Horizontal stacking with active-only labels
+
+```html
+<mlv-bottom-nav [items]="navItems" stacking="horizontal" labelVisibility="active-only" />
+```
+
+### Overflow (more than 5 items)
+
+```ts
+readonly navItems: MlvNavItem[] = [
+  { icon: 'home',     label: 'Home',     route: '/home' },
+  { icon: 'search',   label: 'Search',   route: '/search' },
+  { icon: 'inbox',    label: 'Inbox',    route: '/inbox' },
+  { icon: 'calendar', label: 'Calendar', route: '/calendar' },
+  { icon: 'bell',     label: 'Alerts',   route: '/alerts' },
+  { icon: 'settings', label: 'Settings', route: '/settings' },
+  // 6 items → first 4 shown, "More" button opens menu with Alerts + Settings
+];
+```
+
+---
+
+## Accessibility
+
+- The host element is the sole `role="navigation"` landmark. The inner bar is a `<div>` (not a `<nav>`) so there is exactly one navigation landmark — nested `<nav>` inside a `role="navigation"` host would be a duplicate landmark.
+- `aria-label` defaults to `"Bottom navigation"` and can be customized via the `ariaLabel` input.
+- The active item is marked with `aria-current="page"`: router-mode links use `RouterLinkActive`'s `ariaCurrentWhenActive="page"`; managed-mode buttons bind `[attr.aria-current]="i === activeIndex() ? 'page' : null"`.
+- All icons have `aria-hidden="true"` — the visible `<span>` label provides the accessible name.
+- Items have `:hover`, `:active`, and `:focus-visible` visual states for interactive feedback.
+- The "More" button has `aria-haspopup="menu"` and `aria-expanded` (via `MlvMenuTrigger`).
+- The overflow menu uses `role="menu"` with `mlv-list-item[mlvMenuItem]` (`role="menuitem"`) and full keyboard navigation via `FocusKeyManager`.
+- Active state is communicated visually via `--mlv-text-action` color; `RouterLinkActive` also reflects the current route in the link's DOM state.
+
+---
+
+## Internationalization (i18n)
+
+Strings resolve through `MLV_BOTTOM_NAV_I18N` (`@malva-ui/i18n`): `navigation` (landmark `aria-label` fallback when the `ariaLabel` input is unset), `moreOptions` (overflow trigger `aria-label`), `more` (visible overflow-trigger label), and `moreMenu` (overflow `mlv-menu` accessible label). Provide `provideMlvI18nTesting()` in specs.
+
+## Dependencies
+
+- `@angular/core`
+- `@angular/router` — `Router`, `RouterLink`, `RouterLinkActive`
+- `@lucide/angular` — `LucideDynamicIcon`
+- `@malva-ui/cdk/utils` — `MlvNavItem` interface
+- `@malva-ui/core/menu` — `MlvMenu`, `MlvMenuItem`, `MlvMenuTrigger`
+- `@malva-ui/core/list` — `MlvListItem`, `MlvListItemPrefix`
+- `@malva-ui/styles` — design tokens

package/docs/ai/breadcrumb.md

@@ -0,0 +1,174 @@
+# Library: breadcrumb
+
+## Overview
+
+`@malva-ui/core/breadcrumb` provides a navigation breadcrumb component (`nav[mlvBreadcrumb]`) with configurable separator, overflow truncation for long paths, and Angular Router integration.
+
+Selector: `nav[mlvBreadcrumb]` — enhances the native `<nav>` element for proper landmark semantics and accessibility.
+
+**Two usage modes:**
+1. **Data-driven** — pass `MlvBreadcrumbEntry[]` via `[items]` input
+2. **Projected** — nest `<mlv-breadcrumb-item>` elements directly inside the `<nav>`
+
+---
+
+## Public API
+
+### `MlvBreadcrumb`
+
+**Selector:** `nav[mlvBreadcrumb]`
+**Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+#### Inputs
+
+| Name                             | Type                      | Default     | Description                                                                                                                                                                                                                  |
+| -------------------------------- | ------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`                          | `MlvBreadcrumbEntry[]`    | `[]`        | Data-driven list of breadcrumb items. Last item is automatically marked as current.                                                                                                                                          |
+| `maxItems`                       | `number`                  | `0`         | Max items to display before truncating. `0` = no truncation. Middle items collapse to `…`.                                                                                                                                   |
+| `mlvDensity`                     | `MlvDensity \| undefined` | `undefined` | Density for the overflow popover's item list. Forwarded to the overflow `mlv-popup`, which stamps `mlv--{density}` on the detached overlay panel (outside the page's density cascade). Omitted → global `MlvDensityService`. |
+| `hideSeparatorFromScreenReaders` | `BooleanInput`            | `true`      | When true, adds `aria-hidden="true"` to separators.                                                                                                                                                                          |
+
+There is **no `separator` input**. The separator is a projected template:
+`<ng-template mlvSeparator>` (`MlvBreadcrumbSeparator`) replaces the default
+`LucideChevronRight` icon for every gap.
+
+#### Host
+
+| Attribute    | Value            |
+| ------------ | ---------------- |
+| `class`      | `mlv-breadcrumb` |
+| `aria-label` | `'Breadcrumb'`   |
+
+---
+
+### `MlvBreadcrumbItem`
+
+**Selector:** `mlv-breadcrumb-item`
+**Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+#### Inputs
+
+| Name         | Type                         | Default | Description                                                                           |
+| ------------ | ---------------------------- | ------- | ------------------------------------------------------------------------------------- |
+| `routerLink` | `string \| string[] \| null` | `null`  | Angular router link for navigation.                                                   |
+| `href`       | `string \| null`             | `null`  | Raw href for anchor navigation.                                                       |
+| `current`    | `BooleanInput`               | `false` | Marks item as current page; renders as `<span>` with `aria-current="page"`.           |
+| `disabled`   | `BooleanInput`               | `false` | Disables navigation; renders as plain `<span>` with `mlv-breadcrumb__link--disabled`. |
+
+#### Host
+
+| Attribute | Value                  |
+| --------- | ---------------------- |
+| `class`   | `mlv-breadcrumb__item` |
+| `role`    | `listitem`             |
+
+---
+
+### `MlvBreadcrumbEntry` (interface)
+
+```ts
+interface MlvBreadcrumbEntry {
+  label: string;
+  routerLink?: string | string[];
+  href?: string;
+  disabled?: boolean;
+}
+```
+
+---
+
+## CSS Classes
+
+| Class                             | Description                                        |
+| --------------------------------- | -------------------------------------------------- |
+| `.mlv-breadcrumb`                 | Root block on `<nav>`                              |
+| `.mlv-breadcrumb__list`           | The `<ol>` ordered list wrapper                    |
+| `.mlv-breadcrumb__item`           | Each `<li>` breadcrumb item                        |
+| `.mlv-breadcrumb__link`           | Link or span inside each item                      |
+| `.mlv-breadcrumb__link--current`  | Applied to the current/last item (non-interactive) |
+| `.mlv-breadcrumb__link--disabled` | Applied to disabled items                          |
+| `.mlv-breadcrumb__separator`      | Separator between items                            |
+| `.mlv-breadcrumb__ellipsis`       | Ellipsis shown during overflow truncation          |
+
+---
+
+## Accessibility
+
+- `<nav>` host uses native landmark semantics
+- `aria-label="Breadcrumb"` on the host nav element
+- Last/current item has `aria-current="page"`
+- Separators are `aria-hidden="true"` by default
+- Disabled items are non-interactive `<span>` elements
+- All interactive links have `:focus-visible` outline using `--mlv-border-focus`
+- Uses semantic `<ol>` + `<li>` list structure in **data-driven** mode
+- Overflow popover focuses the first hidden link when opened
+- Overflow popover supports Arrow Up/Down/Left/Right, Home, End, and Escape keyboard navigation
+
+> **`MlvBreadcrumbItem` content projection** — the item template exposes a
+> single `<ng-content>` via a shared `#content` `ng-template` that is stamped
+> into whichever `@if` branch (`current`/`disabled`/`routerLink`/`href`/plain)
+> is active. Declaring a separate `<ng-content>` per branch left the active
+> branch empty (Angular projects into the first-declared slot only), which
+> rendered projected labels as empty links.
+>
+> **Known axe exception (`list`)** — in **projected** mode the `<ol>` directly
+> contains `<mlv-breadcrumb-item>` custom elements. axe's `list` rule wants
+> only `<li>` children. The item host deliberately does **not** claim
+> `role="listitem"` (a standalone item outside a list would be an orphan
+> listitem — see the `MlvBreadcrumbItem` spec), so this is an accepted
+> trade-off for the projected API; the data-driven API uses real `<li>` and is
+> clean.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Data-driven -->
+<nav mlvBreadcrumb [items]="breadcrumbs"></nav>
+
+<!-- Custom separator -->
+<nav mlvBreadcrumb [items]="breadcrumbs" separator="›"></nav>
+
+<!-- With truncation -->
+<nav mlvBreadcrumb [items]="longBreadcrumbs" [maxItems]="4"></nav>
+
+<!-- Projected items with router -->
+<nav mlvBreadcrumb>
+  <mlv-breadcrumb-item [routerLink]="['/']">Home</mlv-breadcrumb-item>
+  <mlv-breadcrumb-item [routerLink]="['/products']">Products</mlv-breadcrumb-item>
+  <mlv-breadcrumb-item [current]="true">Widget Pro</mlv-breadcrumb-item>
+</nav>
+
+<!-- Projected items with href -->
+<nav mlvBreadcrumb separator="→">
+  <mlv-breadcrumb-item href="/">Home</mlv-breadcrumb-item>
+  <mlv-breadcrumb-item href="/docs">Docs</mlv-breadcrumb-item>
+  <mlv-breadcrumb-item [current]="true">Getting Started</mlv-breadcrumb-item>
+</nav>
+```
+
+---
+
+## Internationalization (i18n)
+
+Strings resolve through `MLV_BREADCRUMB_I18N` (`@malva-ui/i18n`): `label` (the `<nav>` landmark `aria-label`), `hiddenItems` (overflow list `aria-label`), and `showMore` — an ICU plural (`"{count, plural, one {Show # more breadcrumb item} other {Show # more breadcrumb items}}"`) resolved via `MlvI18nResolverService` and exposed as the `_showMoreLabel` computed. Provide `provideMlvI18nTesting()` in specs.
+
+## Dependencies
+
+| Package                 | Version   | Role                                    |
+| ----------------------- | --------- | --------------------------------------- |
+| `@angular/core`         | `^20.0.0` | Signals, DI, component                  |
+| `@angular/router`       | `^20.0.0` | `RouterLink` for router integration     |
+| `@angular/cdk/coercion` | `^20.0.0` | `BooleanInput`, `coerceBooleanProperty` |
+
+---
+
+## File Structure
+
+---
+
+## Accessibility notes (updated)
+
+- Host now sets an explicit `role="navigation"` (in addition to `aria-label="Breadcrumb"`).
+- The overflow ellipsis trigger sets `[ariaHasPopup]="'menu'"` so `aria-haspopup` matches the `role="menu"` overflow list (the popup panel itself is roleless).