forty-cdk 0.2.0 → 0.3.0

package/slider/README.md

@@ -0,0 +1,152 @@
+# Slider
+
+Headless slider implementing the [WAI-ARIA Slider pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider/) (single thumb) and the [WAI-ARIA Slider (Multi-Thumb) pattern](https://www.w3.org/WAI/ARIA/apg/patterns/slider-multi-thumb/) (range / N thumbs). Implements `FormValueControl<readonly number[]>` from `@angular/forms/signals`.
+
+A single primitive supports single, range, and multi-thumb sliders — the shape comes from `value`'s array length and how many `[forSliderThumb]` you render.
+
+## Pieces
+
+| Class            | Selector           | Role                                                                                           |
+| ---------------- | ------------------ | ---------------------------------------------------------------------------------------------- |
+| `ForSlider`      | `[forSlider]`      | Root. Owns `[(value)]`, configuration, drag, form wiring.                                      |
+| `ForSliderTrack` | `[forSliderTrack]` | Track surface. PointerDown moves the nearest thumb and starts a drag.                          |
+| `ForSliderRange` | `[forSliderRange]` | Optional decorative band between min and the highest thumb (single) or between thumbs (multi). |
+| `ForSliderThumb` | `[forSliderThumb]` | One thumb. `role="slider"`, full ARIA, keyboard, and drag.                                     |
+
+## Single thumb
+
+```html
+<div forSlider [(value)]="volume">
+  <span forSliderTrack>
+    <span forSliderRange></span>
+    <span forSliderThumb [index]="0" [label]="'Volume'"></span>
+  </span>
+</div>
+```
+
+Where `volume = signal<readonly number[]>([50])`.
+
+## Range (two thumbs)
+
+```html
+<div forSlider [(value)]="priceRange" [min]="0" [max]="1000" [step]="10">
+  <span forSliderTrack>
+    <span forSliderRange></span>
+    <span forSliderThumb [index]="0" [label]="'Minimum price'"></span>
+    <span forSliderThumb [index]="1" [label]="'Maximum price'"></span>
+  </span>
+</div>
+```
+
+`priceRange = signal<readonly number[]>([200, 800])` — non-passing constraint is enforced automatically (the lower thumb can't go above the upper, and vice versa). Use `[minStepsBetweenThumbs]="1"` to force a minimum gap.
+
+## Inputs
+
+| Input                   | Default        | Description                                                                                                                                             |
+| ----------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`                   | `0`            | Numeric minimum.                                                                                                                                        |
+| `max`                   | `100`          | Numeric maximum.                                                                                                                                        |
+| `step`                  | `1`            | Discrete value increment for arrows + drag.                                                                                                             |
+| `largeStep`             | `10`           | Increment for `PageUp` / `PageDown`.                                                                                                                    |
+| `orientation`           | `'horizontal'` | `'horizontal'` or `'vertical'`.                                                                                                                         |
+| `dir`                   | `'ltr'`        | `'ltr'` or `'rtl'`. RTL flips horizontal pointer mapping and `ArrowLeft`/`ArrowRight` semantics.                                                        |
+| `inverted`              | `false`        | Visually flips the value-to-position mapping (e.g. max on the left in horizontal LTR). Keyboard `Up`/`Right` (LTR) still moves toward `max` regardless. |
+| `minStepsBetweenThumbs` | `0`            | Multi-thumb only: minimum gap between adjacent thumbs in step units.                                                                                    |
+| `disabled`              | `false`        | Disables all interaction.                                                                                                                               |
+| `readonly`              | `false`        | Allows focus + announcement, blocks updates.                                                                                                            |
+| `name`                  | `''`           | If non-empty, mirrors `value()` into N `<input type="hidden">` siblings for native form submit.                                                         |
+
+## Outputs
+
+`(valueChange)` (from `model<readonly number[]>`) fires only on internal updates (drag, keyboard, track click). It stays silent on consumer writes via `[(value)]`.
+
+`(valueCommit)` fires once at the trailing edge of a value-changing interaction with the final value array — on `pointerup` / `pointercancel` after a drag, or on `keyup` after one or more keyboard adjustments. Use it to defer expensive work (network calls, history undo entries) without throttling `(valueChange)`. Stays silent when the interaction did not actually change the value (e.g. press + release without movement, or arrow at the extreme).
+
+`(touchedChange)` fires when focus leaves the slider region the first time.
+
+## Keyboard
+
+Focus a thumb, then:
+
+| Key                                                            | Action                   |
+| -------------------------------------------------------------- | ------------------------ |
+| **ArrowRight** _(LTR)_ / **ArrowLeft** _(RTL)_ / **ArrowUp**   | Increase by `step`.      |
+| **ArrowLeft** _(LTR)_ / **ArrowRight** _(RTL)_ / **ArrowDown** | Decrease by `step`.      |
+| **PageUp**                                                     | Increase by `largeStep`. |
+| **PageDown**                                                   | Decrease by `largeStep`. |
+| **Home**                                                       | Set to `min`.            |
+| **End**                                                        | Set to `max`.            |
+
+`inverted` swaps "increase" / "decrease" on every key. Disabled and readonly thumbs are no-ops.
+
+## Form integration
+
+`[forSlider]` implements `FormValueControl<readonly number[]>`. Pair with `[formField]` for auto-wiring with `@angular/forms/signals`:
+
+```html
+<div forSlider [formField]="form.opacity">…</div>
+```
+
+For native `<form>` submit, set `[name]` and the directive mirrors `value()` into N `<input type="hidden">` siblings (one per thumb). `data-touched` / `data-dirty` / `data-pending` / `data-invalid` are reflected on the host as boolean `data-*` attributes (present when `true`, absent otherwise).
+
+## 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                     |
+| ------------------ | ------------------ | -------------------------- |
+| `[forSlider]`      | `data-orientation` | `horizontal` \| `vertical` |
+| `[forSlider]`      | `data-disabled`    | present \| absent          |
+| `[forSlider]`      | `data-readonly`    | present \| absent          |
+| `[forSlider]`      | `data-touched`     | present \| absent          |
+| `[forSlider]`      | `data-dirty`       | present \| absent          |
+| `[forSlider]`      | `data-pending`     | present \| absent          |
+| `[forSlider]`      | `data-invalid`     | present \| absent          |
+| `[forSliderTrack]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forSliderTrack]` | `data-disabled`    | present \| absent          |
+| `[forSliderRange]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forSliderRange]` | `data-disabled`    | present \| absent          |
+| `[forSliderThumb]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forSliderThumb]` | `data-disabled`    | present \| absent          |
+| `[forSliderThumb]` | `data-readonly`    | present \| absent          |
+| `[forSliderThumb]` | `data-index`       | 0-based thumb index        |
+
+### CSS custom properties
+
+| Property                      | Meaning                                                                                                            |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `--for-slider-thumb-position` | On `[forSliderThumb]`. Fraction `[0, 1]`, already accounting for `inverted`. The thumb's position along the track. |
+| `--for-slider-range-start`    | On `[forSliderRange]`. Lowest fraction `[0, 1]` (single: pinned to the closer edge; multi: smallest thumb).        |
+| `--for-slider-range-end`      | On `[forSliderRange]`. Highest fraction `[0, 1]`.                                                                  |
+| `--for-slider-range-size`     | On `[forSliderRange]`. `end - start`. Useful for `width` / `height`.                                               |
+
+Pair with `data-orientation` on every piece to pick the right axis from CSS.
+
+```css
+.thumb {
+  inset-inline-start: calc(var(--for-slider-thumb-position) * 100%);
+}
+
+.range {
+  inset-inline-start: calc(var(--for-slider-range-start) * 100%);
+  inline-size: calc(var(--for-slider-range-size) * 100%);
+}
+
+.thumb[data-disabled] {
+  opacity: 0.5;
+}
+```
+
+## Accessibility notes
+
+- `role="slider"` on each thumb with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, optional `aria-valuetext`, and `aria-orientation`.
+- Multi-thumb non-passing: each thumb's `aria-valuemin` / `aria-valuemax` automatically squeeze to its neighbors' values, matching the APG multi-thumb guidance.
+- The root has `role="group"` and `dir="rtl"` mirrored when `dir()==='rtl'`, so screen readers and CSS layout agree.
+- `disabled` thumbs receive `tabindex="-1"` and `aria-disabled="true"`.
+- Provide `[label]` (or `[labelledby]`) on every thumb — even single-thumb sliders benefit from explicit naming. The directive does not synthesize a label.
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_SLIDER_HOST_DIRECTIVE_INPUTS` / `FOR_SLIDER_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).

package/stepper/README.md

@@ -0,0 +1,292 @@
+# ForStepper
+
+A headless, accessible multi-step wizard primitive. Implements the
+[WAI-ARIA Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) in
+`mode="interactive"` (full roving tabindex, `role="tablist"`) and a progress
+list with `aria-current="step"` in `mode="progress"`.
+
+See [Styling forty-cdk](../../../../../docs/styling.md) for theming guidance.
+
+---
+
+## Pieces
+
+| Directive                    | Selector                       | Role (interactive / progress)           |
+| ---------------------------- | ------------------------------ | --------------------------------------- |
+| `ForStepper`                 | `[forStepper]`                 | root                                    |
+| `ForStepperList`             | `[forStepperList]`             | `tablist` / `list`                      |
+| `ForStepperItem`             | `[forStepperItem]`             | item container (wraps trigger + panel)  |
+| `ForStepperTrigger`          | `[forStepperTrigger]`          | `tab` / static (aria-current)           |
+| `ForStepperIndicator`        | `[forStepperIndicator]`        | decorative icon (`aria-hidden`)         |
+| `ForStepperSeparator`        | `[forStepperSeparator]`        | decorative connector (`aria-hidden`)    |
+| `ForStepperContent`          | `[forStepperContent]`          | `tabpanel` / `group`                    |
+| `ForStepperNext`             | `button[forStepperNext]`       | next-step button                        |
+| `ForStepperPrevious`         | `button[forStepperPrevious]`   | previous-step button                    |
+| `ForStepperProgress`         | `[forStepperProgress]`         | `progressbar` (optional)                |
+| `ForStepperCompletedContent` | `[forStepperCompletedContent]` | `group` (terminal "all complete" panel) |
+
+---
+
+## `ForStepper` inputs / model
+
+| Input / Model    | Type                              | Default         | Description                                                                                                |
+| ---------------- | --------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| `selectedIndex`  | `model<number>`                   | `0`             | Two-way bindable selected step index, range `0 … count` (the terminal `=== count` is the completed state). |
+| `linear`         | `input<boolean>`                  | `false`         | Gate forward navigation until preceding steps complete.                                                    |
+| `mode`           | `input<StepperMode>`              | `'interactive'` | Accessibility model.                                                                                       |
+| `orientation`    | `input<'horizontal'\|'vertical'>` | `'horizontal'`  | Layout axis; affects arrow-key semantics.                                                                  |
+| `activationMode` | `input<StepperActivationMode>`    | `'manual'`      | Whether arrow nav also selects (scope-injectable).                                                         |
+| `loop`           | `input<boolean>`                  | `true`          | Wrap arrow navigation (scope-injectable).                                                                  |
+| `disabled`       | `input<boolean>`                  | `false`         | Disables all triggers and navigation.                                                                      |
+| `dir`            | `input<'ltr'\|'rtl'\|null>`       | `null`          | Writing direction (inherits ambient when unset).                                                           |
+
+## `ForStepperItem` inputs
+
+| Input       | Type                              | Default | Description                                                                  |
+| ----------- | --------------------------------- | ------- | ---------------------------------------------------------------------------- |
+| `completed` | `input<boolean>`                  | `false` | Marks the step done (manual; wins over `field`).                             |
+| `optional`  | `input<boolean>`                  | `false` | Marks the step skippable in linear mode.                                     |
+| `disabled`  | `input<boolean>`                  | `false` | Disables only this step.                                                     |
+| `hasError`  | `input<boolean>`                  | `false` | Emits `'error'` resolved state when not current (manual; wins over `field`). |
+| `field`     | `input<FieldTree<unknown>\|null>` | `null`  | Optional Signal Forms field; drives `completed`/`hasError` from validity.    |
+| `state`     | `input<string\|null>`             | `null`  | Custom state override — wins over derived state.                             |
+
+## Outputs / completed state
+
+`ForStepper` exposes two members for the terminal completed state:
+
+- **`isCompleted`** (`Signal<boolean>`) — true when `selectedIndex()` has reached `count()` (one past the last step). Read it via a `#stepper="forStepper"` template reference.
+- **`(complete)`** — output that fires once each time the stepper enters the completed state. Retreating via `[forStepperPrevious]` and re-entering emits again.
+
+---
+
+## Completed-all content
+
+```html
+<div forStepper [(selectedIndex)]="step" (complete)="onDone()">
+  <!-- … list / content … -->
+  @if (step() >= steps.length) {
+  <section forStepperCompletedContent>All steps complete 🎉</section>
+  }
+</div>
+```
+
+When `Next` is pressed on the last step, `selectedIndex` advances to `count` (one past the last step) and `(complete)` fires once. `[forStepperPrevious]` returns to the last step. While completed, every `[forStepperContent]` panel is inactive and only `[forStepperCompletedContent]` carries `data-state="active"` (the others reflect `inert` + `aria-hidden`).
+
+---
+
+## Interactive mode with linear progression
+
+```html
+<div forStepper [(selectedIndex)]="step" [linear]="true">
+  <ol forStepperList ariaLabel="Checkout">
+    <li forStepperItem [completed]="step > 0">
+      <button forStepperTrigger>
+        <span forStepperIndicator></span>
+        Shipping
+      </button>
+      <span forStepperSeparator></span>
+    </li>
+    <li forStepperItem [completed]="step > 1">
+      <button forStepperTrigger>
+        <span forStepperIndicator></span>
+        Payment
+      </button>
+      <span forStepperSeparator></span>
+    </li>
+    <li forStepperItem>
+      <button forStepperTrigger>
+        <span forStepperIndicator></span>
+        Review
+      </button>
+    </li>
+  </ol>
+
+  <section forStepperContent>Shipping form</section>
+  <section forStepperContent>Payment form</section>
+  <section forStepperContent>Order review</section>
+
+  <button forStepperPrevious>Back</button>
+  <button forStepperNext>Next</button>
+</div>
+```
+
+---
+
+## Signal Forms field-driven completion
+
+Bind a step to a [Signal Forms](https://angular.dev/) field and its completion and
+error state follow the field's validity automatically — no manual `[completed]`
+wiring. A step is `completed` when its field is **valid and touched**; it reflects
+`error` when the field is **touched and invalid**. A manual `[completed]` /
+`[hasError]` input always wins when set.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { form, required, email } from '@angular/forms/signals';
+import {
+  ForStepper,
+  ForStepperContent,
+  ForStepperItem,
+  ForStepperList,
+  ForStepperTrigger,
+} from 'forty-cdk/stepper';
+
+@Component({
+  imports: [ForStepper, ForStepperList, ForStepperItem, ForStepperTrigger, ForStepperContent],
+  template: `
+    <div forStepper [(selectedIndex)]="step" [linear]="true">
+      <ol forStepperList ariaLabel="Sign up">
+        <li forStepperItem [field]="signup.account">
+          <button forStepperTrigger>Account</button>
+        </li>
+        <li forStepperItem [field]="signup.profile">
+          <button forStepperTrigger>Profile</button>
+        </li>
+      </ol>
+      <section forStepperContent>…</section>
+      <section forStepperContent>…</section>
+    </div>
+  `,
+})
+export class SignupWizard {
+  protected readonly step = signal(0);
+  private readonly model = signal({ account: '', profile: '' });
+  protected readonly signup = form(this.model, (s) => {
+    required(s.account);
+    email(s.account);
+    required(s.profile);
+  });
+}
+```
+
+---
+
+## Progress mode (display-only)
+
+```html
+<div forStepper [selectedIndex]="currentStep" mode="progress">
+  <ol forStepperList ariaLabel="Order status">
+    <li forStepperItem [completed]="currentStep > 0">
+      <span forStepperTrigger>Processing</span>
+      <span forStepperSeparator></span>
+    </li>
+    <li forStepperItem [completed]="currentStep > 1">
+      <span forStepperTrigger>Shipped</span>
+      <span forStepperSeparator></span>
+    </li>
+    <li forStepperItem>
+      <span forStepperTrigger>Delivered</span>
+    </li>
+  </ol>
+</div>
+```
+
+---
+
+## Progress bar (`ForStepperProgress`)
+
+An optional `role="progressbar"` reflecting how far through the steps the user is. Reports
+`aria-valuenow` (0–100) + `aria-valuetext`, and publishes a `--for-stepper-progress` (0–1)
+custom property for a styleable fill. `valueBy="index"` (default) tracks the current step
+index; `valueBy="completed"` tracks the count of completed steps.
+
+```html
+<div forStepper [(selectedIndex)]="step">
+  <div forStepperProgress ariaLabel="Checkout progress"></div>
+  <!-- … list / content … -->
+</div>
+```
+
+```css
+[forStepperProgress]::after {
+  content: '';
+  display: block;
+  width: calc(var(--for-stepper-progress) * 100%);
+}
+```
+
+---
+
+## Custom icon per state (indicator example)
+
+```html
+<li forStepperItem #step="forStepperItem">
+  <button forStepperTrigger>
+    <span forStepperIndicator>
+      @if (step.resolvedState() === 'completed') {
+      <svg><!-- checkmark --></svg>
+      } @else if (step.resolvedState() === 'error') {
+      <svg><!-- exclamation --></svg>
+      } @else { {{ step.index() + 1 }} }
+    </span>
+    Step label
+  </button>
+</li>
+```
+
+Or purely via CSS:
+
+```css
+[forStepperIndicator][data-state='completed']::before {
+  content: '✓';
+}
+[forStepperIndicator][data-state='error']::before {
+  content: '!';
+}
+[forStepperIndicator][data-state='active']::before {
+  content: '●';
+}
+[forStepperIndicator][data-state='pending']::before {
+  content: '○';
+}
+```
+
+---
+
+## Keyboard interaction (interactive mode)
+
+| Key                        | Action                                    |
+| -------------------------- | ----------------------------------------- |
+| `ArrowRight` / `ArrowDown` | Move focus to next selectable trigger     |
+| `ArrowLeft` / `ArrowUp`    | Move focus to previous selectable trigger |
+| `Home`                     | Move focus to first selectable trigger    |
+| `End`                      | Move focus to last selectable trigger     |
+| `Space` / `Enter`          | Activate focused trigger (manual mode)    |
+| `Tab`                      | Move focus into / out of the step panel   |
+
+In `activationMode="automatic"` arrow keys move focus AND select. In `activationMode="manual"` (default) only Space / Enter activate.
+
+In `orientation="vertical"` ArrowUp/Down navigate; ArrowLeft/Right are ignored. In `orientation="horizontal"` ArrowLeft/Right navigate; ArrowUp/Down are ignored. RTL inverts ArrowLeft and ArrowRight.
+
+---
+
+## `data-state` vocabulary
+
+| Piece                          | Values                                            |
+| ------------------------------ | ------------------------------------------------- |
+| `[forStepperItem]`             | `pending` `active` `completed` `error` `<custom>` |
+| `[forStepperTrigger]`          | same as item                                      |
+| `[forStepperIndicator]`        | same as item                                      |
+| `[forStepperContent]`          | `active` `inactive`                               |
+| `[forStepperCompletedContent]` | `active` `inactive`                               |
+| `[forStepperSeparator]`        | `completed` `pending`                             |
+
+### Boolean `data-*`
+
+| Attribute          | When present                                     |
+| ------------------ | ------------------------------------------------ |
+| `data-disabled`    | Root or step is disabled                         |
+| `data-orientation` | Always — `horizontal` or `vertical`              |
+| `data-mode`        | Always (root only) — `interactive` or `progress` |
+
+---
+
+## Accessibility notes
+
+- **Interactive mode** implements the WAI-ARIA Tabs pattern. Each trigger carries `role="tab"`, the list carries `role="tablist"`, and content panels carry `role="tabpanel"`. `aria-selected` is always emitted; `aria-controls` is gated to the current step (prevents dangling references when panels are unmounted with `@if`).
+- **Progress mode** uses a standard `<ol role="list">` with `aria-current="step"` on the active trigger. No tab-stop manipulation is performed; triggers carry no `role`.
+- **Disabled triggers** in interactive mode retain their tab stop using `aria-disabled="true"` rather than the native `disabled` attribute, so assistive technology can announce them.
+- **Linear mode** reflects unreachable ahead-steps as `aria-disabled="true"` + `data-disabled=""` on the trigger. Keyboard navigation skips them automatically.
+- **RTL** is supported: set `dir="rtl"` on the root or a DOM ancestor.
+- **Progress bar** (`[forStepperProgress]`) is an opt-in part. When present it exposes `role="progressbar"` with `aria-valuemin="0"`, `aria-valuemax="100"`, and `aria-valuenow` derived from the current step or the count of completed steps.

package/switch/README.md

@@ -0,0 +1,116 @@
+# Switch
+
+Headless implementation of the [WAI-ARIA Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) that doubles as a `FormCheckboxControl` for Angular Signal Forms.
+
+A switch is a binary on/off control whose state changes immediately on activation — distinct semantically from a checkbox (which represents a deferred selection).
+
+## Pieces
+
+| Class       | Selector      | Role                                                                 |
+| ----------- | ------------- | -------------------------------------------------------------------- |
+| `ForSwitch` | `[forSwitch]` | Single directive on a `<button>`. Wires ARIA + click + Signal Forms. |
+
+## Inputs / models
+
+| API        | Type                                                      | Description                                                                                              |
+| ---------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `checked`  | `model<boolean>`                                          | Two-way bindable on/off state. Required by `FormCheckboxControl`.                                        |
+| `disabled` | `input<boolean>`                                          | Ignores click; reflects `aria-disabled="true"` and `data-disabled`. Stays focusable (per APG).           |
+| `readonly` | `input<boolean>`                                          | Ignores click; reflects `aria-readonly="true"`. Stays focusable.                                         |
+| `required` | `input<boolean>`                                          | Reflects `aria-required="true"`.                                                                         |
+| `invalid`  | `input<boolean>`                                          | Reflects `aria-invalid="true"`.                                                                          |
+| `pending`  | `input<boolean>`                                          | Reflects `aria-busy="true"` while async validation is in flight.                                         |
+| `name`     | `input<string \| undefined>`                              | Reflects on `name`.                                                                                      |
+| `errors`   | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Validation errors fed by `[formField]`. The directive does not render them — that is consumer territory. |
+| `touched`  | `model<boolean>`                                          | Set to `true` on blur. Two-way so the field can read it back.                                            |
+
+The host gets `data-state="checked" \| "unchecked"`, `data-disabled`, and `data-readonly` for CSS hooks.
+
+## Stand-alone usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForSwitch } from 'forty-cdk/switch';
+
+@Component({
+  selector: 'demo-toggle',
+  imports: [ForSwitch],
+  template: `
+    <button forSwitch class="switch" [(checked)]="enabled">
+      <span class="thumb"></span>
+    </button>
+    <p>Notifications: {{ enabled() ? 'on' : 'off' }}</p>
+  `,
+})
+export class DemoToggle {
+  readonly enabled = signal(false);
+}
+```
+
+## Signal Forms usage
+
+`ForSwitch` implements `FormCheckboxControl`. The `[formField]` directive detects the interface and wires everything — value, disabled, required, invalid, errors, touched — without any glue.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import { Field } from '@angular/forms';
+import { ForSwitch } from 'forty-cdk/switch';
+
+interface Settings {
+  notifications: boolean;
+  termsAccepted: boolean;
+}
+
+@Component({
+  selector: 'demo-settings',
+  imports: [ForSwitch /* , FormField from @angular/forms */],
+  template: `
+    <button forSwitch [formField]="settings.notifications"></button>
+    <button forSwitch [formField]="settings.termsAccepted"></button>
+  `,
+})
+export class DemoSettings {
+  readonly model = signal<Settings>({ notifications: false, termsAccepted: false });
+  readonly settings = form(this.model, (s) => {
+    required(s.termsAccepted);
+  });
+}
+```
+
+## 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                   |
+| ------------- | --------------- | ------------------------ |
+| `[forSwitch]` | `data-state`    | `checked` \| `unchecked` |
+| `[forSwitch]` | `data-disabled` | present \| absent        |
+| `[forSwitch]` | `data-readonly` | present \| absent        |
+| `[forSwitch]` | `data-touched`  | present \| absent        |
+| `[forSwitch]` | `data-dirty`    | present \| absent        |
+| `[forSwitch]` | `data-pending`  | present \| absent        |
+| `[forSwitch]` | `data-invalid`  | present \| absent        |
+
+```css
+.switch .thumb {
+  transition: transform 150ms;
+}
+
+.switch[data-state='checked'] .thumb {
+  transform: translateX(100%);
+}
+```
+
+## Accessibility notes
+
+- **Use a `<button>`.** The directive forces `type="button"` to prevent submit-by-Enter inside a `<form>`. Enter and Space toggle the switch via native button behavior. On other elements (e.g. `<div>`), keyboard activation is on you.
+- **A disabled switch stays focusable** (per APG): it reflects `aria-disabled="true"` + `data-disabled=""` rather than the native `disabled` attribute, so assistive tech still announces it while click / keyboard activation is a no-op. Form-submit exclusion is handled by the hidden `<input>`, not the visible button.
+- **`role="switch"`** is announced as "switch, on/off" by screen readers, distinct from "checkbox, checked/not checked".
+- **`@angular/forms` is an optional peer.** If you're not using Signal Forms, don't install it — the directive runs fine without it (only the type import from `@angular/forms/signals` is type-only and erased at build).
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_SWITCH_HOST_DIRECTIVE_INPUTS` / `FOR_SWITCH_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).