@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/breadcrumb.json

@@ -0,0 +1,368 @@
+{
+  "family": "breadcrumb",
+  "ui": "breadcrumb",
+  "binding": "angular",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Trail of links to the current page's ancestors."
+  },
+  "axes": {
+    "overflow": [
+      "collapse",
+      "wrap"
+    ]
+  },
+  "members": {
+    "breadcrumb": {
+      "nativeElement": "nav",
+      "defaults": {
+        "maxItems": 8,
+        "itemsBeforeCollapse": 1,
+        "itemsAfterCollapse": 2,
+        "defaultExpanded": false,
+        "overflow": "collapse"
+      },
+      "capabilities": [
+        "open",
+        "wiring",
+        "overflow"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "expanded",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "list",
+        "item",
+        "link",
+        "page",
+        "trigger",
+        "separator",
+        "ellipsis"
+      ]
+    }
+  },
+  "docs": {
+    "breadcrumb": {
+      "imports": {
+        "source": "import {\n  SlBreadcrumb,\n  SlBreadcrumbItem,\n  SlBreadcrumbLink,\n  SlBreadcrumbList,\n  SlBreadcrumbPage,\n  SlBreadcrumbTrigger,\n  provideBreadcrumbDefaults,\n} from '@slotted/angular/breadcrumb';",
+        "selector": "nav[slBreadcrumb]",
+        "exportAs": "slBreadcrumb"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "nav[slBreadcrumb], exportAs=\"slBreadcrumb\"",
+          "required": true,
+          "purpose": "The consumer’s own nav, which is the navigation landmark and its name. Carries data-ui=\"breadcrumb\", data-expanded, and data-collapsed with the count of folded crumbs, and owns the collapse."
+        },
+        {
+          "part": "list",
+          "element": "ol[slBreadcrumbList], exportAs=\"slBreadcrumbList\"",
+          "required": true,
+          "purpose": "The ordered list, which is what carries the hierarchy and the set size. It queries its items and tells each one whether it is last or hidden by the count, inserts the ellipsis’s item in front of the first crumb that can fold, and, with overflow=\"collapse\", folds by its own width."
+        },
+        {
+          "part": "item",
+          "element": "li[slBreadcrumbItem], exportAs=\"slBreadcrumbItem\"",
+          "required": true,
+          "purpose": "One ancestor, or the current page. It renders the separator after itself, and carries hidden while the collapse hides it."
+        },
+        {
+          "part": "link",
+          "element": "a[slBreadcrumbLink], exportAs=\"slBreadcrumbLink\"",
+          "required": false,
+          "purpose": "An ancestor that can be reached. The directive sits on the consumer’s own anchor, so href and routerLink stay on the element they already belong to."
+        },
+        {
+          "part": "page",
+          "element": "[slBreadcrumbPage], exportAs=\"slBreadcrumbPage\"",
+          "required": false,
+          "purpose": "The page the reader is on, carrying aria-current=\"page\". Text rather than a link, because a link to this page goes nowhere."
+        },
+        {
+          "part": "trigger",
+          "element": "button[slBreadcrumbTrigger], exportAs=\"slBreadcrumbTrigger\"",
+          "required": false,
+          "purpose": "A crumb that opens a menu of its siblings, with a chevron after its label. slMenuTriggerFor composes on the same button; current keeps aria-current=\"page\" on the switcher of this page."
+        },
+        {
+          "part": "separator",
+          "element": "span",
+          "required": false,
+          "purpose": "Drawn between two crumbs, never after the last, never announced. Empty by default, when the stylesheet draws a rotated rule; a TemplateRef passed to the trail replaces it."
+        },
+        {
+          "part": "ellipsis",
+          "element": "button",
+          "required": false,
+          "purpose": "What the collapse hides, in an item of its own in front of the first crumb that can fold, and the control that reveals it. Its accessible name carries the count."
+        }
+      ],
+      "api": [
+        {
+          "name": "messages",
+          "type": "Partial<BreadcrumbMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slBreadcrumb",
+          "description": "Words laid over the language in force, key by key: the landmark’s name (label) and the ellipsis (showHidden)"
+        },
+        {
+          "name": "maxItems",
+          "type": "number",
+          "defaultValue": "8",
+          "appliesTo": "slBreadcrumb",
+          "description": "The count above which the trail folds; 0 never folds"
+        },
+        {
+          "name": "itemsBeforeCollapse",
+          "type": "number",
+          "defaultValue": "1",
+          "appliesTo": "slBreadcrumb",
+          "description": "How many crumbs survive at the start of a folded trail"
+        },
+        {
+          "name": "itemsAfterCollapse",
+          "type": "number",
+          "defaultValue": "2",
+          "appliesTo": "slBreadcrumb",
+          "description": "How many survive at its end"
+        },
+        {
+          "name": "expanded",
+          "type": "boolean | undefined",
+          "defaultValue": "—",
+          "appliesTo": "slBreadcrumb",
+          "description": "Present means controlled, for the life of the component"
+        },
+        {
+          "name": "defaultExpanded",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slBreadcrumb",
+          "description": "What an uncontrolled trail starts from, read once"
+        },
+        {
+          "name": "overflow",
+          "type": "'collapse' | 'wrap'",
+          "defaultValue": "collapse",
+          "appliesTo": "slBreadcrumb",
+          "description": "What the trail does with crumbs its width cannot hold: fold the middle into the ellipsis, or wrap"
+        },
+        {
+          "name": "separator",
+          "type": "TemplateRef<unknown>",
+          "defaultValue": "—",
+          "appliesTo": "slBreadcrumb",
+          "description": "The mark between two crumbs, rendered once per item. Absent, the stylesheet draws a rotated rule"
+        },
+        {
+          "name": "href, routerLink",
+          "type": "attribute or directive",
+          "defaultValue": "—",
+          "appliesTo": "slBreadcrumbLink",
+          "description": "The consumer’s own destination on the consumer’s own anchor; the directive claims none"
+        },
+        {
+          "name": "current",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slBreadcrumbTrigger",
+          "description": "The switcher of the page the reader is on: writes aria-current=\"page\" and takes the page weight"
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs=\"slBreadcrumb\"",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "Template",
+          "description": "Reaches the trail, for a template that needs to read the collapse or expand it from a control of its own"
+        },
+        {
+          "name": "routerLink, routerLinkActive",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "The same anchor",
+          "description": "The link directive claims no destination, so the router writes href on the anchor it already owns"
+        },
+        {
+          "name": "ng-content",
+          "type": "projection",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Each part projects the content the consumer wrote; only the separator, the ellipsis and a switcher’s chevron are rendered by the family"
+        },
+        {
+          "name": "slMenuTriggerFor",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "button[slBreadcrumbTrigger]",
+          "description": "Composes a menu on the switcher’s own button; the part it would erase is written back after the first render"
+        },
+        {
+          "name": "provideBreadcrumbDefaults",
+          "type": "maxItems | itemsBeforeCollapse | itemsAfterCollapse | overflow | separator",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets those five once for the whole injector; an input on the trail still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "expandedChange",
+          "payload": "ChangeRequest<boolean>",
+          "when": "Before the trail expands. The request carries the value it replaces, the reason — pointer or keyboard — and the originating event, and cancelling it commits nothing. It is not the second half of [(expanded)]: one slot can carry none of those."
+        }
+      ],
+      "accessibility": [
+        "The rendered elements are the consumer’s own nav and ol, which is the whole of the APG Breadcrumb pattern: it lists no keyboard interaction, and the two attributes it does list — a name on the landmark and aria-current=\"page\" on the last crumb — are written here rather than reimplemented.",
+        "A static aria-label the consumer wrote on the nav survives the host binding, read once through HostAttributeToken, so the family never overwrites a name an application already chose.",
+        "The current page is a span rather than a link, because a link to the page the reader is already on goes nowhere. The APG makes aria-current optional there; this family writes it anyway, so the end of the trail is announced as this page.",
+        "The separator is never announced. It is drawn as geometry in CSS — a rotated rule, not a character and not a glyph — which is the same reasoning the APG example gives, and it mirrors from :dir(rtl) so a trail inside a left-to-right island leans the way that island reads.",
+        "A crumb the collapse hides carries the hidden attribute, so it leaves the accessibility tree with the page. That is the cost of expanding in place rather than into an overlay, and it is paid by the ellipsis: its accessible name says how many crumbs it hides, and it carries aria-expanded.",
+        "A crumb the width folds is hidden the same way, and the ellipsis counts it with the others. Hiding only the label of a narrow crumb would leave the link named by nothing but an aria-hidden icon; a folded crumb is out of the tree whole, and the ellipsis says so.",
+        "A switcher is a button with aria-haspopup from the menu composed on it, and the switcher of this page keeps aria-current=\"page\", so the end of the trail is still announced as the current page when it opens a menu.",
+        "Pressing the ellipsis removes it, so focus is given to the first crumb it revealed — after the next render rather than after a microtask, because that crumb is still hidden while the handler runs. Focus on a removed element falls to the body, which is the defect that rule exists to prevent.",
+        "A crumb wider than the trail truncates with an ellipsis, and the full string stays in the DOM and in the accessible name — the repository rule for every truncation."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-width-thin",
+    "--slotted-breadcrumb-color",
+    "--slotted-breadcrumb-color-current",
+    "--slotted-breadcrumb-color-hover",
+    "--slotted-breadcrumb-content-gap",
+    "--slotted-breadcrumb-ellipsis-background-active",
+    "--slotted-breadcrumb-ellipsis-background-hover",
+    "--slotted-breadcrumb-ellipsis-focus-ring-offset",
+    "--slotted-breadcrumb-ellipsis-radius",
+    "--slotted-breadcrumb-focus-ring-offset",
+    "--slotted-breadcrumb-font-family",
+    "--slotted-breadcrumb-font-size",
+    "--slotted-breadcrumb-gap",
+    "--slotted-breadcrumb-item-measure",
+    "--slotted-breadcrumb-line-height",
+    "--slotted-breadcrumb-page-weight",
+    "--slotted-breadcrumb-radius",
+    "--slotted-breadcrumb-row-gap",
+    "--slotted-breadcrumb-separator-color",
+    "--slotted-breadcrumb-separator-length",
+    "--slotted-breadcrumb-separator-skew",
+    "--slotted-breadcrumb-separator-thickness",
+    "--slotted-breadcrumb-underline-offset",
+    "--slotted-breadcrumb-underline-thickness",
+    "--slotted-control-font-size-md",
+    "--slotted-control-gap-md",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-inner-size-md",
+    "--slotted-control-radius",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-width",
+    "--slotted-font-family-sans",
+    "--slotted-font-weight-medium",
+    "--slotted-line-height-md",
+    "--slotted-radius-full",
+    "--slotted-radius-xs",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Every input on one trail, driven by the controls below the canvas. Lower maxItems and watch which crumbs survive the fold.",
+      "language": "html",
+      "source": "<nav slBreadcrumb>\n  <ol slBreadcrumbList>\n    <li slBreadcrumbItem><a slBreadcrumbLink href=\"/workspace\">Workspace</a></li>\n    <li slBreadcrumbItem><span slBreadcrumbPage>INV-2026-08-0041</span></li>\n  </ol>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "collapse",
+      "title": "A trail that got too deep",
+      "note": "Above maxItems the middle folds behind one button, and pressing it expands the trail in place — no overlay, and focus lands on the first crumb it revealed.",
+      "language": "html",
+      "source": "<nav slBreadcrumb [maxItems]=\"4\" [itemsBeforeCollapse]=\"1\" [itemsAfterCollapse]=\"2\">\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n\n<!-- Or hold the choice yourself, and persist it. -->\n<nav slBreadcrumb [expanded]=\"open()\" (expandedChange)=\"open.set($event.value)\">\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "separator",
+      "title": "The mark between two crumbs",
+      "note": "Empty, the stylesheet draws a rotated rule that mirrors in a right-to-left document. A TemplateRef replaces the drawing without replacing the element.",
+      "language": "html",
+      "source": "<ng-template #mark>›</ng-template>\n\n<nav slBreadcrumb [separator]=\"mark\">\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "current",
+      "title": "The page you are on",
+      "note": "The last crumb carries aria-current=\"page\", which is the value the ARIA specification names for a link inside a set of pages. It gains weight rather than colour alone.",
+      "language": "html",
+      "source": "<li slBreadcrumbItem><span slBreadcrumbPage>INV-2026-08-0041</span></li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "context",
+      "title": "Above the page it describes",
+      "note": "Where a trail actually lives: over a heading, at the type size of the interface rather than of the page title. It is not a back button, and it never stands in for one.",
+      "language": "html",
+      "source": "<header>\n  <nav slBreadcrumb>\n    <ol slBreadcrumbList>\n      ...\n    </ol>\n  </nav>\n  <h1>INV-2026-08-0041</h1>\n</header>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the trail did not choose",
+      "note": "A German compound, a pasted identifier with no break opportunity, and a single-crumb trail. The row wraps before anything truncates, and a truncated string stays in the accessible name.",
+      "language": "html",
+      "source": "<li slBreadcrumbItem>\n  <a slBreadcrumbLink href=\"/settings\">Zahlungsabwicklungseinstellungen</a>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "The directives sit on the consumer’s own elements, so routerLink composes on the same anchor, and provideBreadcrumbDefaults decides the separator and the collapse for a whole application.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideBreadcrumbDefaults({ maxItems: 5 })],\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "switcher",
+      "title": "Crumbs that switch between siblings",
+      "note": "Organisation, ledger and period each open a menu of their siblings. The open one keeps its underline and turns its chevron, and the period the reader is on still says it is this page.",
+      "language": "html",
+      "source": "<li slBreadcrumbItem>\n  <button slBreadcrumbTrigger current [slMenuTriggerFor]=\"periods\">August 2026</button>\n  <sl-menu #periods>\n    <button slMenuItem>July 2026</button>\n    <button slMenuItem>August 2026</button>\n  </sl-menu>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "overflow",
+      "title": "A trail narrower than its crumbs",
+      "note": "Drag the column narrower: the middle crumbs fold into the ellipsis from the one nearest the root, the first and the last two stay, and the ellipsis names how many it holds. overflow=\"wrap\" breaks the row instead.",
+      "language": "html",
+      "source": "<nav slBreadcrumb>\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n\n<!-- Keep every crumb and let the row wrap. -->\n<nav slBreadcrumb overflow=\"wrap\">\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard and announcement",
+      "note": "Tab reaches every crumb and the ellipsis; Enter follows a crumb; Enter or Space on the ellipsis expands the trail and moves focus to the first crumb it revealed. A switcher takes the keys of the menu composed on it.",
+      "language": "html",
+      "source": "<!-- The landmark is named, the ellipsis says how many it hides,\n     and the last crumb says it is this page. -->\n<nav slBreadcrumb aria-label=\"Breadcrumb\" [maxItems]=\"4\">\n  <ol slBreadcrumbList>\n    ...\n  </ol>\n</nav>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/breadcrumb.md

@@ -0,0 +1,237 @@
+<!-- index: ./index.md -->
+# breadcrumb
+
+`data-ui="breadcrumb"` · Trail of links to the current page's ancestors.
+
+## Import
+
+```ts
+import {
+  SlBreadcrumb,
+  SlBreadcrumbItem,
+  SlBreadcrumbLink,
+  SlBreadcrumbList,
+  SlBreadcrumbPage,
+  SlBreadcrumbTrigger,
+  provideBreadcrumbDefaults,
+} from '@slotted/angular/breadcrumb';
+```
+
+Selector: `nav[slBreadcrumb]` · exportAs: `slBreadcrumb`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<nav slBreadcrumb>
+  <ol slBreadcrumbList>
+    <li slBreadcrumbItem><a slBreadcrumbLink href="/workspace">Workspace</a></li>
+    <li slBreadcrumbItem><span slBreadcrumbPage>INV-2026-08-0041</span></li>
+  </ol>
+</nav>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | nav[slBreadcrumb], exportAs="slBreadcrumb" | yes |
+| `list` | ol[slBreadcrumbList], exportAs="slBreadcrumbList" | yes |
+| `item` | li[slBreadcrumbItem], exportAs="slBreadcrumbItem" | yes |
+| `link` | a[slBreadcrumbLink], exportAs="slBreadcrumbLink" | no |
+| `page` | [slBreadcrumbPage], exportAs="slBreadcrumbPage" | no |
+| `trigger` | button[slBreadcrumbTrigger], exportAs="slBreadcrumbTrigger" | no |
+| `separator` | span | no |
+| `ellipsis` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `messages` | `Partial<BreadcrumbMessages>` | — | slBreadcrumb | Words laid over the language in force, key by key: the landmark’s name (label) and the ellipsis (showHidden) |
+| `maxItems` | `number` | 8 | slBreadcrumb | The count above which the trail folds; 0 never folds |
+| `itemsBeforeCollapse` | `number` | 1 | slBreadcrumb | How many crumbs survive at the start of a folded trail |
+| `itemsAfterCollapse` | `number` | 2 | slBreadcrumb | How many survive at its end |
+| `expanded` | `boolean \| undefined` | — | slBreadcrumb | Present means controlled, for the life of the component |
+| `defaultExpanded` | `boolean` | false | slBreadcrumb | What an uncontrolled trail starts from, read once |
+| `overflow` | `'collapse' \| 'wrap'` | collapse | slBreadcrumb | What the trail does with crumbs its width cannot hold: fold the middle into the ellipsis, or wrap |
+| `separator` | `TemplateRef<unknown>` | — | slBreadcrumb | The mark between two crumbs, rendered once per item. Absent, the stylesheet draws a rotated rule |
+| `href, routerLink` | `attribute or directive` | — | slBreadcrumbLink | The consumer’s own destination on the consumer’s own anchor; the directive claims none |
+| `current` | `boolean` | false | slBreadcrumbTrigger | The switcher of the page the reader is on: writes aria-current="page" and takes the page weight |
+| `exportAs="slBreadcrumb"` | `template reference` | — | Template | Reaches the trail, for a template that needs to read the collapse or expand it from a control of its own |
+| `routerLink, routerLinkActive` | `directive` | — | The same anchor | The link directive claims no destination, so the router writes href on the anchor it already owns |
+| `ng-content` | `projection` | — | every part | Each part projects the content the consumer wrote; only the separator, the ellipsis and a switcher’s chevron are rendered by the family |
+| `slMenuTriggerFor` | `directive` | — | button[slBreadcrumbTrigger] | Composes a menu on the switcher’s own button; the part it would erase is written back after the first render |
+| `provideBreadcrumbDefaults` | `maxItems \| itemsBeforeCollapse \| itemsAfterCollapse \| overflow \| separator` | — | Application | Sets those five once for the whole injector; an input on the trail still wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `expandedChange` | `ChangeRequest<boolean>` | Before the trail expands. The request carries the value it replaces, the reason — pointer or keyboard — and the originating event, and cancelling it commits nothing. It is not the second half of [(expanded)]: one slot can carry none of those. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `overflow` | `collapse`, `wrap` | `collapse` |
+
+## Rules
+
+- The rendered elements are the consumer’s own nav and ol, which is the whole of the APG Breadcrumb pattern: it lists no keyboard interaction, and the two attributes it does list — a name on the landmark and aria-current="page" on the last crumb — are written here rather than reimplemented.
+- A static aria-label the consumer wrote on the nav survives the host binding, read once through HostAttributeToken, so the family never overwrites a name an application already chose.
+- The current page is a span rather than a link, because a link to the page the reader is already on goes nowhere. The APG makes aria-current optional there; this family writes it anyway, so the end of the trail is announced as this page.
+- The separator is never announced. It is drawn as geometry in CSS — a rotated rule, not a character and not a glyph — which is the same reasoning the APG example gives, and it mirrors from :dir(rtl) so a trail inside a left-to-right island leans the way that island reads.
+- A crumb the collapse hides carries the hidden attribute, so it leaves the accessibility tree with the page. That is the cost of expanding in place rather than into an overlay, and it is paid by the ellipsis: its accessible name says how many crumbs it hides, and it carries aria-expanded.
+- A crumb the width folds is hidden the same way, and the ellipsis counts it with the others. Hiding only the label of a narrow crumb would leave the link named by nothing but an aria-hidden icon; a folded crumb is out of the tree whole, and the ellipsis says so.
+- A switcher is a button with aria-haspopup from the menu composed on it, and the switcher of this page keeps aria-current="page", so the end of the trail is still announced as the current page when it opens a menu.
+- Pressing the ellipsis removes it, so focus is given to the first crumb it revealed — after the next render rather than after a microtask, because that crumb is still hidden while the handler runs. Focus on a removed element falls to the body, which is the defect that rule exists to prevent.
+- A crumb wider than the trail truncates with an ellipsis, and the full string stays in the DOM and in the accessible name — the repository rule for every truncation.
+
+## Tokens
+
+`--slotted-border-width-thin`, `--slotted-breadcrumb-color`, `--slotted-breadcrumb-color-current`, `--slotted-breadcrumb-color-hover`, `--slotted-breadcrumb-content-gap`, `--slotted-breadcrumb-ellipsis-background-active`, `--slotted-breadcrumb-ellipsis-background-hover`, `--slotted-breadcrumb-ellipsis-focus-ring-offset`, `--slotted-breadcrumb-ellipsis-radius`, `--slotted-breadcrumb-focus-ring-offset`, `--slotted-breadcrumb-font-family`, `--slotted-breadcrumb-font-size`, `--slotted-breadcrumb-gap`, `--slotted-breadcrumb-item-measure`, `--slotted-breadcrumb-line-height`, `--slotted-breadcrumb-page-weight`, `--slotted-breadcrumb-radius`, `--slotted-breadcrumb-row-gap`, `--slotted-breadcrumb-separator-color`, `--slotted-breadcrumb-separator-length`, `--slotted-breadcrumb-separator-skew`, `--slotted-breadcrumb-separator-thickness`, `--slotted-breadcrumb-underline-offset`, `--slotted-breadcrumb-underline-thickness`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-icon-size-md`, `--slotted-control-inner-size-md`, `--slotted-control-radius`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-weight-medium`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-radius-xs`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### A trail that got too deep
+
+Above maxItems the middle folds behind one button, and pressing it expands the trail in place — no overlay, and focus lands on the first crumb it revealed.
+
+Excerpt — not a complete module
+
+```html
+<nav slBreadcrumb [maxItems]="4" [itemsBeforeCollapse]="1" [itemsAfterCollapse]="2">
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+
+<!-- Or hold the choice yourself, and persist it. -->
+<nav slBreadcrumb [expanded]="open()" (expandedChange)="open.set($event.value)">
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+```
+
+### The mark between two crumbs
+
+Empty, the stylesheet draws a rotated rule that mirrors in a right-to-left document. A TemplateRef replaces the drawing without replacing the element.
+
+Excerpt — not a complete module
+
+```html
+<ng-template #mark>›</ng-template>
+
+<nav slBreadcrumb [separator]="mark">
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+```
+
+### The page you are on
+
+The last crumb carries aria-current="page", which is the value the ARIA specification names for a link inside a set of pages. It gains weight rather than colour alone.
+
+Excerpt — not a complete module
+
+```html
+<li slBreadcrumbItem><span slBreadcrumbPage>INV-2026-08-0041</span></li>
+```
+
+### Above the page it describes
+
+Where a trail actually lives: over a heading, at the type size of the interface rather than of the page title. It is not a back button, and it never stands in for one.
+
+Excerpt — not a complete module
+
+```html
+<header>
+  <nav slBreadcrumb>
+    <ol slBreadcrumbList>
+      ...
+    </ol>
+  </nav>
+  <h1>INV-2026-08-0041</h1>
+</header>
+```
+
+### Content the trail did not choose
+
+A German compound, a pasted identifier with no break opportunity, and a single-crumb trail. The row wraps before anything truncates, and a truncated string stays in the accessible name.
+
+Excerpt — not a complete module
+
+```html
+<li slBreadcrumbItem>
+  <a slBreadcrumbLink href="/settings">Zahlungsabwicklungseinstellungen</a>
+</li>
+```
+
+### Composition
+
+The directives sit on the consumer’s own elements, so routerLink composes on the same anchor, and provideBreadcrumbDefaults decides the separator and the collapse for a whole application.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideBreadcrumbDefaults({ maxItems: 5 })],
+});
+```
+
+### Crumbs that switch between siblings
+
+Organisation, ledger and period each open a menu of their siblings. The open one keeps its underline and turns its chevron, and the period the reader is on still says it is this page.
+
+Excerpt — not a complete module
+
+```html
+<li slBreadcrumbItem>
+  <button slBreadcrumbTrigger current [slMenuTriggerFor]="periods">August 2026</button>
+  <sl-menu #periods>
+    <button slMenuItem>July 2026</button>
+    <button slMenuItem>August 2026</button>
+  </sl-menu>
+</li>
+```
+
+### A trail narrower than its crumbs
+
+Drag the column narrower: the middle crumbs fold into the ellipsis from the one nearest the root, the first and the last two stay, and the ellipsis names how many it holds. overflow="wrap" breaks the row instead.
+
+Excerpt — not a complete module
+
+```html
+<nav slBreadcrumb>
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+
+<!-- Keep every crumb and let the row wrap. -->
+<nav slBreadcrumb overflow="wrap">
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+```
+
+### Keyboard and announcement
+
+Tab reaches every crumb and the ellipsis; Enter follows a crumb; Enter or Space on the ellipsis expands the trail and moves focus to the first crumb it revealed. A switcher takes the keys of the menu composed on it.
+
+Excerpt — not a complete module
+
+```html
+<!-- The landmark is named, the ellipsis says how many it hides,
+     and the last crumb says it is this page. -->
+<nav slBreadcrumb aria-label="Breadcrumb" [maxItems]="4">
+  <ol slBreadcrumbList>
+    ...
+  </ol>
+</nav>
+```