forty-cdk 0.25.2 → 0.27.0

package/accordion/README.md

@@ -9,6 +9,12 @@ apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
 
 A stack of collapsible sections, optionally allowing multiple panels open at once.
 
+## When to choose
+
+- **Accordion**: a group of collapsible items under one root. `[(value)]` holds which are open, `multiple` decides whether more than one may be, and ArrowUp / ArrowDown / Home / End move focus across the triggers.
+- **[Disclosure](../disclosure/README.md)**: a single trigger and its region, with no shared state and no arrow-key navigation. Stacking several of them is not an accordion, and that is the right shape when the panels are unrelated.
+- **[Tabs](../tabs/README.md)**: when exactly one panel is ever visible and the panels are alternatives rather than sections the reader may open together.
+
 ## Anatomy
 
 ```html
@@ -25,8 +31,10 @@ A stack of collapsible sections, optionally allowing multiple panels open at onc
 
 ## Examples
 
+Open a panel with the pointer or `Enter`, move between headers with the arrow keys, and watch `data-state` flip on the item, its trigger and its content together.
+
 ```ts
-import { Component, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import {
   ForAccordion,
   ForAccordionContent,
@@ -34,43 +42,83 @@ import {
   ForAccordionTrigger,
 } from 'forty-cdk/accordion';
 
+interface AccordionEntry {
+  readonly value: string;
+  readonly title: string;
+  readonly body: string;
+}
+
 @Component({
-  selector: 'demo-faq',
+  selector: 'app-accordion-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ForAccordion, ForAccordionItem, ForAccordionTrigger, ForAccordionContent],
   template: `
-    <div forAccordion [(value)]="open" collapsible>
-      <div forAccordionItem value="shipping">
-        <h3>
-          <button type="button" forAccordionTrigger class="accordion-trigger">Shipping</button>
-        </h3>
-        <section forAccordionContent>Ships in 24h.</section>
-      </div>
-      <div forAccordionItem value="returns">
-        <h3>
-          <button type="button" forAccordionTrigger class="accordion-trigger">Returns</button>
-        </h3>
-        <section forAccordionContent>Free 30-day returns.</section>
-      </div>
+    <div forAccordion class="acc-root" [(value)]="value" collapsible>
+      @for (item of items; track item.value) {
+        <div forAccordionItem class="acc-item" [value]="item.value">
+          <h3 class="acc-heading">
+            <button type="button" forAccordionTrigger class="acc-trigger">
+              <span>{{ item.title }}</span>
+              <span class="chevron" aria-hidden="true"></span>
+            </button>
+          </h3>
+          <section forAccordionContent class="acc-content">
+            <div class="acc-inner">
+              <p>{{ item.body }}</p>
+            </div>
+          </section>
+        </div>
+      }
     </div>
   `,
 })
-export class DemoFaq {
-  readonly open = signal<readonly string[]>([]);
+export class AccordionDefaultExample {
+  protected readonly items: readonly AccordionEntry[] = [
+    {
+      value: 'a',
+      title: 'What is forty-cdk?',
+      body: 'A library of headless UI primitives with built-in WAI-ARIA accessibility.',
+    },
+    {
+      value: 'b',
+      title: 'Does it ship styles?',
+      body: 'No. It exposes state, behavior, focus and ARIA; you apply the styles yourself.',
+    },
+    {
+      value: 'c',
+      title: 'Does it work without Zone.js?',
+      body: 'Yes, it is designed to run under provideZonelessChangeDetection().',
+    },
+  ];
+
+  protected readonly value = signal<readonly string[]>(['a']);
 }
 ```
 
+### Multiple
+
+`multiple` lets several sections stay open at once, so `value` holds an array of every open item.
+
+### Horizontal
+
+`orientation='horizontal'` lays the sections out in a row and switches roving navigation to `ArrowLeft` / `ArrowRight`. It is reflected as `data-orientation` for styling.
+
+### Disabled item
+
+A disabled item cannot be toggled and is skipped by the arrow keys, while staying in the DOM for screen readers.
+
 ## API
 
 ### `ForAccordion`
 
-| Property      | Type                                | Description                                                                                                                                                              |
-| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** —                                                                               |
-| `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously.<br>**Default:** `false`                                                                                            |
-| `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Otherwise once any item is open, exactly one stays open.<br>**Default:** `false`             |
-| `disabled`    | `input<boolean>`                    | When true, disables every item — each trigger reflects the native `disabled` attribute and cannot toggle. Composes with a per-item `[disabled]`.<br>**Default:** `false` |
-| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. In horizontal mode ArrowLeft/Right replace ArrowUp/Down.<br>**Default:** `'vertical'`                                              |
-| `dir`         | `input<'ltr' \| 'rtl'>`             | Writing direction. Only relevant in horizontal mode — swaps the meaning of Left/Right arrows.<br>**Default:** —                                                          |
+| Property      | Type                                | Description                                                                                                                                                             |
+| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** —                                                                              |
+| `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously.<br>**Default:** `false`                                                                                           |
+| `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Otherwise once any item is open, exactly one stays open.<br>**Default:** `false`            |
+| `disabled`    | `input<boolean>`                    | When true, disables every item: each trigger reflects the native `disabled` attribute and cannot toggle. Composes with a per-item `[disabled]`.<br>**Default:** `false` |
+| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. In horizontal mode ArrowLeft/Right replace ArrowUp/Down.<br>**Default:** `'vertical'`                                             |
+| `dir`         | `input<'ltr' \| 'rtl'>`             | Writing direction. Only relevant in horizontal mode, where it swaps the meaning of Left/Right arrows.<br>**Default:** —                                                 |
 
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |
@@ -106,35 +154,35 @@ export class DemoFaq {
 
 ## Keyboard
 
-| Key                                          | Action                                                                                             |
-| -------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| <kbd>Enter</kbd> / <kbd>Space</kbd>          | Toggle the focused trigger (native button).                                                        |
-| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>    | Move focus between triggers (vertical, default). Wrap-around, skips disabled.                      |
-| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Move focus between triggers (horizontal — flipped under `dir='rtl'`). Wrap-around, skips disabled. |
-| <kbd>Home</kbd>                              | Jump to the first trigger.                                                                         |
-| <kbd>End</kbd>                               | Jump to the last trigger.                                                                          |
+| Key                                          | Action                                                                                            |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>          | Toggle the focused trigger (native button).                                                       |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>    | Move focus between triggers (vertical, default). Wrap-around, skips disabled.                     |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowRight</kbd> | Move focus between triggers (horizontal, flipped under `dir='rtl'`). Wrap-around, skips disabled. |
+| <kbd>Home</kbd>                              | Jump to the first trigger.                                                                        |
+| <kbd>End</kbd>                               | Jump to the last trigger.                                                                         |
 
 ## Accessibility
 
-- **Heading wrapper is your job.** The library does not render a heading around the trigger — wrap it in the heading level (`<h2>`–`<h6>`) appropriate to your document outline. Without it, screen-reader landmark navigation is broken.
+- **Heading wrapper is your job.** The library does not render a heading around the trigger, so wrap it in the heading level (`<h2>`–`<h6>`) appropriate to your document outline. Without it, screen-reader landmark navigation is broken.
 - **Use a real `<button type="button">` for the trigger.** Native Enter / Space activation and focus come for free; the directive does not synthesize them.
 - **`role="region"`** is added to every panel automatically. APG recommends suppressing it on accordions with 6+ panels to avoid landmark proliferation; there is currently no opt-out.
 - **Closed panels leave the accessibility tree.** While closed, `ForAccordionContent` sets `aria-hidden="true"` and `inert` on the panel, removing it from both the accessibility tree and the focus order. The directive does **not** apply `[hidden]`, so pick how to hide it visually:
-  - **Mount / unmount with `@if (item.expanded())`** — the panel is absent from the DOM while closed; the cleanest path for `animate.enter` / `animate.leave`. The trigger emits `aria-controls` only while expanded, so the reference never dangles at an unmounted panel.
-  - **Leave it mounted** — preserve internal state or run CSS-only transitions off `data-state`. Add `display: none` (or your own collapse animation) keyed on `[data-state="closed"]` to also hide it visually.
+  - **Mount / unmount with `@if (item.expanded())`**: the panel is absent from the DOM while closed; the cleanest path for `animate.enter` / `animate.leave`. The trigger emits `aria-controls` only while expanded, so the reference never dangles at an unmounted panel.
+  - **Leave it mounted**: preserve internal state or run CSS-only transitions off `data-state`. Add `display: none` (or your own collapse animation) keyed on `[data-state="closed"]` to also hide it visually.
 - **`aria-disabled`** is applied to the open trigger only when single mode is active and `collapsible=false`, indicating the user cannot collapse it from this trigger.
 - **A truly disabled item (`[disabled]` on `[forAccordionItem]`) uses the native `disabled` attribute on the trigger, by design.** The trigger is a real single-purpose `<button>`, not a roving-tabindex collection item (each trigger stays independently in the Tab order; arrow-key navigation is the APG-optional enhancement on top). The disabled trigger leaves the Tab order and the arrow-key navigation (which already skips it), but stays in the accessibility tree so screen readers announce it as unavailable in browse mode. The [APG Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) does not require disabled headers to remain focusable.
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
 
 ```css
-.trigger-chevron {
+.chevron {
   transition: transform 150ms ease;
 }
 
-.accordion-trigger[data-state='open'] .trigger-chevron {
+.acc-trigger[data-state='open'] .chevron {
   transform: rotate(180deg);
 }
 ```

package/aspect-ratio/README.md

@@ -8,21 +8,21 @@ archetype: [composable-ui]
 
 A container that keeps its content at a fixed width-to-height ratio.
 
-Pure visual utility — it locks an element's box via the native CSS `aspect-ratio` property, with no ARIA semantics. Reach for it to reserve space for media before it loads (preventing layout shift), keep cards on a grid uniform, or wrap responsive iframes.
+It is a pure visual utility that locks an element's box via the native CSS `aspect-ratio` property, with no ARIA semantics. Reach for it to reserve space for media before it loads (preventing layout shift), keep cards on a grid uniform, or wrap responsive iframes.
 
 ## Why this exists
 
-A fixed, never-changing ratio is one line of CSS — you don't need this primitive for that:
+You don't need this primitive for a fixed, never-changing ratio, which is one line of CSS:
 
 ```css
-.card-cover {
+.box {
   aspect-ratio: 16 / 9;
 }
 ```
 
 `[forAspectRatio]` earns its place when the ratio is **dynamic or must be validated**. It is more than the static declaration:
 
-- **Reactive `ratio` input.** Bind `[ratio]="ratio()"` and the host style recomputes as the value changes — no manual style writes.
+- **Reactive `ratio` input.** Bind `[ratio]="ratio()"` and the host style recomputes as the value changes, with no manual style writes.
 - **Invalid-value guarding.** `0`, negative, and non-finite ratios fall back to `1`, so a bad computed value never emits invalid CSS.
 - **SSR-safe.** The `aspect-ratio` style is bound declaratively (never touched imperatively), so it renders identically on the server and hydrates cleanly.
 - **Consistent headless API.** Same shape as the other primitives, so it composes the same way.
@@ -39,46 +39,29 @@ If your ratio is a literal constant, prefer the CSS property directly and keep t
 
 ## Examples
 
+Resize the preview and watch the frame hold its 16 / 9 ratio. The primitive writes the ratio and nothing else, so every border, colour and inset below is your own CSS.
+
 ```ts
-import { Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { ForAspectRatio } from 'forty-cdk/aspect-ratio';
 
 @Component({
-  selector: 'demo-aspect-ratio',
+  selector: 'app-aspect-ratio-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ForAspectRatio],
   template: `
-    <div forAspectRatio [ratio]="16 / 9" class="card-cover">
-      <img src="cover.jpg" alt="" />
-    </div>
-
-    <div forAspectRatio ratio="1" class="avatar">
-      <img src="me.jpg" alt="Me" />
-    </div>
-
-    <div forAspectRatio [ratio]="21 / 9" class="hero">
-      <video src="hero.mp4" autoplay loop muted></video>
+    <div forAspectRatio class="box" [ratio]="16 / 9">
+      <span class="label">16 / 9</span>
     </div>
   `,
-  styles: [
-    `
-      .card-cover,
-      .avatar,
-      .hero {
-        width: 100%;
-      }
-      .card-cover img,
-      .avatar img,
-      .hero video {
-        width: 100%;
-        height: 100%;
-        object-fit: cover;
-      }
-    `,
-  ],
 })
-export class DemoAspectRatio {}
+export class AspectRatioDefaultExample {}
 ```
 
+### Square (1 / 1)
+
+Set `ratio` to `1` to keep a box perfectly square at any width. That is handy for avatars, thumbnails, or uniform grid cards.
+
 ## API
 
 ### `ForAspectRatio`
@@ -93,7 +76,7 @@ export class DemoAspectRatio {}
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). This primitive is purely structural: its only host effect is the native `aspect-ratio` style, so it reflects no `data-*` attributes and writes no CSS custom properties. Style the host through your own class on `[forAspectRatio]`.
+forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). This primitive is purely structural: its only host effect is the native `aspect-ratio` style, so it reflects no `data-*` attributes and writes no CSS custom properties. Style the host through your own class on `[forAspectRatio]`.
 
 ## Behavior notes
 

package/avatar/README.md

@@ -8,7 +8,7 @@ archetype: [composable-ui]
 
 A user image with a graceful fallback across its loading lifecycle.
 
-Headless and presentational — it tracks the load lifecycle of an `<img>` and lets you choose what to show while loading or after an error. There is no WAI-ARIA pattern for avatars, so the directive imposes no `role` of its own.
+It is headless and presentational: it tracks the load lifecycle of an `<img>` and lets you choose what to show while loading or after an error. There is no WAI-ARIA pattern for avatars, so the directive imposes no `role` of its own.
 
 ## Anatomy
 
@@ -22,52 +22,50 @@ Headless and presentational — it tracks the load lifecycle of an `<img>` and l
 
 ## Examples
 
+Let the image load, then break its URL: `data-status` moves between `loading`, `loaded` and `error`, and the fallback only appears once the delay has passed without an image.
+
 ```ts
-import { Component, signal } from '@angular/core';
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 import { ForAvatar, ForAvatarFallback, ForAvatarImage } from 'forty-cdk/avatar';
 
+const AVATAR_SRC =
+  'data:image/svg+xml;utf8,' +
+  encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="72" height="72" viewBox="0 0 72 72">
+      <defs>
+        <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+          <stop offset="0" stop-color="#6366f1" />
+          <stop offset="1" stop-color="#ec4899" />
+        </linearGradient>
+      </defs>
+      <rect width="72" height="72" fill="url(#g)" />
+      <circle cx="36" cy="28" r="14" fill="#fff" opacity="0.92" />
+      <path d="M14 64c0-12 9.8-20 22-20s22 8 22 20Z" fill="#fff" opacity="0.92" />
+    </svg>`,
+  );
+
 @Component({
-  selector: 'demo-avatar',
+  selector: 'app-avatar-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ForAvatar, ForAvatarImage, ForAvatarFallback],
   template: `
-    <span forAvatar #a="forAvatar" class="avatar" fallbackDelayMs="500">
-      <img forAvatarImage class="avatar-image" [src]="user.avatarUrl" [alt]="user.name" />
-      @if (a.shouldShowFallback()) {
-        <span forAvatarFallback class="avatar-fallback">{{ initials() }}</span>
+    <span forAvatar #avatar="forAvatar" class="avatar" [fallbackDelayMs]="500">
+      <img forAvatarImage class="avatar-image" [src]="src" alt="Ada Lovelace" />
+      @if (avatar.shouldShowFallback()) {
+        <span forAvatarFallback class="avatar-fallback">AL</span>
       }
     </span>
   `,
-  styles: [
-    `
-      .avatar {
-        display: inline-flex;
-        width: 40px;
-        height: 40px;
-        border-radius: 999px;
-        overflow: hidden;
-        background: #eee;
-        font: 600 14px/40px system-ui;
-        align-items: center;
-        justify-content: center;
-      }
-      .avatar-image {
-        width: 100%;
-        height: 100%;
-        object-fit: cover;
-      }
-      .avatar-image[data-status='loading'],
-      .avatar-image[data-status='error'] {
-        display: none;
-      }
-    `,
-  ],
 })
-export class DemoAvatar {
-  readonly user = { name: 'Ada Lovelace', avatarUrl: '/api/avatar/ada.jpg' };
-  readonly initials = signal('AL');
+export class AvatarDefaultExample {
+  protected readonly src = AVATAR_SRC;
 }
 ```
 
+### Failed load
+
+When the image errors, the directive flips `shouldShowFallback()` and the initials render in its place. An error shows the fallback at once, skipping the `fallbackDelayMs` wait.
+
 ## API
 
 ### `ForAvatar`
@@ -104,7 +102,7 @@ The directive does not impose a `role`. Pair the avatar with visible name text o
 
 ## Styling
 
-forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
+forty-cdk ships no styles. Add your own class to each piece. The `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes listed per piece in the [API](#api) section.
 
 ```css
 .avatar-image:not([data-status='loaded']) {
@@ -117,9 +115,9 @@ forty-cdk ships no styles. Add your own class to each piece — the `for*` selec
 
 ## Behavior notes
 
-- **Cached images are detected on first render.** If the browser already has the image cached, `load`/`error` may not fire — the directive checks `<img>.complete` and `naturalWidth` after the first render and reports `loaded` / `error` accordingly. A cached image that is `complete` but has zero intrinsic width (e.g. an SVG without explicit dimensions) is ambiguous, so the directive stays `loading` and confirms validity with `img.decode()` rather than pessimistically flagging `error`.
+- **Cached images are detected on first render.** If the browser already has the image cached, `load`/`error` may not fire. The directive checks `<img>.complete` and `naturalWidth` after the first render and reports `loaded` / `error` accordingly. A cached image that is `complete` but has zero intrinsic width (e.g. an SVG without explicit dimensions) is ambiguous, so the directive stays `loading` and confirms validity with `img.decode()` rather than pessimistically flagging `error`.
 - **Multiple images per avatar are not supported.** Each `[forAvatar]` expects exactly one `[forAvatarImage]`. If you need cascading sources (CDN → fallback URL → fallback content), swap `src` on a single image.
-- **`alt` is consumer territory.** Because `<img>` is the host element, the consumer keeps full control of `alt` — set `""` for purely decorative avatars next to a name, or describe the person if the avatar stands alone.
+- **`alt` is consumer territory.** Because `<img>` is the host element, the consumer keeps full control of `alt`. Set `""` for purely decorative avatars next to a name, or describe the person if the avatar stands alone.
 - **The image stays in the DOM.** Hide it via CSS `[data-status="loading"], [data-status="error"] { display: none }` if your consumer-side styling needs it gone. The fallback uses `@if`, so it only mounts when needed.
 
 ## Wrapping in a design system

package/breadcrumbs/README.md

@@ -23,34 +23,75 @@ A labelled navigation landmark for a breadcrumb trail: links with aria-current='
 
 ## Examples
 
+Walk the trail with `Tab`: the last crumb is the page you are on, so it carries `aria-current="page"` and is not a link back to itself.
+
 ```ts
-import { Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
 import { ForBreadcrumbItem, ForBreadcrumbSeparator, ForBreadcrumbs } from 'forty-cdk/breadcrumbs';
 
+interface Crumb {
+  readonly label: string;
+  readonly href: string;
+}
+
 @Component({
-  selector: 'demo-breadcrumbs',
+  selector: 'app-breadcrumbs-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [ForBreadcrumbs, ForBreadcrumbItem, ForBreadcrumbSeparator],
   template: `
-    <nav forBreadcrumbs>
-      <ol>
-        <li><a forBreadcrumbItem href="/">Home</a></li>
-        <li forBreadcrumbSeparator>/</li>
-        <li><a forBreadcrumbItem href="/library">Library</a></li>
-        <li forBreadcrumbSeparator>/</li>
-        <li><a forBreadcrumbItem href="/library/data" current>Data</a></li>
+    <nav forBreadcrumbs class="bc">
+      <ol class="bc-list">
+        @for (crumb of crumbs(); track crumb.href; let last = $last) {
+          <li class="bc-li">
+            <a
+              forBreadcrumbItem
+              class="bc-link"
+              [href]="crumb.href"
+              [current]="last"
+              (click)="$event.preventDefault()"
+            >
+              {{ crumb.label }}
+            </a>
+          </li>
+          @if (!last) {
+            <li forBreadcrumbSeparator class="bc-sep">
+              <svg viewBox="0 0 24 24" aria-hidden="true">
+                <path
+                  d="m8.25 4.5 7.5 7.5-7.5 7.5"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="1.75"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                />
+              </svg>
+            </li>
+          }
+        }
       </ol>
     </nav>
   `,
 })
-export class DemoBreadcrumbs {}
+export class BreadcrumbsDefaultExample {
+  protected readonly crumbs = signal<readonly Crumb[]>([
+    { label: 'Home', href: '/' },
+    { label: 'Components', href: '/components' },
+    { label: 'Navigation', href: '/components/navigation' },
+    { label: 'Breadcrumbs', href: '/components/navigation/breadcrumbs' },
+  ]);
+}
 ```
 
-The root defaults its label to `Breadcrumb`. Override it with `ariaLabel="…"` (or point a native `aria-labelledby` at a visible heading) when a page hosts more than one breadcrumb trail.
+### Collapsing a long trail
+
+The primitive renders whatever items you give it, so collapsing a deep path is a consumer decision. Here the middle is folded into an expandable ellipsis button that reveals the hidden crumbs. The trail stays a single accessible navigation landmark either way.
 
-### Localizing the label
+## Localizing the label
 
 `Breadcrumb` is verbalized by screen readers, so translate it per injector scope with `provideForBreadcrumbsDefaults`. Configure it at the application root, or in any component's `providers` to scope the translation to a subtree. A per-instance `[ariaLabel]` still wins over the scope default.
 
+<!-- snippet: fragment -->
+
 ```ts
 import { provideForBreadcrumbsDefaults } from 'forty-cdk/breadcrumbs';
 
@@ -77,7 +118,7 @@ bootstrapApplication(App, {
 
 Implements the [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/).
 
-- **Navigation landmark.** `[forBreadcrumbs]` applies `role="navigation"` and labels it `aria-label="Breadcrumb"` by default, creating a named landmark that screen-reader users can jump to directly.
+- **Navigation landmark.** `[forBreadcrumbs]` applies `role="navigation"` and labels it `aria-label="Breadcrumb"` by default, creating a named landmark that screen-reader users can jump to directly. When a page hosts more than one trail, name each with `[ariaLabel]`, or point a native `aria-labelledby` at a visible heading.
 - **Current page.** Set `current` on `[forBreadcrumbItem]` for the active page; the directive reflects `aria-current="page"` so assistive technology announces the user's location in the trail.
 - **Decorative separators.** `[forBreadcrumbSeparator]` reflects `aria-hidden="true"` so the visual divider (e.g. `/`) is skipped by screen readers.