forty-cdk 0.37.0 → 0.39.0

package/README.md

@@ -26,10 +26,10 @@ Required:
 
 Optional — install only if you use the matching entry point / primitives:
 
-| Peer                               | Needed by                                                                                                                                                                                                                                                                                                                                                                  |
-| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@angular/forms` `^22.1.0`         | Form-control primitives (`Switch`, `Checkbox`, `RadioGroup`, `Listbox`, `Select`, `Slider`, `Combobox`, …). They implement `FormValueControl` / `FormCheckboxControl` from `@angular/forms/signals` for `[formField]` auto-wiring. The contract is type-only, so the published bundle never references the package — consumers using only non-form primitives can skip it. |
-| `@internationalized/date` `^3.0.0` | The `forty-cdk/internationalized-date` entry point (`InternationalizedDateAdapter`, `InternationalizedDateTimeAdapter`). The date/time primitives themselves depend only on the abstract `DateAdapter` contract from `forty-cdk/date-adapter` — install this peer only when you import that entry point.                                                                   |
+| Peer                               | Needed by                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@angular/forms` `^22.1.0`         | The form-control entry points: `forty-cdk/checkbox`, `combobox`, `date-field`, `date-picker`, `input`, `listbox`, `number-input`, `otp-input`, `radio-group`, `search`, `select`, `slider`, `switch`, `time-field`, `time-picker` and `toggle`. Their controls implement `FormValueControl` / `FormCheckboxControl` from `@angular/forms/signals` for `[formField]` auto-wiring. The contract is type-only, so no published bundle references the package, but those entry points' type declarations do: a project that type-checks its dependencies (`skipLibCheck: false`) needs the peer as soon as it imports one of them. Every other entry point, `forty-cdk/field` and `forty-cdk/stepper` included, compiles without it. |
+| `@internationalized/date` `^3.0.0` | The `forty-cdk/internationalized-date` entry point (`InternationalizedDateAdapter`, `InternationalizedDateTimeAdapter`). The date/time primitives themselves depend only on the abstract `DateAdapter` contract from `forty-cdk/date-adapter` — install this peer only when you import that entry point.                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Regular dependencies
 

package/avatar/README.md

@@ -22,7 +22,7 @@ It is headless and presentational: it tracks the load lifecycle of an `<img>` an
 
 ## 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.
+The image loads, so `data-status` settles on `loaded` and the initials never render: `fallbackDelayMs` holds the fallback back for 500 ms, so a fast load never flashes it. Failed load below breaks the URL to show the `error` path.
 
 ```ts
 import { ChangeDetectionStrategy, Component } from '@angular/core';
@@ -100,6 +100,8 @@ When the image errors, the directive flips `shouldShowFallback()` and the initia
 
 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.
 
+A meaningful `alt` names the avatar only while the image is shown: once it fails, the image is hidden and the fallback initials are all that is left to announce. When an avatar stands alone, name the root instead (`role="img"` with an `aria-label`) and give the `<img>` `alt=""`, so the fallback carries the same name as the loaded image.
+
 ## Styling
 
 forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [API](#api), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).

package/breadcrumbs/README.md

@@ -126,10 +126,10 @@ Implements the [WAI-ARIA Breadcrumb pattern](https://www.w3.org/WAI/ARIA/apg/pat
 
 ## Styling
 
-forty-cdk ships no styles. Style the current item via `[aria-current="page"]`.
+forty-cdk ships no styles: put your own class on each piece and key your CSS off the `aria-current="page"` the current item reflects, not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 ```css
-[forBreadcrumbItem][aria-current='page'] {
+.bc-link[aria-current='page'] {
   font-weight: bold;
   color: inherit;
   text-decoration: none;

package/button/README.md

@@ -5,7 +5,7 @@ archetype: [composable-ui]
 apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/button/
 ---
 
-# ForButton
+# 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.
 
@@ -58,20 +58,26 @@ Disabled buttons stay focusable so assistive technology can announce them. The n
 A surrounding disabled `[forFieldset]` disables the button too: its `disabled` input is OR'd with the group's, so `aria-disabled` / `data-disabled` are reflected and activation is suppressed. This matters most on a non-native host (`<div forButton>`), which a native `<fieldset disabled>` cannot reach.
 
 ```html
-<fieldset forFieldset [disabled]="locked()">
-  <legend forFieldsetLegend>Account</legend>
+<div forFieldset [disabled]="locked()">
+  <span forFieldsetLegend>Account</span>
   <button forButton (activate)="save()">Save</button>
-</fieldset>
+</div>
 ```
 
+On a native `<fieldset>` host, `[forFieldset]` sets the native `disabled` attribute, and HTML then disables every native `<button>` inside it: the button leaves the tab order and cannot be focused, whatever `forButton` does. The guarantee that a disabled button stays focusable holds for a non-native group host like the `<div>` above, and for a non-native button host (`<div forButton>`) in either group.
+
 ## Preserve consumer `type`
 
-A native `<button>` without an explicit `type` attribute defaults to `type="button"`. A consumer-set `type="submit"` is preserved:
+A native `<button>` without an explicit `type` attribute defaults to `type="button"`. A consumer-set `type` is preserved, whether it is a static attribute or a binding, and later writes to a binding are followed:
 
 ```html
 <button type="submit" forButton>Submit form</button>
+
+<button [attr.type]="kind()" forButton>Save</button>
 ```
 
+A binding that resolves to `null` removes the attribute, so the button falls back to the HTML default, which is `submit` inside a form.
+
 ## API
 
 ### `ForButton`
@@ -118,12 +124,12 @@ Implements the [WAI-ARIA Button pattern](https://www.w3.org/WAI/ARIA/apg/pattern
 forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [API](#api), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
 ```css
-[forButton][data-disabled] {
+.btn[data-disabled] {
   opacity: 0.4;
   pointer-events: none;
 }
 
-[forButton][data-pressed] {
+.btn[data-pressed] {
   transform: scale(0.97);
 }
 ```

package/calendar/README.md

@@ -341,12 +341,18 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
         />
       </svg>
     </button>
-    <select forCalendarMonthSelect #m="forCalendarMonthSelect">
+    <select forCalendarMonthSelect #m="forCalendarMonthSelect" aria-label="Month">
       @for (opt of m.options(); track opt.value) {
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.label }}</option>
       }
     </select>
-    <select forCalendarYearSelect #y="forCalendarYearSelect" [minYear]="1900" [maxYear]="2100">
+    <select
+      forCalendarYearSelect
+      #y="forCalendarYearSelect"
+      aria-label="Year"
+      [minYear]="1900"
+      [maxYear]="2100"
+    >
       @for (opt of y.years(); track opt.value) {
       <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.value }}</option>
       }
@@ -575,7 +581,7 @@ Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/
 - **`aria-selected`** is always emitted (`"true"` / `"false"`); **`aria-current="date"`** marks today; **`aria-disabled`** marks unavailable dates (truthy-only).
 - **`aria-multiselectable="true"`** is set on the day grid in `selectionMode="range"`, where a committed range selects several cells, and is absent in single mode.
 - **Roving tabindex**: exactly one cell (the focused date) is tabbable. `Tab` enters and leaves the grid in one stop.
-- **Boolean `data-*`** on the cell, present when true and absent when false: `data-selected`, `data-today`, `data-highlighted` (the focused/roving cell), `data-disabled` and `data-outside-month`.
+- **Boolean `data-*`** on the cell, present when true and absent when false: `data-selected`, `data-today`, `data-highlighted` (the roving tab-stop cell, kept after focus leaves the grid), `data-disabled` and `data-outside-month`.
 
 ## Styling
 
@@ -612,7 +618,7 @@ import { CalendarDate, today, getLocalTimeZone } from '@internationalized/date';
 @Component({
   selector: 'app-date',
   changeDetection: ChangeDetectionStrategy.OnPush,
-  /* ... */
+  template: `<p>Today is {{ date()?.toString() }}</p>`,
 })
 export class DatePage {
   readonly date = signal<CalendarDate | null>(null);

package/carousel/README.md

@@ -5,7 +5,7 @@ archetype: [composable-ui]
 apgUrl: https://www.w3.org/WAI/ARIA/apg/patterns/carousel/
 ---
 
-# ForCarousel
+# Carousel
 
 A slideshow of content panels with previous / next controls, an indicator group, optional looping and multi-slide views, and an accessible autoplay mode with a pause control.
 

package/checkbox/README.md

@@ -134,12 +134,12 @@ One class and one directive, three states. `disabled` and `readonly` both keep t
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { form, required } from '@angular/forms/signals';
+import { form, FormField, required } from '@angular/forms/signals';
 import { ForCheckbox } from 'forty-cdk/checkbox';
 
 @Component({
   selector: 'demo-checkout',
-  imports: [ForCheckbox /* , FormField from @angular/forms */],
+  imports: [ForCheckbox, FormField],
   template: `
     <button forCheckbox class="cb-row" [formField]="checkout.acceptTerms">
       <span class="cb">
@@ -166,7 +166,7 @@ export class DemoCheckout {
 | `disabled` / `readonly` / `required` / `invalid` / `pending` | `input<boolean>`                                          | Reflected as the matching `aria-*` / `data-*` attributes. A disabled checkbox stays focusable (per APG), with `aria-disabled="true"` + `data-disabled` and no native `disabled`; click is a no-op.<br>**Default:** — |
 | `name`                                                       | `input<string>`                                           | Reflected on `name` (empty string omits the attribute). A native reset of the owning `<form>` restores `checked` and `indeterminate` to their first-render values.<br>**Default:** `''`                              |
 | `errors`                                                     | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Validation errors fed by `[formField]`.<br>**Default:** —                                                                                                                                                            |
-| `touched`                                                    | `model<boolean>`                                          | Set to `true` on blur.<br>**Default:** —                                                                                                                                                                             |
+| `touched`                                                    | `model<boolean>`                                          | Set to `true` on blur.<br>**Default:** `false`                                                                                                                                                                       |
 
 | Data attribute  | Values                                      |
 | --------------- | ------------------------------------------- |

package/combobox/README.md

@@ -115,17 +115,11 @@ const COUNTRIES = [
     ForComboboxClear,
   ],
   template: `
-    <div
-      forCombobox
-      #combobox="forCombobox"
-      class="combobox"
-      [(query)]="query"
-      [(value)]="value"
-      ariaLabel="Country search"
-    >
+    <div forCombobox #combobox="forCombobox" class="combobox" [(query)]="query" [(value)]="value">
       <div class="combobox-single">
         <input
           forComboboxInput
+          aria-label="Country search"
           class="combobox-input combobox-input--boxed"
           placeholder="Search countries…"
         />
@@ -192,7 +186,7 @@ Click the `[forComboboxTrigger]` button, type into the search field inside the p
 
 ### Virtualized (1,000 options)
 
-The primitive never owns the scroll container, so it virtualizes with any windowing strategy. The demo uses a dependency-free one. The consumer renders only the visible window and wires `[totalCount]`, `[visibleRange]` and `[forComboboxOption][posInSet]`; `(scrollToIndex)` fires when navigation targets a row outside the window.
+The primitive never owns the scroll container, so it virtualizes with any windowing strategy. The demo uses a dependency-free one. The consumer renders only the visible window, adds `forComboboxVirtualized` to the combobox, and wires its `[totalCount]` and `[visibleRange]` plus `[forComboboxOption][posInSet]`; `(scrollToIndex)` fires when navigation targets a row outside the window.
 
 ## API
 
@@ -225,6 +219,9 @@ The content anchors to the field box when a `[forComboboxAnchor]` is present; se
 | `[forCombobox]`          | `data-dirty`       | present / absent                                                    |
 | `[forCombobox]`          | `data-pending`     | present / absent                                                    |
 | `[forCombobox]`          | `data-invalid`     | present / absent                                                    |
+| `[forComboboxTrigger]`   | `data-state`       | `open` \| `closed`                                                  |
+| `[forComboboxTrigger]`   | `data-disabled`    | present / absent                                                    |
+| `[forComboboxTrigger]`   | `data-readonly`    | present / absent                                                    |
 | `[forComboboxInput]`     | `data-state`       | `open` \| `closed`                                                  |
 | `[forComboboxInput]`     | `data-disabled`    | present / absent                                                    |
 | `[forComboboxToggle]`    | `data-state`       | `open` \| `closed`                                                  |
@@ -299,7 +296,7 @@ The default (editable) anatomy is a text field that filters in place. A **picker
 
 Add two parts:
 
-- **`[forComboboxTrigger]`**: a real `<button>` outside the `@if (open())`. It opens the panel, becomes the default positioning anchor, and is where focus returns on close.
+- **`[forComboboxTrigger]`**: a real `<button>` outside the `@if (open())`. It opens the panel, becomes the default positioning anchor, and is where focus returns on close. It carries `role="combobox"` and announces the form state (`aria-required`, `aria-invalid`, `aria-busy`, `aria-readonly`), because while the panel is closed it is the only focusable part of the field. Give it a label: a combobox is not named by its text.
 - **`[forComboboxList]`**: the `role="listbox"` element nested inside `[forComboboxContent]`, next to the input. It owns the options and the labelled role; `[forComboboxContent]` becomes the `role="dialog"` the trigger opens, named by the trigger.
 
 ```html
@@ -669,14 +666,17 @@ The same three inputs cover multi mode + chips: bind `<span forComboboxChip [val
 
 ## Virtualization
 
-For very large option sets (1k+) the consumer can render only the visible window and let the directive coordinate navigation across the full source. Three additive inputs / one output cover the wiring; non-virtualized usage is unchanged.
+For very large option sets (1k+) the consumer can render only the visible window and let the directive coordinate navigation across the full source. The wiring lives on `ForComboboxVirtualized` (`[forComboboxVirtualized]`, `exportAs: 'forComboboxVirtualized'`), placed on the same element as `[forCombobox]` and imported from `forty-cdk/combobox` next to `ForCombobox`. Non-virtualized usage is unchanged, and a combobox without the directive never bundles the virtualized navigation engine.
 
-| Input / Output                              | Purpose                                                                                                                                                                    |
-| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[totalCount]: number \| undefined`         | Length of the **filtered** source array. Drives `aria-setsize` and lets navigation walk past the rendered window. Leave `undefined` (default) for non-virtualized lists.   |
-| `[visibleRange]: [start, end) \| undefined` | Inclusive-exclusive index range currently rendered in the DOM. Pulled from your virtualizer's `getVirtualItems()`.                                                         |
-| `[forComboboxOption][posInSet]`             | Absolute index of this option in the source array. Required when virtualizing; the directive folds option data into a snapshot keyed by this index so it survives unmount. |
-| `(scrollToIndex)`                           | Emitted when arrow keys (or Home / End) need to land on an option whose absolute index falls outside `visibleRange()`. Wire to the virtualizer's `scrollToIndex(idx)`.     |
+| `ForComboboxVirtualized` member             | Purpose                                                                                                                                                                  |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `[totalCount]: number \| undefined`         | Length of the **filtered** source array. Drives `aria-setsize` and lets navigation walk past the rendered window. Leave `undefined` (default) for non-virtualized lists. |
+| `[visibleRange]: [start, end) \| undefined` | Inclusive-exclusive index range currently rendered in the DOM. Pulled from your virtualizer's `getVirtualItems()`.                                                       |
+| `[dataVersion]: unknown`                    | Bind any value that changes when the source is re-sorted or refreshed without its length changing, so navigation never lands on a stale off-window entry.                |
+| `(scrollToIndex)`                           | Emitted when arrow keys (or Home / End) need to land on an option whose absolute index falls outside `visibleRange()`. Wire to the virtualizer's `scrollToIndex(idx)`.   |
+| `invalidateSnapshot()`                      | The imperative twin of `[dataVersion]`, for a same-length refresh you cannot express through the input. No-op while `totalCount` is unset.                               |
+
+Each rendered option also binds `[forComboboxOption][posInSet]`, its absolute index in the source array. It is required when virtualizing: the directive keeps option data keyed by this index so it survives unmount.
 
 How navigation flows when virtualizing:
 
@@ -692,6 +692,7 @@ Inline autocomplete matches against the most recently rendered window overlaid w
 ```html
 <div
   forCombobox
+  forComboboxVirtualized
   [(query)]="query"
   [(value)]="value"
   [(open)]="open"
@@ -742,11 +743,11 @@ This uses the library's own [`injectVirtualizer`](../virtualization/README.md) c
 
 `[totalCount]` is also the result count the message pieces read: `[forComboboxStatus]`'s `count()` reports it rather than the size of the rendered window, so `{{ status.count() }} results.` announces the full count once and stays put while the window scrolls, and `[forComboboxEmpty]` stays hidden while a window with results has not rendered yet.
 
-When `[totalCount]` is omitted, the directive falls back to `options().length` and behaves exactly as before: `aria-setsize` is left to the platform default and navigation never emits `(scrollToIndex)`.
+When `[forComboboxVirtualized]` is absent or its `[totalCount]` is omitted, the combobox falls back to `options().length` and behaves exactly as before: `aria-setsize` is left to the platform default and navigation never emits `(scrollToIndex)`.
 
 > **Disabled options off-screen.** The directive learns an option's `disabled` only when it's been rendered at least once. While the consumer can pre-mark disabled rows with their own filter (most apps do), arrow nav cannot skip an off-screen disabled option it has never seen: it will land on it, the option will mount, and the next arrow press skips. Mark disabled rows in the source array if this matters.
 
-> **Listbox virtualization** ships the same contract: `[forListbox]` defaults to roving tabindex (DOM focus on the actual option element) and switches to the `aria-activedescendant` model when you set `[totalCount]`. See the [Listbox README "Virtualization"](../listbox/README.md#virtualization) section.
+> **Listbox virtualization** ships the same contract: `[forListbox]` defaults to roving tabindex (DOM focus on the actual option element) and switches to the `aria-activedescendant` model when you add `[forListboxVirtualized]` with `[totalCount]`. See the [Listbox README "Virtualization"](../listbox/README.md#virtualization) section.
 
 ## Writing direction
 
@@ -838,10 +839,11 @@ Hovering an option also makes it the activedescendant, so mouse and keyboard int
 
 Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
 
+- **Name the input.** `role="combobox"` takes its name from the author, and a placeholder is only a fallback that disappears once the user types. The root's `ariaLabel` names the listbox, not the input. Give `[forComboboxInput]` a `<label for>`, an `aria-label` or an `aria-labelledby`, or wrap the combobox in `[forField]` with a `[forLabel]`. In the picker anatomy, label `[forComboboxTrigger]` the same way, for example `aria-labelledby` pointing at a visible label and at the element showing the value.
 - Apply the input directive to an actual `<input>`: the browser's caret and selection semantics are what make inline autocomplete work, and screen readers expect a real text field for `role="combobox"`.
 - `role="listbox"` lives on `[forComboboxContent]` in the editable anatomy and on `[forComboboxList]` in the picker anatomy; the input's `aria-controls` targets whichever carries it. In the picker anatomy the popup surface (`[forComboboxContent]`) is a `role="dialog"` named by the trigger (`aria-labelledby`; a static `aria-label` or `aria-labelledby` on it wins), so it can hold the input next to the list without an `aria-required-owned-elements` violation. The "editable + list" shape, with no trigger, leaves it role-less.
 - `aria-multiselectable="true"` (multi mode) and the labelled role (`aria-label` / `aria-labelledby`, pointing at the input) sit on whichever element carries `role="listbox"`: content in the editable anatomy, the list in the picker anatomy.
-- `[forComboboxTrigger]` (picker anatomy) is a real `<button>` reflecting `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (the dialog surface, while open), an `id` (a static one is kept), and native `disabled` from the combobox's effective disabled. The popup is a dialog rather than a listbox because focus moves into the search input inside it. It is exempt from the popup's outside-pointer dismissal layer, like the input.
+- `[forComboboxTrigger]` (picker anatomy) is a real `<button>` with `role="combobox"`, reflecting `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` (the dialog surface, while open), an `id` (a static one is kept), and native `disabled` from the combobox's effective disabled. It also reflects `aria-required`, `aria-invalid`, `aria-busy` and `aria-readonly` (truthy-only) from the root, so a closed picker announces a required, failing or validating field: the input carrying the same state only exists while the panel is open. It keeps the role while the dialog is open, next to the `role="combobox"` search input inside it. The popup is a dialog rather than a listbox because focus moves into the search input inside it. It is exempt from the popup's outside-pointer dismissal layer, like the input.
 - `[forComboboxContent]` and `[forComboboxList]` cancel a `mousedown` that would otherwise move focus onto the surface or blur the input, so a press between options leaves focus in the input. A press on a focusable descendant is let through.
 - `[forComboboxToggle]` (editable anatomy) is a real `<button>` with `tabindex="-1"`, a localizable `aria-label`, `aria-expanded`, `aria-controls` (the listbox, while open) and native `disabled`. It cancels `mousedown` so focus stays in the input, and it is exempt from the outside-pointer dismissal layer.
 - `[forComboboxClear]` has `tabindex="-1"` and a localizable `aria-label`. It cancels `mousedown` too, and is exempt from the outside-pointer dismissal layer, so clearing an open listbox leaves it open with focus in the input and the combobox untouched.
@@ -885,4 +887,4 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 
 ## Wrapping in a design system
 
-[Wrapping form primitives](../../../docs/wrapping-form-primitives.md) documents both supported wrapper patterns: `hostDirectives` with the exported `FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS` / `FOR_COMBOBOX_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing.
+[Wrapping form primitives](../../../docs/wrapping-form-primitives.md) documents both supported wrapper patterns: `hostDirectives` with the exported `FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS` / `FOR_COMBOBOX_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing. A virtualized wrapper adds `ForComboboxVirtualized` as a second `hostDirectives` entry and re-exposes its surface with `FOR_COMBOBOX_VIRTUALIZED_HOST_DIRECTIVE_INPUTS` / `FOR_COMBOBOX_VIRTUALIZED_HOST_DIRECTIVE_OUTPUTS`.

package/date-field/README.md

@@ -99,14 +99,14 @@ With a time-capable adapter, a `granularity` finer than `'day'` appends hour / m
 
 ```ts
 import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
-import { form } from '@angular/forms/signals';
+import { form, FormField } from '@angular/forms/signals';
 import { CalendarDate } from '@internationalized/date';
 import { ForDateField, ForDateFieldLiteral, ForDateFieldSegment } from 'forty-cdk/date-field';
 
 @Component({
   selector: 'app-dob-form',
   changeDetection: ChangeDetectionStrategy.OnPush,
-  imports: [ForDateField, ForDateFieldSegment, ForDateFieldLiteral],
+  imports: [ForDateField, ForDateFieldSegment, ForDateFieldLiteral, FormField],
   template: `
     <div
       forDateField
@@ -135,7 +135,7 @@ export class DobFormField {
 
 ### Date range
 
-`ForDateRangeField` is the range variant, shipped from this same entry point. Two labelled endpoint groups share locale, granularity and bounds; each is its own tab stop, so `Tab` steps start → end while the arrows move between segments inside one endpoint.
+`ForDateRangeField` is the range variant, shipped from this same entry point. Two labelled endpoint groups share locale, granularity and bounds; each is its own tab stop, so `Tab` steps start → end while the arrows move between segments inside one endpoint. Type an end date before the start and a message under the field says so, read from `disordered()`, since the red border alone is a colour cue only.
 
 ### Date & time range
 
@@ -143,7 +143,7 @@ With a time-capable adapter, a `granularity` finer than `'day'` appends time seg
 
 ### Range in Signal Forms
 
-`ForDateRangeField` implements `FormValueControl<DateRange | null>`, so `[formField]` binds the committed range into the form and pulls validation back out. A half-entered or out-of-order range keeps `value()` null, so a `required` field stays invalid until both endpoints are filled and ordered.
+`ForDateRangeField` implements `FormValueControl<DateRange | null>`, so `[formField]` binds the committed range into the form and pulls validation back out. A half-entered or out-of-order range keeps `value()` null, so a `required` field stays invalid until both endpoints are filled and ordered. The error message tells the two cases apart through `disordered()`.
 
 ## API
 
@@ -191,7 +191,7 @@ A native reset of the owning `<form>` returns `value` to what it held when the f
 | `[forDateFieldSegment]` | `data-disabled`    | present \| absent |
 | `[forDateFieldSegment]` | `data-readonly`    | present \| absent |
 
-`data-empty` marks the field only while **every** editable segment is empty (nothing has been entered); a partially-typed field is **not** empty. `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment and the only focus hook the consumer gets, shared with the other roving primitives. `[forDateFieldLiteral]` carries no data-\* attributes (it is `aria-hidden` and out of the tab order).
+`data-empty` marks the field only while **every** editable segment is empty (nothing has been entered); a partially-typed field is **not** empty. `data-placeholder` marks each individual segment that is still empty. `data-highlighted` marks the roving tab-stop segment, the vocabulary shared with the other roving primitives. It stays on that segment after focus leaves the field, so a style that reads as focus is scoped to the field's `:focus-within`, and to each endpoint group's in a range field, where each endpoint keeps its own. `[forDateFieldLiteral]` carries no data-\* attributes (it is `aria-hidden` and out of the tab order).
 
 ## Date-time field
 
@@ -306,7 +306,7 @@ The endpoint groups each accept an `ariaLabel` input for their own group label,
 
 ### Ordering
 
-The two endpoints are typed independently, so order is not guaranteed by construction the way the picker's two-click flow guarantees it. The field preserves the `DateRange` `end >= start` invariant by **never emitting an out-of-order range**: when both endpoints are complete but `start > end`, the typed segments are kept (not silently rewritten), `value` stays `null`, and the root reflects `aria-invalid="true"` + `data-range-error` so the disorder is perceivable and stylable. Editing either endpoint back into order emits the range.
+The two endpoints are typed independently, so order is not guaranteed by construction the way the picker's two-click flow guarantees it. The field preserves the `DateRange` `end >= start` invariant by **never emitting an out-of-order range**: when both endpoints are complete but `start > end`, the typed segments are kept (not silently rewritten), `value` stays `null`, and the root reflects `aria-invalid="true"` + `data-range-error` so the disorder is perceivable and stylable. Editing either endpoint back into order emits the range. The border colour alone is not an error message, so read the same state from `disordered()` (through `#range="forDateRangeField"`) and say it in words, as the Date range example does.
 
 ### Range keyboard and accessibility
 
@@ -339,13 +339,13 @@ Composes the [WAI-ARIA Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patte
 - **`role="spinbutton"`** per segment, with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` reflected; the month segment also exposes a localized `aria-valuetext` ("March"), so screen readers read the name rather than the number.
 - **Roving tabindex**: exactly one segment is tabbable, so `Tab` enters and leaves the whole field in one stop; arrows move between segments.
 - **Literals are `aria-hidden`** and never focusable, so assistive tech reads only the spinbutton segments.
-- **Boolean `data-*`** on each segment, present when true and absent when false: `data-highlighted` (focused/roving), `data-placeholder` (empty), `data-disabled`, `data-readonly`.
+- **Boolean `data-*`** on each segment, present when true and absent when false: `data-highlighted` (the roving tab stop, kept after blur), `data-placeholder` (empty), `data-disabled`, `data-readonly`.
 - **`aria-readonly` belongs on the segments, not the group.** WAI-ARIA supports it on `role="spinbutton"` but not on `role="group"`, so each segment carries `aria-readonly="true"` while the group reflects the `data-readonly` styling hook only.
 - **On-screen keyboards work.** A segment of a field that is neither disabled nor read-only is a `contenteditable="plaintext-only"` editing host with `inputmode="numeric"`, so tapping it on a touch device opens the numeric keypad (the AM/PM segment opens the text keyboard). What the keyboard or an input method types goes through the [Keyboard](#keyboard) map above and is never inserted into the segment, which keeps rendering `{{ seg.text }}`.
 
 ## Styling
 
-The library is styleless, so style the boolean `data-*` hooks yourself: `[data-highlighted]` (the focused/roving segment), `[data-placeholder]` (empty), `[data-disabled]` and `[data-readonly]` on the segments, and `[data-empty]` / `[data-disabled]` / `[data-readonly]` / `[data-required]` plus the form-state hooks `[data-touched]` / `[data-dirty]` / `[data-pending]` / `[data-invalid]` on the root group.
+The library is styleless, so style the boolean `data-*` hooks yourself: `[data-highlighted]` (the roving tab-stop segment, kept after focus leaves the field), `[data-placeholder]` (empty), `[data-disabled]` and `[data-readonly]` on the segments, and `[data-empty]` / `[data-disabled]` / `[data-readonly]` / `[data-required]` plus the form-state hooks `[data-touched]` / `[data-dirty]` / `[data-pending]` / `[data-invalid]` on the root group.
 
 forty-cdk ships no styles: put your own class on each piece and key your CSS off the `data-*` attributes listed under [Data attributes](#data-attributes), not off the `for*` selectors ([Styling forty-cdk](../../../docs/styling.md) explains why).
 
@@ -355,7 +355,7 @@ A segment is an editing host, so the browser paints a text caret in the focused
 .date-field-segment[data-placeholder] {
   color: GrayText;
 }
-.date-field-segment[data-highlighted] {
+.date-field:focus-within .date-field-segment[data-highlighted] {
   caret-color: transparent;
   background: Highlight;
   color: HighlightText;

package/date-picker/README.md

@@ -94,14 +94,13 @@ import { provideInternationalizedDateAdapter } from 'forty-cdk/internationalized
   ],
   providers: [...provideInternationalizedDateAdapter()],
   template: `
-    <div
-      forDatePicker
-      #picker="forDatePicker"
-      [(value)]="date"
-      placeholder="Pick a date"
-      ariaLabel="Choose a date"
-    >
-      <button forDatePickerTrigger type="button" class="date-picker-trigger">
+    <div forDatePicker #picker="forDatePicker" [(value)]="date" placeholder="Pick a date">
+      <button
+        forDatePickerTrigger
+        aria-label="Choose a date"
+        type="button"
+        class="date-picker-trigger"
+      >
         <span forDatePickerValue class="date-picker-value"></span>
         <svg class="date-picker-chevron" viewBox="0 0 24 24" aria-hidden="true">
           <path

package/drag-drop/README.md

@@ -157,7 +157,10 @@ whole gesture (and past the drop, while a settle transition runs) it answers the
 selector (`[forDraggable]`, or a composed one such as `[forTableRow]`) and repeats its `data-index`.
 `id` and `data-testid` are stripped from the clone and its whole subtree, so a hook that identifies
 a single element stays unambiguous; anything that **enumerates** items by attribute selector during
-a drag must filter the preview out with `:not([data-for-drag-preview])`.
+a drag must filter the preview out with `:not([data-for-drag-preview])`. The clone is also made
+inert before it joins the document: `name`, `form`, `autofocus` and `autoplay` are stripped, and
+every `iframe`, `object` and `embed` becomes an empty box of the same size, so a cloned radio never
+unchecks the item's own and no cloned media plays or frame reloads.
 
 ## Keyboard
 
@@ -263,6 +266,19 @@ unaffected.
 </li>
 ```
 
+A handle carries `touch-action: none`, so a touch drag on it is not taken by the page's
+scrolling, and the item around it leaves touch scrolling alone. Both follow the item: a handle
+mounted or removed after the first render moves the `touch-action: none` between the handle and
+the item, and a disabled item or list drops it from both.
+
+### Native drag
+
+Images, links and selected text are draggable by the browser itself, and its own drag starts
+before a pointer drag arms. A `[forDraggable]` or `[forFreeDrag]` therefore cancels the native
+`dragstart` of every press it would turn into a pointer drag, so pressing a thumbnail inside an
+item reorders the item instead of dragging a copy of the image. Content outside the item's
+handles, and every press while the item or its list is disabled, keeps its native drag.
+
 ### Nested controls
 
 A control inside a draggable item keeps its press from starting a drag by calling
@@ -286,6 +302,28 @@ the press stays with the control; lifting with the keyboard is unaffected.
 - A canceled `pointerdown` suppresses the compatibility mouse events of that press (`mousedown`,
   `mouseup`), so the control must not rely on them. `click` still fires.
 
+A `[forDraggable]` or `[forFreeDrag]` nested inside another one needs no `preventDefault()`: every
+press inside it is its own, and the item around it never starts a drag from there, even while the
+nested one is disabled. On a board whose columns are the items of one list and hold a list of
+cards each, pressing a card drags the card, and pressing a column outside its cards drags the
+column. Each item lifts with its own `[forDragPreview]` / `[forDragPlaceholder]`, never with one
+declared inside a nested item.
+
+```html
+<div forDropList orientation="horizontal" (dragDrop)="moveColumn($event)">
+  @for (column of columns(); track column.id) {
+  <section forDraggable [dragData]="column">
+    <h2>{{ column.title }}</h2>
+    <ul forDropList (dragDrop)="moveCard(column, $event)">
+      @for (card of column.cards; track card.id) {
+      <li forDraggable [dragData]="card">{{ card.title }}</li>
+      }
+    </ul>
+  </section>
+  }
+</div>
+```
+
 ### Custom preview & placeholder
 
 Place `<ng-template forDragPreview>` and/or `<ng-template forDragPlaceholder>` as direct
@@ -398,7 +436,9 @@ always provided by the consumer via CSS; the library imposes none.
 ```
 
 With no such CSS, `animateReorder` is a graceful no-op: transforms clear instantly and the
-preview is destroyed promptly.
+preview is destroyed promptly. Otherwise the preview is destroyed when its `transform` transition
+ends, and never before that transition's `transition-delay` plus duration have elapsed, wherever
+`transform` sits in a multi-property `transition` list.
 
 ## Orientation
 
@@ -453,10 +493,14 @@ the CSS `translate` property. It is the standalone counterpart to a sortable lis
 pointer-driven way to move an element freely, with optional root-element retargeting, a confinement
 boundary, axis locking, and a controllable position (see the inputs below).
 
-The offset composes with any `transform` the moved element already has, so a dialog centred with
-`transform: translate(-50%, -50%)` stays centred and moves from there. It replaces an inline
-`translate` property of the element's own, so position the element with `transform` or layout
-properties rather than `translate`.
+The offset composes with the `transform` and the `translate` the moved element already has, inline
+or from a stylesheet, so a dialog centred with `transform: translate(-50%, -50%)` or
+`translate: -50% -50%` stays centred and moves from there. The `translate` it composes with is read
+when the element first leaves its rest position, and the element's own `translate` comes back once
+`position` returns to `{ x: 0, y: 0 }`.
+
+Scrolling the page or a scroll container during a drag keeps the element under the pointer, and the
+`boundary` clamp follows the scrolled geometry.
 
 ```html
 <!-- move the whole dialog by its header -->
@@ -483,7 +527,7 @@ properties rather than `translate`.
 | Output      | Payload    | Fires                                                                                          |
 | ----------- | ---------- | ---------------------------------------------------------------------------------------------- |
 | `moveStart` | `{ x; y }` | When a pointer drag starts (the lift-time position).                                           |
-| `moveMove`  | `{ x; y }` | On every armed move, with the live position.                                                   |
+| `moveMove`  | `{ x; y }` | On every armed move, and when a scroll moves the element, with the live position.              |
 | `moveEnd`   | `{ x; y }` | When the drag ends (commit keeps the position; cancel/Escape restores the lift-time snapshot). |
 
 `[forDragHandle]` works inside `[forFreeDrag]` exactly as it does inside `[forDraggable]`: once any
@@ -533,8 +577,12 @@ other list, because their reorder output describes a move within one dataset.
   [virtualCount]="rows().length"
   forVirtualReorder
   (itemReorder)="onReorder($event)"
+  role="list"
+  aria-label="Rows"
 >
-  <div *forVirtualFor="let row of rows()" forDraggable [dragData]="row.id">{{ row.label }}</div>
+  <div *forVirtualFor="let row of rows()" role="listitem" forDraggable [dragData]="row.id">
+    {{ row.label }}
+  </div>
 </div>
 ```