forty-cdk 0.2.0 → 0.4.0

package/accordion/README.md

@@ -0,0 +1,122 @@
+# 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.
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  ForAccordion,
+  ForAccordionContent,
+  ForAccordionItem,
+  ForAccordionTrigger,
+} from 'forty-cdk/accordion';
+
+@Component({
+  selector: 'demo-faq',
+  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>
+  `,
+})
+export class DemoFaq {
+  readonly open = signal<readonly string[]>([]);
+}
+```
+
+## 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 below.
+
+### Data attributes
+
+| 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` |
+
+```css
+.trigger-chevron {
+  transition: transform 150ms ease;
+}
+
+.accordion-trigger[data-state='open'] .trigger-chevron {
+  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

@@ -0,0 +1,76 @@
+# AspectRatio
+
+Pure visual utility — locks an element's box to a fixed `width / height` ratio via the native CSS `aspect-ratio` property.
+
+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.
+
+## Pieces
+
+| 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`. |
+
+## Usage
+
+```ts
+import { Component } from '@angular/core';
+import { ForAspectRatio } from 'forty-cdk/aspect-ratio';
+
+@Component({
+  selector: 'demo-aspect-ratio',
+  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>
+  `,
+  styles: [
+    `
+      .card-cover,
+      .avatar,
+      .hero {
+        width: 100%;
+      }
+      .card-cover img,
+      .avatar img,
+      .hero video {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+    `,
+  ],
+})
+export class DemoAspectRatio {}
+```
+
+## Notes
+
+- **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>`, …).
+
+## 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
+
+| Piece              | Attribute | Values |
+| ------------------ | --------- | ------ |
+| `[forAspectRatio]` | _(none)_  | —      |

package/avatar/README.md

@@ -0,0 +1,100 @@
+# 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.
+
+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.
+
+## Pieces
+
+| 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"`.
+
+## Usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForAvatar, ForAvatarFallback, ForAvatarImage } from 'forty-cdk/avatar';
+
+@Component({
+  selector: 'demo-avatar',
+  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>
+  `,
+  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');
+}
+```
+
+## 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.
+
+## 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 below.
+
+### Data attributes
+
+| 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` |
+
+```css
+.avatar-image:not([data-status='loaded']) {
+  display: none;
+}
+.avatar-fallback[data-status='error'] {
+  color: #b00020;
+}
+```

package/breadcrumbs/README.md

@@ -0,0 +1,49 @@
+# 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.
+
+## Pieces
+
+| 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"`.          |
+
+## Usage
+
+```ts
+import { Component } from '@angular/core';
+import { ForBreadcrumbItem, ForBreadcrumbSeparator, ForBreadcrumbs } from 'forty-cdk/breadcrumbs';
+
+@Component({
+  selector: 'demo-breadcrumbs',
+  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>
+      </ol>
+    </nav>
+  `,
+})
+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.
+
+## Styling
+
+forty-cdk ships no styles. Style the current item via `[aria-current="page"]`.
+
+```css
+[forBreadcrumbItem][aria-current='page'] {
+  font-weight: bold;
+  color: inherit;
+  text-decoration: none;
+}
+```

package/breakpoints/README.md

@@ -0,0 +1,81 @@
+# 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.
+
+It is a headless reactive utility, not a UI primitive: no DOM, no ARIA, no template. Each query method returns a `Signal<boolean>`.
+
+## Setup
+
+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 { provideForBreakpoints } from 'forty-cdk/breakpoints';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideForBreakpoints({ mobile: 0, tablet: 640, laptop: 1024, desktop: 1280 })],
+};
+```
+
+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
+
+```ts
+import { Component, inject } from '@angular/core';
+import { injectBreakpoints } from 'forty-cdk/breakpoints';
+
+@Component({
+  selector: 'app-layout',
+  template: `
+    @if (isDesktop()) {
+      <aside>Sidebar</aside>
+    }
+    <main>Active breakpoint: {{ active() }}</main>
+  `,
+})
+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
+}
+```
+
+| 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
+protected columns = computed(() => (this.bp.up('xl')() ? 4 : this.bp.up('md')() ? 2 : 1));
+```
+
+## 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:
+
+```ts
+// breakpoints.ts
+export const appBreakpoints = {
+  mobile: 0,
+  tablet: 640,
+  laptop: 1024,
+  desktop: 1280,
+} as const;
+
+declare module 'forty-cdk' {
+  interface BreakpointRegistry extends Record<keyof typeof appBreakpoints, true> {}
+}
+```
+
+Now `injectBreakpoints()` autocompletes `'mobile' | 'tablet' | 'laptop' | 'desktop'` across the whole app.
+
+## 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

@@ -0,0 +1,49 @@
+# ForButton
+
+Headless implementation of the [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/).
+
+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`.
+
+## Basic usage
+
+```html
+<!-- Native button — platform handles Enter/Space → click synthesis -->
+<button forButton (activate)="save()">Save</button>
+
+<!-- Non-button host — role="button", tabindex="0", and keyboard activation added automatically -->
+<div forButton (activate)="save()">Save</div>
+```
+
+## Disabled
+
+Disabled buttons stay focusable so assistive technology can announce them. The native `disabled` attribute is never set; instead `aria-disabled="true"` is reflected.
+
+```html
+<button forButton [disabled]="isSaving()" (activate)="save()">Save</button>
+```
+
+## Preserve consumer `type`
+
+A native `<button>` without an explicit `type` attribute defaults to `type="button"`. A consumer-set `type="submit"` is preserved:
+
+```html
+<button type="submit" forButton>Submit form</button>
+```
+
+## Data attributes
+
+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.
+
+| 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) |
+
+## API
+
+| 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. |