forty-cdk 0.25.2 → 0.26.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,31 +42,71 @@ 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`

package/aspect-ratio/README.md

@@ -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 — handy for avatars, thumbnails, or uniform grid cards.
+
 ## API
 
 ### `ForAspectRatio`

package/avatar/README.md

@@ -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`

package/breadcrumbs/README.md

@@ -23,34 +23,77 @@ 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.
 
-### Localizing the label
+### 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
 
 `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';
 

package/breakpoints/README.md

@@ -15,6 +15,7 @@ It is a headless reactive utility, not a UI primitive: no DOM, no ARIA, no templ
 Configuring is optional — without a provider the Tailwind scale (`sm` 640, `md` 768, `lg` 1024, `xl` 1280, `2xl` 1536) is used. To define your own:
 
 ```ts
+import { ApplicationConfig } from '@angular/core';
 import { provideForBreakpointsDefaults } from 'forty-cdk/breakpoints';
 
 export const appConfig: ApplicationConfig = {
@@ -28,33 +29,88 @@ Providing it again on a component injector replaces the map for that subtree onl
 
 ## Examples
 
+Resize the preview and watch the matched breakpoint change: `injectBreakpoints()` hands back signals, so the template re-renders without a listener of your own.
+
 ```ts
-import { Component, inject } from '@angular/core';
-import { injectBreakpoints } from 'forty-cdk/breakpoints';
+import {
+  afterNextRender,
+  ChangeDetectionStrategy,
+  Component,
+  DestroyRef,
+  inject,
+  signal,
+} from '@angular/core';
+import { forBreakpointsTailwind, injectBreakpoints } from 'forty-cdk/breakpoints';
+
+type TailwindName = keyof typeof forBreakpointsTailwind;
 
 @Component({
-  selector: 'app-layout',
+  selector: 'app-breakpoints-active-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
-    @if (isDesktop()) {
-      <aside>Sidebar</aside>
-    }
-    <main>Active breakpoint: {{ active() }}</main>
+    <div class="bp-demo">
+      <div class="bp-readout">
+        <span class="bp-readout-label">active breakpoint</span>
+        <span class="bp-active">{{ active() ?? 'below sm' }}</span>
+        <span class="bp-width">viewport ≈ {{ width() }}px</span>
+      </div>
+
+      <ul class="bp-grid">
+        @for (row of rows; track row.name) {
+          <li class="bp-cell" [class.bp-cell--on]="row.up()">
+            <span class="bp-name">{{ row.name }}</span>
+            <span class="bp-min">≥ {{ row.min }}px</span>
+            <span class="bp-flags">
+              <span class="bp-flag" [class.bp-flag--on]="row.up()">up</span>
+              <span class="bp-flag" [class.bp-flag--on]="row.only()">only</span>
+            </span>
+          </li>
+        }
+      </ul>
+    </div>
   `,
 })
-export class Layout {
-  private bp = injectBreakpoints();
-
-  protected isDesktop = this.bp.up('lg'); // (min-width: 1024px) and wider
-  protected active = this.bp.active; // 'sm' | 'md' | … | null
+export class BreakpointsActiveExample {
+  protected readonly bp = injectBreakpoints();
+  protected readonly active = this.bp.active;
+
+  protected readonly rows = (Object.keys(forBreakpointsTailwind) as TailwindName[]).map((name) => ({
+    name,
+    min: forBreakpointsTailwind[name],
+    up: this.bp.up(name),
+    only: this.bp.only(name),
+  }));
+
+  protected readonly width = signal(0);
+
+  constructor() {
+    const destroyRef = inject(DestroyRef);
+    afterNextRender(() => {
+      const onResize = (): void => this.width.set(globalThis.innerWidth);
+      onResize();
+      globalThis.addEventListener('resize', onResize, { passive: true });
+      destroyRef.onDestroy(() => globalThis.removeEventListener('resize', onResize));
+    });
+  }
 }
 ```
 
 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:
 
+<!-- snippet: fragment -->
+
 ```ts
 protected columns = computed(() => (this.bp.up('xl')() ? 4 : this.bp.up('md')() ? 2 : 1));
 ```
 
+### Responsive layout
+
+Derive UI from the breakpoint inside `computed()` and `@if` instead of repeating media queries in the template. The card grid picks its column count from `up('md')` / `up('lg')` / `up('xl')`, and the sidebar is only mounted at `lg` and wider.
+
+### Arbitrary media queries
+
+`matches(query)` is the escape hatch for any media feature the named width helpers don't cover — orientation, pointer, hover, and the `prefers-*` user settings. Each call returns a live `Signal<boolean>` from the same cached `MediaQueryList` layer.
+
 ## Typed custom names
 
 The default map gives you fully-typed names out of the box (`up('md')` autocompletes; `up('foo')` is a type error). When you provide a custom map, recover the same typing by augmenting `BreakpointRegistry` once — derive the keys from your map so you never write them twice:

package/button/README.md

@@ -23,17 +23,31 @@ A single `[forButton]` directive does all of this. On a native `<button>` host t
 
 ## Examples
 
-### Basic usage
+Press and hold either control — a native `<button>` and a `<span>` — and watch `data-pressed`, `data-hovered` and `data-focus-visible` appear on both, so one rule styles the pair.
+
+```ts
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ForButton } from 'forty-cdk/button';
+
+@Component({
+  selector: 'app-button-default-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [ForButton],
+  template: `
+    <div class="stage">
+      <button forButton class="btn btn--primary">Native &lt;button&gt;</button>
+      <span forButton class="btn">Custom &lt;span&gt;</span>
+    </div>
+  `,
+})
+export class ButtonDefaultExample {}
+```
 
-```html
-<!-- Native button — platform handles Enter/Space → click synthesis -->
-<button forButton (activate)="save()">Save</button>
+### Disabled stays focusable
 
-<!-- Non-button host — role="button", tabindex="0", and keyboard activation added automatically -->
-<div forButton (activate)="save()">Save</div>
-```
+Per the APG, a disabled button must stay reachable so assistive tech can announce it. `forButton` never sets the native `disabled` attribute — it reflects `aria-disabled='true'` + `data-disabled` and makes activation a no-op. The native disabled button is skipped entirely.
 
-### 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.
 
@@ -50,7 +64,7 @@ A surrounding disabled `[forFieldset]` disables the button too — its `disabled
 </fieldset>
 ```
 
-### 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:
 
@@ -78,12 +92,25 @@ The directive reflects boolean `data-*` attributes (present with an empty-string
 
 `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).
 
+## Keyboard
+
+On a native `<button>` host the platform owns activation: every key handler the directive binds returns immediately, and nothing in this table is its doing. On any other host (`<div forButton>`, `<span forButton>`) it synthesizes the activation itself, through the same `(click)` path a pointer takes — on a deliberately asymmetric split, because that is what a native button does.
+
+| Key                         | Action                                                                                                                                                                                                                                       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Enter` — native `<button>` | The platform synthesizes the click; the directive adds nothing.                                                                                                                                                                              |
+| `Enter` — any other host    | Activates on `keydown`, so `(activate)` fires while the key is still held. While disabled the event is left alone entirely — not even its default is prevented.                                                                              |
+| `Space` — native `<button>` | The platform synthesizes the click on release and suppresses the page scroll itself.                                                                                                                                                         |
+| `Space` — any other host    | Activates on `keyup`, and only when the matching `keydown` reached the same host — focus leaving mid-press drops the press. Its `keydown` always calls `preventDefault()` to stop the page scrolling, **even while the button is disabled**. |
+
+Both keys drive `data-pressed` on every host: present from `keydown` until `keyup`, until focus leaves, or until the pointer is released. `data-focus-visible` instead follows the keyboard modality, so a `keydown` carrying `Meta` / `Control` / `Alt` is read as a shortcut and does not turn it on, while `Shift` does.
+
 ## 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.
+- **Native `<button>` semantics are preserved.** On a native host, no extra ARIA is added; the browser's built-in button role, keyboard activation, and `type` handling all apply.
+- **Non-button hosts get `role="button"` and `tabindex="0"`**, and the directive synthesizes the activation the platform would have — see [Keyboard](#keyboard).
 - **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