forty-cdk 0.5.0 → 0.6.0

package/accordion/README.md

@@ -1,56 +1,22 @@
 # Accordion
 
-Headless implementation of the [WAI-ARIA Accordion pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/).
-A vertical stack of collapsible sections, each with a header button and a panel.
-
-## Pieces
-
-| Class                 | Selector                | Role                                                                                                 |
-| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
-| `ForAccordion`        | `[forAccordion]`        | Root. Owns the open `value`, the single/multiple mode, and the keyboard navigation between triggers. |
-| `ForAccordionItem`    | `[forAccordionItem]`    | One section. Requires a unique `value` string.                                                       |
-| `ForAccordionTrigger` | `[forAccordionTrigger]` | Header button. Wires ARIA + click + keyboard.                                                        |
-| `ForAccordionContent` | `[forAccordionContent]` | Panel. Adds `role="region"` + `aria-labelledby` automatically.                                       |
-
-## Inputs / outputs
-
-### `ForAccordion`
-
-| API           | Type                                | Description                                                                                                                                      |
-| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.                                                                         |
-| `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously. Defaults to `false`.                                                                       |
-| `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Defaults to `false` — once any item is open, exactly one stays open. |
-| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. Defaults to `'vertical'`; in horizontal mode ArrowLeft/Right replace ArrowUp/Down.                         |
-| `dir`         | `input<'ltr' \| 'rtl'>`             | Writing direction. Only relevant in horizontal mode — swaps the meaning of Left/Right arrows.                                                    |
-
-### `ForAccordionItem`
-
-| API        | Type                     | Description                                                                        |
-| ---------- | ------------------------ | ---------------------------------------------------------------------------------- |
-| `value`    | `input.required<string>` | Unique identifier within the accordion. Required.                                  |
-| `disabled` | `input<boolean>`         | When true, the trigger ignores clicks and exposes the native `disabled` attribute. |
-
-The host gets `data-state="open" \| "closed"` and `data-disabled` for CSS hooks.
-
-### `ForAccordionTrigger`
-
-Reflects on its host: `id`, `aria-expanded`, `aria-controls`, `aria-disabled` (when collapse is disallowed), `disabled` (real, when item is disabled), `data-state`. Toggles on click. Handles `ArrowDown` / `ArrowUp` / `Home` / `End` for navigation between triggers.
-
-`aria-controls` is emitted only while the item is expanded — mirroring the overlay triggers' open-only gating — so the reference never dangles at an unmounted panel under the recommended `@if (item.expanded())` mount pattern.
-
-Wrap it in a heading element (`<h2>`–`<h6>`) — APG requires that for landmark navigation. Use a real `<button type="button">` so Enter / Space activation comes for free.
-
-### `ForAccordionContent`
-
-Reflects on its host: `id`, `role="region"`, `aria-labelledby` (the trigger's id), `data-state`, `aria-hidden` (when closed), `inert` (when closed).
-
-The directive does **not** apply `[hidden]`. Two patterns work:
-
-- **Mount/unmount with `@if (item.expanded())`** — the panel is absent from the DOM while closed, which is the cleanest path for `animate.enter` / `animate.leave`.
-- **Leave it mounted** — preserve internal state or run CSS-only transitions off `data-state`. While closed, the directive sets `aria-hidden="true"` and `inert` on the host so the panel is removed from the accessibility tree and focus order. Add `display: none` (or your own collapse animation) keyed on `[data-state="closed"]` to also hide it visually.
+A stack of collapsible sections, optionally allowing multiple panels open at once.
+
+## Anatomy
+
+```html
+<div forAccordion>
+  <div forAccordionItem value="item-1">
+    <h3>
+      <button type="button" forAccordionTrigger>Trigger</button>
+    </h3>
+    <div forAccordionContent>Panel content</div>
+  </div>
+  <!-- repeat forAccordionItem per section -->
+</div>
+```
 
-## Example
+## Examples
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -86,22 +52,73 @@ export class DemoFaq {
 }
 ```
 
-## Styling
+## API
+
+### `ForAccordion`
 
-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 below.
+| 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` |
+| `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:** —                                              |
 
-### Data attributes
+| Data attribute     | Values                     |
+| ------------------ | -------------------------- |
+| `data-orientation` | `horizontal` \| `vertical` |
 
-| Piece                   | Attribute          | Values                     |
-| ----------------------- | ------------------ | -------------------------- |
-| `[forAccordion]`        | `data-orientation` | `horizontal` \| `vertical` |
-| `[forAccordionItem]`    | `data-state`       | `open` \| `closed`         |
-| `[forAccordionItem]`    | `data-disabled`    | present \| absent          |
-| `[forAccordionItem]`    | `data-orientation` | `horizontal` \| `vertical` |
-| `[forAccordionTrigger]` | `data-state`       | `open` \| `closed`         |
-| `[forAccordionTrigger]` | `data-orientation` | `horizontal` \| `vertical` |
-| `[forAccordionContent]` | `data-state`       | `open` \| `closed`         |
-| `[forAccordionContent]` | `data-orientation` | `horizontal` \| `vertical` |
+### `ForAccordionItem`
+
+| Property   | Type                     | Description                                                                                          |
+| ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `value`    | `input.required<string>` | Unique identifier within the accordion. Required.<br>**Default:** —                                  |
+| `disabled` | `input<boolean>`         | When true, the trigger ignores clicks and exposes the native `disabled` attribute.<br>**Default:** — |
+
+| Data attribute     | Values                     |
+| ------------------ | -------------------------- |
+| `data-state`       | `open` \| `closed`         |
+| `data-disabled`    | present \| absent          |
+| `data-orientation` | `horizontal` \| `vertical` |
+
+### `ForAccordionTrigger`
+
+| Data attribute     | Values                     |
+| ------------------ | -------------------------- |
+| `data-state`       | `open` \| `closed`         |
+| `data-orientation` | `horizontal` \| `vertical` |
+
+### `ForAccordionContent`
+
+| Data attribute     | Values                     |
+| ------------------ | -------------------------- |
+| `data-state`       | `open` \| `closed`         |
+| `data-orientation` | `horizontal` \| `vertical` |
+
+## 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.                                                                          |
+
+## 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.
+- **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. An opt-out input will be added to `ForAccordionContent` if this surfaces in real usage.
+- **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.
+- **`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.** This is the sanctioned exception in [rule #561](https://github.com/tutkli/forty-cdk/issues/561): 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.
 
 ```css
 .trigger-chevron {
@@ -112,11 +129,3 @@ forty-cdk ships no styles. Add your own class to each piece — the `for*` selec
   transform: rotate(180deg);
 }
 ```
-
-## Accessibility notes
-
-- **Heading wrapper is your job.** The library does not render a heading around the trigger — wrap it in the heading level appropriate to your document outline. Without it, screen-reader landmark navigation is broken.
-- **`role="region"`** is added to every panel automatically. APG recommends suppressing it on accordions with 6+ panels to avoid landmark proliferation. An opt-out input will be added to `ForAccordionContent` if this surfaces in real usage.
-- **Keyboard**: Enter and Space toggle the focused trigger (native button). ArrowDown / ArrowUp (vertical, default) or ArrowLeft / ArrowRight (horizontal — flipped under `dir='rtl'`) move focus between triggers (wrap-around, skip disabled). Home / End jump to the first/last trigger.
-- **`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.** This is the sanctioned exception in [rule #561](https://github.com/tutkli/forty-cdk/issues/561): 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.

package/aspect-ratio/README.md

@@ -1,22 +1,18 @@
 # AspectRatio
 
-Pure visual utility — locks an element's box to a fixed `width / height` ratio via the native CSS `aspect-ratio` property.
+A container that keeps its content at a fixed width-to-height ratio.
 
-No ARIA semantics. Use it to reserve space for media before it loads (preventing layout shift), to keep cards on a grid uniform, or to wrap responsive iframes.
+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.
 
-## Pieces
+## Anatomy
 
-| Class            | Selector           | Role                                                      |
-| ---------------- | ------------------ | --------------------------------------------------------- |
-| `ForAspectRatio` | `[forAspectRatio]` | Single attribute directive. Applies `style.aspect-ratio`. |
-
-## Inputs
-
-| API     | Type            | Description                                                                                                                                                                      |
-| ------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ratio` | `input<number>` | Width / height ratio (e.g. `16 / 9`, `4 / 3`, `1`). Accepts both numeric expressions and string attributes. Defaults to `1`. Non-positive or non-finite values fall back to `1`. |
+```html
+<div forAspectRatio [ratio]="16 / 9">
+  <!-- your content fills the box -->
+</div>
+```
 
-## Usage
+## Examples
 
 ```ts
 import { Component } from '@angular/core';
@@ -58,19 +54,25 @@ import { ForAspectRatio } from 'forty-cdk/aspect-ratio';
 export class DemoAspectRatio {}
 ```
 
-## Notes
+## API
 
-- **Browser support.** Native `aspect-ratio` is in Baseline 2021 (Chrome 88+, Firefox 89+, Safari 15+) — same target as Angular 20+, so no polyfill is needed.
-- **Width still on you.** The directive only sets `aspect-ratio`; you decide width / max-width / display. The height is computed from the ratio.
-- **Children fill the box.** Use `width: 100%; height: 100%; object-fit: cover` on inner media to fill without distortion. The directive imposes no styles on children.
-- **No role, no a11y.** This is a layout utility. The element it sits on keeps whatever semantics you give it (`<div>`, `<figure>`, `<a>`, …).
+### `ForAspectRatio`
+
+| Property | Type            | Description                                                                                                                                                                         |
+| -------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ratio`  | `input<number>` | Width / height ratio (e.g. `16 / 9`, `4 / 3`, `1`). Accepts both numeric expressions and string attributes. Non-positive or non-finite values fall back to `1`.<br>**Default:** `1` |
+
+| Data attribute     | Values  |
+| ------------------ | ------- |
+| `[forAspectRatio]` | present |
 
 ## 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]`.
 
-### Data attributes
+## Behavior notes
 
-| Piece              | Attribute | Values |
-| ------------------ | --------- | ------ |
-| `[forAspectRatio]` | _(none)_  | —      |
+- **Browser support.** Native `aspect-ratio` is in Baseline 2021 (Chrome 88+, Firefox 89+, Safari 15+) — same target as Angular 20+, so no polyfill is needed.
+- **Width still on you.** The directive only sets `aspect-ratio`; you decide width / max-width / display. The height is computed from the ratio.
+- **Children fill the box.** Use `width: 100%; height: 100%; object-fit: cover` on inner media to fill without distortion. The directive imposes no styles on children.
+- **No role, no a11y.** This is a layout utility. The element it sits on keeps whatever semantics you give it (`<div>`, `<figure>`, `<a>`, …).

package/avatar/README.md

@@ -1,29 +1,20 @@
 # Avatar
 
-Headless avatar that tracks the load lifecycle of an `<img>` and lets the consumer choose what to show during loading or after an error.
+A user image with a graceful fallback across its loading lifecycle.
 
-There is no WAI-ARIA pattern for "avatar" — it is a presentational composition. The directive does not impose a `role`; pair the avatar with visible name text or `aria-label` on the surrounding element when identity matters.
+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.
 
-## Pieces
+## Anatomy
 
-| Class               | Selector              | Role                                                                   |
-| ------------------- | --------------------- | ---------------------------------------------------------------------- |
-| `ForAvatar`         | `[forAvatar]`         | Root. Owns `status`, `shouldShowFallback`, and `fallbackDelayMs`.      |
-| `ForAvatarImage`    | `img[forAvatarImage]` | Observes the `<img>` and reports `idle \| loading \| loaded \| error`. |
-| `ForAvatarFallback` | `[forAvatarFallback]` | Marker for fallback content. Reflects `data-status`.                   |
-
-## Inputs / outputs / models
-
-| API                   | Type                      | Owner            | Description                                                                               |
-| --------------------- | ------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
-| `fallbackDelayMs`     | `input<number>`           | `ForAvatar`      | ms to wait before `shouldShowFallback()` flips to `true` while idle/loading. Default `0`. |
-| `status`              | `Signal<ForAvatarStatus>` | `ForAvatar`      | Read-only current status.                                                                 |
-| `shouldShowFallback`  | `Signal<boolean>`         | `ForAvatar`      | `true` when the consumer should render the fallback. Drives `@if`.                        |
-| `(loadStatusChanged)` | `output<ForAvatarStatus>` | `ForAvatarImage` | Emits whenever the lifecycle transitions.                                                 |
-
-The host element of every piece carries `data-status="idle" \| "loading" \| "loaded" \| "error"`.
+```html
+<span forAvatar #avatar="forAvatar">
+  <img forAvatarImage [src]="src" [alt]="name" />
+  <!-- rendered only when avatar.shouldShowFallback() is true -->
+  <span forAvatarFallback>{{ initials }}</span>
+</span>
+```
 
-## Usage
+## Examples
 
 ```ts
 import { Component, signal } from '@angular/core';
@@ -71,24 +62,43 @@ export class DemoAvatar {
 }
 ```
 
-## Notes
+## API
 
-- **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.
-- **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.
+### `ForAvatar`
 
-## Styling
+| Property             | Type                      | Description                                                                                      |
+| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ |
+| `fallbackDelayMs`    | `input<number>`           | ms to wait before `shouldShowFallback()` flips to `true` while idle/loading.<br>**Default:** `0` |
+| `status`             | `Signal<ForAvatarStatus>` | Read-only current status.<br>**Default:** —                                                      |
+| `shouldShowFallback` | `Signal<boolean>`         | `true` when the consumer should render the fallback. Drives `@if`.<br>**Default:** —             |
+
+| Data attribute | Values                                     |
+| -------------- | ------------------------------------------ |
+| `data-status`  | `idle` \| `loading` \| `loaded` \| `error` |
+
+### `ForAvatarImage`
+
+| Property              | Type                      | Description                                                         |
+| --------------------- | ------------------------- | ------------------------------------------------------------------- |
+| `(loadStatusChanged)` | `output<ForAvatarStatus>` | Output. Emits whenever the lifecycle transitions.<br>**Default:** — |
 
-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 below.
+| Data attribute | Values                                     |
+| -------------- | ------------------------------------------ |
+| `data-status`  | `idle` \| `loading` \| `loaded` \| `error` |
 
-### Data attributes
+### `ForAvatarFallback`
 
-| Piece                 | Attribute     | Values                                     |
-| --------------------- | ------------- | ------------------------------------------ |
-| `[forAvatar]`         | `data-status` | `idle` \| `loading` \| `loaded` \| `error` |
-| `img[forAvatarImage]` | `data-status` | `idle` \| `loading` \| `loaded` \| `error` |
-| `[forAvatarFallback]` | `data-status` | `idle` \| `loading` \| `loaded` \| `error` |
+| Data attribute | Values                                     |
+| -------------- | ------------------------------------------ |
+| `data-status`  | `idle` \| `loading` \| `loaded` \| `error` |
+
+## Accessibility
+
+The directive does not impose a `role`. Pair the avatar with visible name text or `aria-label` on the surrounding element when identity matters. Set `alt=""` on the `<img>` for purely decorative avatars next to a name, or provide a meaningful `alt` description if the avatar stands alone.
+
+## 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.
 
 ```css
 .avatar-image:not([data-status='loaded']) {
@@ -98,3 +108,10 @@ forty-cdk ships no styles. Add your own class to each piece — the `for*` selec
   color: #b00020;
 }
 ```
+
+## 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`.
+- **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.
+- **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.

package/breadcrumbs/README.md

@@ -1,16 +1,20 @@
 # Breadcrumbs
 
-Headless breadcrumb trail implementing the [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/): a labelled `navigation` landmark wrapping a set of links, with [`aria-current="page"`](https://www.w3.org/TR/wai-aria-1.2/#aria-current) on the current page and decorative separators hidden from assistive technology. Ships no styles — apply your own.
+A labelled navigation landmark for a breadcrumb trail: links with aria-current='page' on the current page and decorative separators hidden from assistive technology.
 
-## Pieces
+## Anatomy
 
-| Class                    | Selector                   | Role                                                                      |
-| ------------------------ | -------------------------- | ------------------------------------------------------------------------- |
-| `ForBreadcrumbs`         | `[forBreadcrumbs]`         | Root. `role="navigation"`, labelled `aria-label="Breadcrumb"` by default. |
-| `ForBreadcrumbItem`      | `[forBreadcrumbItem]`      | A link in the trail. Reflects `aria-current="page"` when `current`.       |
-| `ForBreadcrumbSeparator` | `[forBreadcrumbSeparator]` | Decorative divider between items. Reflects `aria-hidden="true"`.          |
+```html
+<nav forBreadcrumbs>
+  <ol>
+    <li><a forBreadcrumbItem href="/">Home</a></li>
+    <li forBreadcrumbSeparator>/</li>
+    <li><a forBreadcrumbItem href="/data" current>Data</a></li>
+  </ol>
+</nav>
+```
 
-## Usage
+## Examples
 
 ```ts
 import { Component } from '@angular/core';
@@ -36,6 +40,28 @@ export class DemoBreadcrumbs {}
 
 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.
 
+## API
+
+### `ForBreadcrumbs`
+
+| Property    | Type            | Description                                                                                                                               |
+| ----------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `ariaLabel` | `input<string>` | Accessible label for the `navigation` landmark. Override when a page hosts more than one breadcrumb trail.<br>**Default:** `'Breadcrumb'` |
+
+### `ForBreadcrumbItem`
+
+| Property  | Type             | Description                                                              |
+| --------- | ---------------- | ------------------------------------------------------------------------ |
+| `current` | `input<boolean>` | When true, reflects `aria-current="page"` on the link.<br>**Default:** — |
+
+## Accessibility
+
+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.
+- **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.
+
 ## Styling
 
 forty-cdk ships no styles. Style the current item via `[aria-current="page"]`.

package/breakpoints/README.md

@@ -1,8 +1,8 @@
 # Breakpoints
 
-A signal-first, zoneless, SSR-safe viewport breakpoint observer. Configure the breakpoint map **once** via a provider; read it anywhere with `injectBreakpoints()` — no need to repeat the breakpoint set at every call site.
+A signal-first, zoneless, SSR-safe viewport breakpoint observer (injectBreakpoints). Configure the breakpoint map once via provideForBreakpoints — or use the Tailwind scale by default — then read up / down / between / only / active or any arbitrary media query, each as a live Signal<boolean>.
 
-It is a headless reactive utility, not a UI primitive: no DOM, no ARIA, no template. Each query method returns a `Signal<boolean>`.
+It is a headless reactive utility, not a UI primitive: no DOM, no ARIA, no template. Configure the breakpoint map **once** via a provider; read it anywhere with `injectBreakpoints()` — no need to repeat the breakpoint set at every call site.
 
 ## Setup
 
@@ -18,7 +18,7 @@ export const appConfig: ApplicationConfig = {
 
 Providing it again on a component injector replaces the map for that subtree only (nearest scope wins; the map is replaced wholesale, never merged key-by-key).
 
-## Usage
+## Examples
 
 ```ts
 import { Component, inject } from '@angular/core';
@@ -41,15 +41,6 @@ export class Layout {
 }
 ```
 
-| Method           | Matches                                                                        |
-| ---------------- | ------------------------------------------------------------------------------ |
-| `up(name)`       | the breakpoint and wider — `(min-width: N px)`                                 |
-| `down(name)`     | narrower than the breakpoint — `(max-width: (N − 0.02) px)`                    |
-| `between(a, b)`  | from `a` (inclusive) up to but not including `b`                               |
-| `only(name)`     | the breakpoint's own band, up to but not including the next-larger one         |
-| `active`         | the largest breakpoint whose `min-width` matches, or `null` below the smallest |
-| `matches(query)` | escape hatch for an arbitrary media query (orientation, `prefers-*`, …)        |
-
 The returned handle captures its injection context, so the query methods can be called lazily from a `computed()` or a template, not only during construction:
 
 ```ts
@@ -76,6 +67,19 @@ declare module 'forty-cdk' {
 
 Now `injectBreakpoints()` autocompletes `'mobile' | 'tablet' | 'laptop' | 'desktop'` across the whole app.
 
+## API
+
+### `injectBreakpoints`
+
+| Method           | Matches                                                                        |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `up(name)`       | the breakpoint and wider — `(min-width: N px)`                                 |
+| `down(name)`     | narrower than the breakpoint — `(max-width: (N − 0.02) px)`                    |
+| `between(a, b)`  | from `a` (inclusive) up to but not including `b`                               |
+| `only(name)`     | the breakpoint's own band, up to but not including the next-larger one         |
+| `active`         | the largest breakpoint whose `min-width` matches, or `null` below the smallest |
+| `matches(query)` | escape hatch for an arbitrary media query (orientation, `prefers-*`, …)        |
+
 ## SSR
 
 On the server (or where `matchMedia` is unavailable) every query signal reads `false` and `active` reads `null`. No `matchMedia` access happens server-side, so the helper is safe under Angular Universal.

package/button/README.md

@@ -1,10 +1,22 @@
 # ForButton
 
-Headless implementation of the [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+Turns any element — a native <button> or a custom host like <div> / <span> — into an accessible button with keyboard activation. Disabled stays focusable (aria-disabled, never the native attribute) and pressed / hovered / focus-visible are reflected as data-\* hooks.
 
-A single `[forButton]` directive turns any element into an accessible, interactive button. It works on a native `<button>` host and on any non-button host (e.g. `<div>`, `<span>`). Install from `forty-cdk`.
+A single `[forButton]` directive does all of this. On a native `<button>` host the platform owns Enter/Space activation and `type` handling; on any non-button host the directive adds `role="button"`, `tabindex="0"`, and keyboard activation so the contract matches.
 
-## Basic usage
+## Anatomy
+
+```html
+<!-- Native button — platform owns Enter/Space and type handling -->
+<button forButton [disabled]="saving()" (activate)="save()">Save</button>
+
+<!-- Non-button host — role="button", tabindex="0", keyboard activation added -->
+<div forButton (activate)="save()">Save</div>
+```
+
+## Examples
+
+### Basic usage
 
 ```html
 <!-- Native button — platform handles Enter/Space → click synthesis -->
@@ -14,7 +26,7 @@ A single `[forButton]` directive turns any element into an accessible, interacti
 <div forButton (activate)="save()">Save</div>
 ```
 
-## Disabled
+### Disabled
 
 Disabled buttons stay focusable so assistive technology can announce them. The native `disabled` attribute is never set; instead `aria-disabled="true"` is reflected.
 
@@ -22,7 +34,7 @@ Disabled buttons stay focusable so assistive technology can announce them. The n
 <button forButton [disabled]="isSaving()" (activate)="save()">Save</button>
 ```
 
-## Preserve consumer `type`
+### Preserve consumer `type`
 
 A native `<button>` without an explicit `type` attribute defaults to `type="button"`. A consumer-set `type="submit"` is preserved:
 
@@ -30,20 +42,45 @@ A native `<button>` without an explicit `type` attribute defaults to `type="butt
 <button type="submit" forButton>Submit form</button>
 ```
 
-## Data attributes
+## API
 
-The directive reflects the following boolean `data-*` attributes (present with an empty-string value when true, absent when false). There is no `data-state` — this primitive has no open/closed or checked/unchecked logical state.
+### `ForButton`
 
-| Attribute            | When present                                    |
-| -------------------- | ----------------------------------------------- |
-| `data-disabled`      | `[disabled]="true"`                             |
-| `data-pressed`       | Primary pointer held down, or Enter/Space held  |
-| `data-hovered`       | Mouse/pen pointer is over the element           |
-| `data-focus-visible` | Focused via keyboard (keyboard modality active) |
+| Property   | Type             | Description                                                                                        |
+| ---------- | ---------------- | -------------------------------------------------------------------------------------------------- |
+| `disabled` | `input<boolean>` | Suppresses activation and reflects `aria-disabled` + `data-disabled`.<br>**Default:** `false`      |
+| `activate` | `output<void>`   | Fires once per user activation (click, Enter, Space). Never fires when disabled.<br>**Default:** — |
 
-## API
+The directive reflects boolean `data-*` attributes (present with an empty-string value when true, absent when false). There is no `data-state` — this primitive has no open/closed or checked/unchecked logical state.
 
-| Member     | Type             | Default | Description                                                                      |
-| ---------- | ---------------- | ------- | -------------------------------------------------------------------------------- |
-| `disabled` | `input<boolean>` | `false` | Suppresses activation and reflects `aria-disabled` + `data-disabled`.            |
-| `activate` | `output<void>`   | —       | Fires once per user activation (click, Enter, Space). Never fires when disabled. |
+| Data attribute       | Values            |
+| -------------------- | ----------------- |
+| `data-disabled`      | present \| absent |
+| `data-pressed`       | present \| absent |
+| `data-hovered`       | present \| absent |
+| `data-focus-visible` | present \| absent |
+
+`data-pressed` is present while the primary pointer is held down or Enter/Space is held. `data-hovered` is present while a mouse/pen pointer is over the element. `data-focus-visible` is present when focused via keyboard (keyboard modality active).
+
+## Accessibility
+
+Implements the [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+- **Native `<button>` semantics are preserved.** On a native host, no extra ARIA is added; the browser's built-in button role, Enter/Space activation, and `type` handling all apply.
+- **Non-button hosts get `role="button"` and `tabindex="0"`** plus keyboard activation (Enter/Space), matching the native button contract.
+- **Disabled buttons stay focusable.** `aria-disabled="true"` is used instead of the native `disabled` attribute so assistive technology can still announce the control's purpose.
+
+## 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.
+
+```css
+[forButton][data-disabled] {
+  opacity: 0.4;
+  pointer-events: none;
+}
+
+[forButton][data-pressed] {
+  transform: scale(0.97);
+}
+```