forty-cdk 0.36.0 → 0.38.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/accordion/README.md

@@ -111,14 +111,14 @@ A disabled item cannot be toggled and is skipped by the arrow keys, while stayin
 
 ### `ForAccordion`
 
-| Property      | Type                                | Description                                                                                                                                                             |
-| ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** —                                                                              |
-| `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously.<br>**Default:** `false`                                                                                           |
-| `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Otherwise once any item is open, exactly one stays open.<br>**Default:** `false`            |
-| `disabled`    | `input<boolean>`                    | When true, disables every item: each trigger reflects the native `disabled` attribute and cannot toggle. Composes with a per-item `[disabled]`.<br>**Default:** `false` |
-| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. In horizontal mode ArrowLeft/Right replace ArrowUp/Down.<br>**Default:** `'vertical'`                                             |
-| `dir`         | `input<'ltr' \| 'rtl'>`             | Writing direction. Only relevant in horizontal mode, where it swaps the meaning of Left/Right arrows.<br>**Default:** —                                                 |
+| Property      | Type                                | Description                                                                                                                                                                                    |
+| ------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<readonly string[]>`          | Currently open item values. In single mode the array has 0 or 1 element.<br>**Default:** —                                                                                                     |
+| `multiple`    | `input<boolean>`                    | When true, multiple items can be open simultaneously.<br>**Default:** `false`                                                                                                                  |
+| `collapsible` | `input<boolean>`                    | Single mode only: when true, the open item can be collapsed by clicking it. Otherwise once any item is open, exactly one stays open.<br>**Default:** `false`                                   |
+| `disabled`    | `input<boolean>`                    | When true, disables every item: each trigger reflects the native `disabled` attribute and cannot toggle. Composes with a per-item `[disabled]`.<br>**Default:** `false`                        |
+| `orientation` | `input<'horizontal' \| 'vertical'>` | Layout direction of the trigger list. In horizontal mode ArrowLeft/Right replace ArrowUp/Down.<br>**Default:** `'vertical'`                                                                    |
+| `dir`         | `input<'ltr' \| 'rtl' \| null>`     | Writing direction. Only relevant in horizontal mode, where it swaps the meaning of Left/Right arrows. `null` inherits the nearest `[dir]` / `<html dir>`, else `'ltr'`.<br>**Default:** `null` |
 
 | Data attribute     | Values                     |
 | ------------------ | -------------------------- |

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';

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

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

@@ -188,7 +188,7 @@ export class CalendarDefaultExample {
 
 ### States
 
-One class and one directive, three states. `disabled` turns off focus movement and selection for the whole calendar; `readonly` keeps days focusable and the grid still pages, but clicking or pressing `Enter` no longer changes the selection. Each reflects a root hook (`data-disabled` and `data-readonly`), and the example's stylesheet keys on nothing else.
+One class and one directive, three states. `disabled` turns off focus movement and selection for the whole calendar; `readonly` keeps days focusable and the grid still pages, but clicking or pressing `Enter` no longer changes the selection, and a click moves only the focused day to the clicked cell. Each reflects a root hook (`data-disabled` and `data-readonly`), and the example's stylesheet keys on nothing else.
 
 ### Constraints & week start
 
@@ -253,11 +253,11 @@ Set `selectionMode="range"` and bind `[(range)]` to get date-range selection. In
 
 **Interaction model.** Click (or `Enter` / `Space`) a first cell to set the anchor; the grid enters selecting state. Click (or `Enter` / `Space`) a second cell **in either direction** to commit the range. Clicking before the anchor commits the inverted band `[click, anchor]` (matching the hover preview) rather than starting over. There is no separate "start over" gesture and no explicit Escape-to-cancel: once a range is committed, the next click begins a fresh anchor, and `range` keeps the committed range until the second click replaces it.
 
-**Keyboard in range mode.** `Enter` / `Space` on the focused cell sets the anchor on the first press and commits on the second (same key as single mode). While selecting, arrow / `Home` / `End` / `PageUp` / `PageDown` move the keyboard focus and update the preview cursor (the keyboard equivalent of pointer hover); moving before the anchor previews (and commits) the inverted band.
+**Keyboard in range mode.** `Enter` / `Space` on the focused cell sets the anchor on the first press and commits on the second (same key as single mode). While selecting, arrow / `Home` / `End` / `PageUp` / `PageDown` move the keyboard focus and update the preview cursor (the keyboard equivalent of pointer hover); moving before the anchor previews (and commits) the inverted band. The preview follows whichever device moved last: a keyboard move, a selection or a page change takes the cursor back from a pointer resting on the grid, and the pointer takes it again when it enters another cell.
 
 **`min` / `max` / `isDateUnavailable`** still gate both endpoints. An unavailable or out-of-bounds date cannot become an anchor or an end.
 
-**`minRangeLength` / `maxRangeLength`.** Constrain the inclusive day count of the committed range. A click that would violate either limit is a no-op (the anchor is preserved). Both default to `null` (unconstrained).
+**`minRangeLength` / `maxRangeLength`.** Constrain the inclusive day count of the committed range. A click that would violate either limit commits nothing: the anchor is preserved, and the clicked cell becomes the focused day and the end of the preview. Both default to `null` (unconstrained).
 
 **Cell facets (range mode).** Four boolean `data-*` attributes are added to `[forCalendarCell]`:
 
@@ -290,7 +290,7 @@ Set `selectionMode="range"` and bind `[(range)]` to get date-range selection. In
 }
 ```
 
-**`aria-selected`** in range mode is `"true"` across every committed-range cell (inclusive). During selecting (range null), it is `"false"` everywhere.
+**`aria-selected`** in range mode is `"true"` across every committed-range cell (inclusive), and the grid carries `aria-multiselectable="true"`. While a new anchor is pending, `aria-selected` is `"false"` everywhere, but `range` keeps the previously committed range until the second click replaces it.
 
 **Scope.** Range mode is day-granular only: `granularity` / time is orthogonal and not supported alongside it.
 
@@ -306,7 +306,7 @@ Set `selectionMode="range"` and bind `[(range)]` to get date-range selection. In
 | `goToMonth(month)`  | Set the visible month within the current visible year. `month` is **1-12**.             |
 | `goToYear(year)`    | Set the visible year, keeping the current visible month.                                |
 
-All three methods re-apply the user's intended day-of-month (clamped to the target month's length), clamp the result into `[min, max]`, and announce the new period politely when the visible month changes. They keep DOM focus on the caller and do not move focus into the grid. They are a no-op while the calendar is `disabled`.
+All three methods re-apply the user's intended day-of-month (clamped to the target month's length), clamp the result into `[min, max]`, and announce the new period politely when the period the active view shows changes. They keep DOM focus on the caller and do not move focus into the grid. They are a no-op while the calendar is `disabled`.
 
 ### Read accessors and predicates
 
@@ -395,15 +395,17 @@ The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`
 
 `ForCalendar` supports two additional views (**month grid** and **year grid**) so users can jump quickly to a different month or year without paging one at a time. All three views share a single `[(view)]` model and the same `focusedDate` cursor.
 
+The heading's `label()` follows the active view, with the same text as the view trigger: the month and year in day view, the year in month view, the block of years in year view. Every grid is named by the heading, so each one is named after the period it shows. A keyboard move or a prev / next press that changes that period announces it. Drilling down changes no value, so a `readonly` calendar still drills from a year to its months and from a month to its days.
+
 ### Pieces
 
-| Class                    | Selector                   | Role                                                                                                                    |
-| ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `ForCalendarViewTrigger` | `[forCalendarViewTrigger]` | Button that cycles the view: day → month → year. Auto-disabled when the calendar is disabled.                           |
-| `ForCalendarMonthGrid`   | `[forCalendarMonthGrid]`   | 4×3 month grid (`role="grid"`). Exposes `rows()`, an array of `CalendarMonthRow`, each with three `CalendarYearOption`. |
-| `ForCalendarMonthCell`   | `[forCalendarMonthCell]`   | One month (`role="gridcell"`). Requires `[month]` (1–12). Click drills down to day view for that month.                 |
-| `ForCalendarYearGrid`    | `[forCalendarYearGrid]`    | 4×3 year grid (`role="grid"`). Exposes `rows()`, an array of `CalendarYearRow`, each with three `CalendarYearOption`.   |
-| `ForCalendarYearCell`    | `[forCalendarYearCell]`    | One year (`role="gridcell"`). Requires `[year]`. Click drills down to month view for that year.                         |
+| Class                    | Selector                   | Role                                                                                                                     |
+| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `ForCalendarViewTrigger` | `[forCalendarViewTrigger]` | Button that cycles the view: day → month → year. Auto-disabled when the calendar is disabled.                            |
+| `ForCalendarMonthGrid`   | `[forCalendarMonthGrid]`   | 4×3 month grid (`role="grid"`). Exposes `rows()`, an array of `CalendarMonthRow`, each with three `CalendarMonthOption`. |
+| `ForCalendarMonthCell`   | `[forCalendarMonthCell]`   | One month (`role="gridcell"`). Requires `[month]` (1–12). Click drills down to day view for that month.                  |
+| `ForCalendarYearGrid`    | `[forCalendarYearGrid]`    | 4×3 year grid (`role="grid"`). Exposes `rows()`, an array of `CalendarYearRow`, each with three `CalendarYearOption`.    |
+| `ForCalendarYearCell`    | `[forCalendarYearCell]`    | One year (`role="gridcell"`). Requires `[year]`. Click drills down to month view for that year.                          |
 
 ### `view` model — `ForCalendar`
 
@@ -571,6 +573,7 @@ Implements the [WAI-ARIA Grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/
 - **`aria-labelledby`** wires the grid to the heading so it names the visible period. Paging the month is announced through a dedicated off-screen `aria-live="polite"` region (owned by `[forCalendar]`), so the period is read on navigation without the heading double-announcing as both a live region and the grid's label.
 - **`aria-label`** on every cell carries the full localized date (e.g. `"Monday, June 15, 2026"`) so screen readers announce the whole date, not the bare day number that stays the cell's visible content. Outside-month padding days are suffixed (`" (outside month)"`) so they are distinguishable. Override the format via `ForCalendar`'s `dateLabel` input.
 - **`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`.
 
@@ -609,7 +612,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/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,13 +166,17 @@ 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                                      |
 | --------------- | ------------------------------------------- |
 | `data-state`    | `checked` \| `unchecked` \| `indeterminate` |
 | `data-disabled` | present \| absent                           |
 | `data-readonly` | present \| absent                           |
+| `data-touched`  | present \| absent                           |
+| `data-dirty`    | present \| absent                           |
+| `data-pending`  | present \| absent                           |
+| `data-invalid`  | present \| absent                           |
 
 ### `ForCheckboxIndicator`
 

package/combobox/README.md

@@ -196,7 +196,23 @@ The primitive never owns the scroll container, so it virtualizes with any window
 
 ## API
 
-Input tables are not yet tabulated for this primitive. See the feature sections below for documented inputs and the prose descriptions of each input.
+Only the positioning inputs every anchored root inherits are tabulated for this primitive so far. See the feature sections below for the other inputs and their prose descriptions.
+
+### `ForCombobox` positioning inputs
+
+| Property              | Type                                    | Description                                                                                                                                                                           |
+| --------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `side`                | `input<FloatingSide>`                   | Anchor side (`'top'` / `'right'` / `'bottom'` / `'left'`). Falls back to `provideForComboboxDefaults`.<br>**Default:** `'bottom'`                                                     |
+| `align`               | `input<FloatingAlign>`                  | Alignment along `side` (`'start'` / `'center'` / `'end'`). Falls back to `provideForComboboxDefaults`.<br>**Default:** `'start'`                                                      |
+| `sideOffset`          | `input<number>`                         | Gap (px) between the anchor and the content along the main axis. Falls back to `provideForComboboxDefaults`.<br>**Default:** `4`                                                      |
+| `alignOffset`         | `input<number>`                         | Gap (px) along the cross axis (parallel to `side`).<br>**Default:** `0`                                                                                                               |
+| `avoidCollisions`     | `input<boolean>`                        | When `true`, `flip` and `shift` keep the content inside the viewport. Set `false` for strict positioning where overflow is acceptable.<br>**Default:** `true`                         |
+| `collisionPadding`    | `input<number>`                         | Padding (px) for the `flip` / `shift` / `size` collision middlewares. Falls back to `provideForComboboxDefaults`.<br>**Default:** `8`                                                 |
+| `sticky`              | `input<'partial' \| 'always' \| false>` | `'always'` keeps the requested placement even when the content leaves the viewport. `'partial'` and `false` let `shift` slide it back into view.<br>**Default:** `'partial'`          |
+| `hideWhenDetached`    | `input<boolean>`                        | When `true`, the content carries `data-detached` while the anchor has scrolled out of every clipping ancestor, so CSS can hide it.<br>**Default:** `false`                            |
+| `clipUntilPositioned` | `input<boolean>`                        | Clips the content until its first position resolves, so it never flashes at the viewport corner. Set `false` so an `animate.enter` plays from its first frame.<br>**Default:** `true` |
+
+The content anchors to the field box when a `[forComboboxAnchor]` is present; see [Anchoring to a field box](#anchoring-to-a-field-box).
 
 ### Data attributes
 
@@ -205,6 +221,10 @@ Input tables are not yet tabulated for this primitive. See the feature sections
 | `[forCombobox]`          | `data-state`       | `open` \| `closed`                                                  |
 | `[forCombobox]`          | `data-disabled`    | present / absent                                                    |
 | `[forCombobox]`          | `data-readonly`    | present / absent                                                    |
+| `[forCombobox]`          | `data-touched`     | present / absent                                                    |
+| `[forCombobox]`          | `data-dirty`       | present / absent                                                    |
+| `[forCombobox]`          | `data-pending`     | present / absent                                                    |
+| `[forCombobox]`          | `data-invalid`     | present / absent                                                    |
 | `[forComboboxInput]`     | `data-state`       | `open` \| `closed`                                                  |
 | `[forComboboxInput]`     | `data-disabled`    | present / absent                                                    |
 | `[forComboboxToggle]`    | `data-state`       | `open` \| `closed`                                                  |
@@ -363,7 +383,9 @@ An action:
 - **never touches `value` / `options()`.** It registers in a collection separate
   from options, so `options()`, `aria-setsize`, and `aria-posinset` are
   unaffected and activation emits `(activate)` instead of mutating `[(value)]`. The
-  consumer decides what happens and whether to close the popup afterwards.
+  consumer decides what happens and whether to close the popup afterwards. In the
+  editable anatomy a close from `(activate)` returns focus to the input, unless
+  your handler already moved it out of the popup.
 - **is `role="button"`, not `role="option"`.** Assistive tech announces it as an
   action, not as one of N choices.
 - **is reached by Tab, not the arrow keys** (see below), so it stays reachable no
@@ -395,10 +417,10 @@ outside-focus dismissal checks, exactly like the input.
 
 ### Action item API
 
-| Member       | Type           | Notes                                                                                                      |
-| ------------ | -------------- | ---------------------------------------------------------------------------------------------------------- |
-| `[disabled]` | `boolean`      | Drops the action out of the focus ring (`tabindex` removed), reflects `aria-disabled`, ignores activation. |
-| `(activate)` | `output<void>` | Fired on click / Enter / Space. Never mutates `[(value)]`.                                                 |
+| Member       | Type           | Notes                                                                                                            |
+| ------------ | -------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `[disabled]` | `boolean`      | Drops the action out of the focus ring (it keeps `tabindex="-1"`), reflects `aria-disabled`, ignores activation. |
+| `(activate)` | `output<void>` | Fired on click / Enter / Space. Never mutates `[(value)]`.                                                       |
 
 `[forComboboxAction]` host-binds `role="button"`, `type="button"` (on a native
 `<button>` host only, leaving any other element with no `type`), a primitive-managed
@@ -575,7 +597,7 @@ Each dismiss reason emits a vetoable event from `[forCombobox]`. Call `preventDe
 
 The two anatomies have different focus models:
 
-- **Editable anatomy**: the input retains focus the entire time the listbox is open and on close; the active option is tracked via `aria-activedescendant`, never via `.focus()`. There is no automatic focus move, so `(autoFocusOnOpen)` / `(autoFocusOnClose)` never fire. If you need to move focus elsewhere, do it from your own keydown handler. The combobox won't fight you.
+- **Editable anatomy**: the input retains focus the entire time the listbox is open and on close; the active option is tracked via `aria-activedescendant`, never via `.focus()`. The one automatic move is back to the input, when a close unmounts the popup while focus is inside it (a `[forComboboxAction]` whose `(activate)` closes the popup), gated by `[returnFocus]`. `(autoFocusOnOpen)` / `(autoFocusOnClose)` never fire. If you need to move focus elsewhere, do it from your own keydown handler. The combobox won't fight you.
 - **Picker anatomy**: focus moves into the input on open and returns to the `[forComboboxTrigger]` on close, exactly like the other trigger-anchored overlays (`[forPopover]`, `[forDropdownMenu]`, `[forSelect]`). Both moves emit a vetoable event on `[forCombobox]`; call `preventDefault()` to keep focus where it is:
 
 | Output               | When                                        | `preventDefault()` effect   |
@@ -822,6 +844,7 @@ Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patte
 - `[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.
 - `[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.
 - In single mode, `aria-selected="true"` follows the activedescendant (the option Enter would activate). In multi mode it follows membership in `value()`, so every selected option carries `aria-selected="true"` simultaneously.
 - `data-state="checked" | "unchecked"` always reflects membership in `value()`, so consumers can paint a checkmark icon with pure CSS regardless of mode.
 - `data-highlighted=""` marks the option that is the current `aria-activedescendant`. Because focus stays on the `<input>`, there is no `:focus` on the option to style. `data-highlighted` is the canonical CSS hook.

package/context-menu/README.md

@@ -88,8 +88,13 @@ The same menu vocabulary the Dropdown Menu exposes, anchored to the pointer on r
 | `sideOffset`                | `input<number>`                                           | Gap (px) between the pointer and the menu along the main axis.<br>**Default:** `0`                                                                                                                                                                                                                                                                 |
 | `alignOffset`               | `input<number>`                                           | Gap (px) along the cross axis (parallel to `side`).<br>**Default:** `0`                                                                                                                                                                                                                                                                            |
 | `fallbackAxisSideDirection` | `input<'none' \| 'start' \| 'end'>`                       | When both sides of the preferred axis overflow, lets `flip` drop the menu to a perpendicular side instead of clipping. `'none'` keeps only the opposite same-axis placement. The default is read from `provideForContextMenuDefaults` for the surrounding scope. Set it once for the whole app rather than per call site.<br>**Default:** `'none'` |
+| `avoidCollisions`           | `input<boolean>`                                          | When `true`, `flip` and `shift` keep the content inside the viewport. Set `false` for strict positioning where overflow is acceptable.<br>**Default:** `true`                                                                                                                                                                                      |
+| `collisionPadding`          | `input<number>`                                           | Padding (px) for the `flip` / `shift` / `size` collision middlewares. The default is read from `provideForContextMenuDefaults` for the surrounding scope.<br>**Default:** `8`                                                                                                                                                                      |
+| `sticky`                    | `input<'partial' \| 'always' \| false>`                   | `'always'` keeps the requested placement even when the content leaves the viewport. `'partial'` and `false` let `shift` slide it back into view.<br>**Default:** `'partial'`                                                                                                                                                                       |
+| `hideWhenDetached`          | `input<boolean>`                                          | When `true`, the content carries `data-detached` while the anchor has scrolled out of every clipping ancestor, so CSS can hide it.<br>**Default:** `false`                                                                                                                                                                                         |
+| `clipUntilPositioned`       | `input<boolean>`                                          | Clips the content until its first position resolves, so it never flashes at the viewport corner. Set `false` so an `animate.enter` plays from its first frame.<br>**Default:** `true`                                                                                                                                                              |
 | `loop`                      | `input<boolean>`                                          | Whether arrow navigation wraps.<br>**Default:** `true`                                                                                                                                                                                                                                                                                             |
-| `dir`                       | `input<string>`                                           | Writing direction. In RTL the swap is automatic: ArrowLeft opens submenus and ArrowRight closes them. Inherited by every nested `[forMenuSub]` underneath unless overridden.<br>**Default:** `'ltr'`                                                                                                                                               |
+| `dir`                       | `input<'ltr' \| 'rtl' \| null>`                           | Writing direction. `null` inherits the nearest `[dir]` / `<html dir>`, else `'ltr'`. In RTL the swap is automatic: ArrowLeft opens submenus and ArrowRight closes them. Inherited by every nested `[forMenuSub]` underneath unless overridden.<br>**Default:** `null`                                                                              |
 | `disabled`                  | `input<boolean>`                                          | When `true`, the contextmenu event falls through to the native browser menu.<br>**Default:** `false`                                                                                                                                                                                                                                               |
 | `dismissible`               | `input<boolean>`                                          | When `false`, Escape and outside interactions don't close.<br>**Default:** `true`                                                                                                                                                                                                                                                                  |
 | `returnFocus`               | `input<boolean>`                                          | When `true`, focus returns on close to the trigger element, or to the focused element inside it that a keyboard activation started from.<br>**Default:** `true`                                                                                                                                                                                    |
@@ -134,10 +139,11 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 
 ## Behavior notes
 
-- **Trigger is NOT exempt** from outside-pointer / outside-focus checks. Unlike DropdownMenu (where the trigger button toggles via its own click handler), the context-menu region is treated like any other "outside" element: a left-click on the region while the menu is open closes it. Right-clicking again immediately reopens at the new position. This is a full close → open cycle, not an in-place reposition: re-right-clicking while the menu is already open tears the surface down and rebuilds it (so any `animate.enter` / `animate.leave` replays and focus resets). Keep enter/leave animations cheap, or gate expensive ones, since a user can fire this rapidly. The directive deliberately exempts nothing, so there is no smooth reposition path to attach to.
+- **Trigger is NOT exempt** from outside-pointer / outside-focus checks. Unlike DropdownMenu (where the trigger button toggles via its own click handler), the context-menu region is treated like any other "outside" element: a left-click on the region while the menu is open closes it. Right-clicking again reopens the menu at the new position. When the close and the reopen land in the same task, as they do where the browser fires `contextmenu` on mouse down (macOS, Linux), the mounted surface is reused rather than rebuilt: it moves to the new point without replaying `animate.enter` / `animate.leave`, and focus moves back to its first item, honouring `(autoFocusOnOpen)`. Where `contextmenu` follows mouse up (Windows), the surface renders closed in between and is mounted again, so its animations replay. Keep enter/leave animations cheap, or gate expensive ones, since a user can fire this rapidly.
+- **Nested regions.** A `[forContextMenuTrigger]` inside another one takes precedence: a right-click, `Shift+F10`, the `ContextMenu` key or a long-press on the inner region opens the inner menu only, and the outer menu opens from the parts of its region the inner one does not cover. A disabled inner region lets the outer menu open. The trigger also ignores a `contextmenu` or key press that a handler beneath it already cancelled with `preventDefault()`, so calling it on a descendant is how you keep a context menu from opening there.
 - **Virtual anchor.** Right-click captures a 0×0 rect at the pointer location. `Shift+F10` and `ContextMenu` snapshot the bounding rect of the focused element (or the trigger if focus is on it directly), so the menu floats off the element under attention. Closing a keyboard-opened menu returns focus to that same element, so a row in a roving-tabindex list keeps its position; when a menu action removed it, focus falls back to the region. Both forms feed floating-ui's `flip` and `shift` middleware, so corners and screen edges work without special-casing.
 - **Keyboard activators only fire while focus is inside the trigger.** Keyboard events dispatch to the focused element, so `Shift+F10` / `ContextMenu` anywhere outside the trigger goes to the browser default. The trigger is focusable by default (host-bound `tabindex="-1"`), so this works out of the box and focus can return to it programmatically when the menu closes. Your own `tabindex` wins over that default: use `tabindex="0"` if you want the region itself reachable via Tab.
-- **Native menu suppressed.** The trigger calls `event.preventDefault()` on `contextmenu` and on the keyboard activators. Set `disabled` to let the browser's native menu surface for that region.
+- **Native menu suppressed.** The trigger calls `event.preventDefault()` on `contextmenu` and on the keyboard activators. After a keyboard open it also cancels the `contextmenu` the platform raises when the key is released (Windows), wherever focus has moved by then, so the browser's menu is not painted over the one that just opened. Set `disabled` to let the browser's native menu surface for that region.
 - **An open that renders nothing closes again.** When a right-click, `Shift+F10`, the `ContextMenu` key or a long-press opens a menu whose template renders no `[forMenuContent]`, the trigger closes it after the next render with reason `'programmatic'`, and dev mode logs `FORCDK-CONTEXT-MENU-002` once. The native menu cannot come back for that gesture, because it was already suppressed, so bind `[disabled]` to the same condition that renders the content: `[disabled]="!hasActions(col)"` beside `@if (hasActions(col))`.
 - **Touch long-press.** The trigger runs its own long-press timer (a `touch` `pointerdown` held ~500 ms, without lifting or moving past a small tolerance, opens the menu at the touch point). This is required because iOS Safari never fires the `contextmenu` event a long-press synthesizes elsewhere; where the browser does synthesize it (Android, desktop touch emulation) the two paths stay mutually exclusive, so the menu opens exactly once. For the press to survive on iOS, suppress the native callout / text-selection on the trigger with CSS, since otherwise the OS gesture cancels the press:
 

package/date-field/README.md

@@ -87,7 +87,7 @@ export class DateFieldDefaultExample {
 
 ### Date & time
 
-With a time-capable adapter, a `granularity` coarser than `'day'` appends hour / minute segments and the value becomes a `CalendarDateTime`. A 12-hour cycle adds an AM/PM segment you toggle with `↑` / `↓` or by typing `a` / `p`.
+With a time-capable adapter, a `granularity` finer than `'day'` appends hour / minute segments and the value becomes a `CalendarDateTime`. A 12-hour cycle adds an AM/PM segment you toggle with `↑` / `↓` or by typing `a` / `p`.
 
 ### Localized segment labels
 
@@ -99,14 +99,14 @@ With a time-capable adapter, a `granularity` coarser than `'day'` appends hour /
 
 ```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
@@ -139,7 +139,7 @@ export class DobFormField {
 
 ### Date & time range
 
-With a time-capable adapter, a `granularity` coarser than `'day'` appends time segments to both endpoints and the value becomes a `CalendarDateTime` range, which is handy for a check-in to check-out with times. A 12-hour `hourCycle` adds an AM/PM segment to each side.
+With a time-capable adapter, a `granularity` finer than `'day'` appends time segments to both endpoints and the value becomes a `CalendarDateTime` range, which is handy for a check-in to check-out with times. A 12-hour `hourCycle` adds an AM/PM segment to each side.
 
 ### Range in Signal Forms
 
@@ -154,7 +154,7 @@ With a time-capable adapter, a `granularity` coarser than `'day'` appends time s
 | `value`       | `model<D \| null>`                               | Two-way bindable entered date, or `null` while any segment is empty. The `FormValueControl` backing.<br>**Default:** `null`                                                   |
 | `minDate`     | `input<D \| null>`                               | Minimum date (inclusive). A composed value below it is clamped up. Named `minDate` (see note below).<br>**Default:** `null`                                                   |
 | `maxDate`     | `input<D \| null>`                               | Maximum date (inclusive). A composed value above it is clamped down.<br>**Default:** `null`                                                                                   |
-| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` is date-only; coarser-than-day appends time segments. See below.<br>**Default:** `'day'`                                                         |
+| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` is date-only; a finer granularity appends time segments. See below.<br>**Default:** `'day'`                                                      |
 | `hourCycle`   | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the time segments. `null` → the scope's `hourCycle`, then the locale. 12-hour adds the AM/PM segment.<br>**Default:** `null`                             |
 | `locale`      | `input<string \| null>`                          | BCP 47 locale driving segment order, separators, and month name. `null` → the adapter's `locale()`, then the runtime locale.<br>**Default:** `null`                           |
 | `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty. Unspecified parts fall back to the scope's `placeholder`, then to `dd` / `mm` / `yyyy` / `hh` / `mm` / `ss` / `--`.<br>**Default:** `{}` |
@@ -181,6 +181,11 @@ A native reset of the owning `<form>` returns `value` to what it held when the f
 | `[forDateField]`        | `data-disabled`    | present \| absent |
 | `[forDateField]`        | `data-readonly`    | present \| absent |
 | `[forDateField]`        | `data-empty`       | present \| absent |
+| `[forDateField]`        | `data-required`    | present \| absent |
+| `[forDateField]`        | `data-touched`     | present \| absent |
+| `[forDateField]`        | `data-dirty`       | present \| absent |
+| `[forDateField]`        | `data-pending`     | present \| absent |
+| `[forDateField]`        | `data-invalid`     | present \| absent |
 | `[forDateFieldSegment]` | `data-highlighted` | present \| absent |
 | `[forDateFieldSegment]` | `data-placeholder` | present \| absent |
 | `[forDateFieldSegment]` | `data-disabled`    | present \| absent |
@@ -284,7 +289,7 @@ readonly booking = form(this.model);
 | `value`       | `model<DateRange<D> \| null>`                    | Two-way bindable committed range, or `null` while incomplete or out of order. The `FormValueControl` backing.<br>**Default:** `null`                |
 | `minDate`     | `input<D \| null>`                               | Minimum date (inclusive) for both endpoints. A composed endpoint below it is clamped up. Named `minDate` (see note below).<br>**Default:** `null`   |
 | `maxDate`     | `input<D \| null>`                               | Maximum date (inclusive) for both endpoints. A composed endpoint above it is clamped down.<br>**Default:** `null`                                   |
-| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision shared by both endpoints. `'day'` is date-only; coarser-than-day appends time segments.<br>**Default:** `'day'`                 |
+| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision shared by both endpoints. `'day'` is date-only; a finer granularity appends time segments.<br>**Default:** `'day'`              |
 | `hourCycle`   | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the time segments. `null` → the scope's `hourCycle`, then the locale. 12-hour adds the AM/PM segment.<br>**Default:** `null`   |
 | `locale`      | `input<string \| null>`                          | BCP 47 locale driving segment order, separators, and month name. `null` → the adapter's `locale()`, then the runtime locale.<br>**Default:** `null` |
 | `placeholder` | `input<Partial<Record<SegmentType, string>>>`    | Per-segment placeholder while empty, applied to both endpoints. Unspecified parts fall back to the scope's `placeholder`.<br>**Default:** `{}`      |
@@ -297,7 +302,7 @@ The endpoint groups each accept an `ariaLabel` input for their own group label,
 
 > **Why `minDate` / `maxDate`, not `min` / `max`?** Beyond the reason above, `FormUiControl.min` / `max` are additionally typed `NonNullable<TValue>` (the range object itself), which is meaningless as a bound.
 
-`[forDateRangeField]` reflects the same `data-disabled` / `data-readonly` / `data-empty` hooks as `[forDateField]`, plus `data-range-error`; `[forDateRangeFieldSegment]` reflects the same four segment hooks. `data-empty` marks the field only while **both** endpoints are entirely empty; a partially-filled or complete-but-disordered range is **not** empty.
+`[forDateRangeField]` reflects the same root hooks as `[forDateField]` (`data-disabled` / `data-readonly` / `data-empty` / `data-required` and the four form-state hooks), plus `data-range-error`; `[forDateRangeFieldSegment]` reflects the same four segment hooks. `data-empty` marks the field only while **both** endpoints are entirely empty; a partially-filled or complete-but-disordered range is **not** empty.
 
 ### Ordering
 
@@ -315,14 +320,14 @@ Each endpoint is its own tab stop, so `Tab` moves start group → end group →
 
 Key behavior applies per segment. Horizontal arrows mirror under `dir="rtl"`.
 
-| Key                        | Behavior                                                                                |
-| -------------------------- | --------------------------------------------------------------------------------------- |
-| **0–9**                    | Type the value; auto-advances to the next segment when full.                            |
-| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today.                |
-| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                                          |
-| **Home / End**             | Jump to the segment minimum / maximum.                                                  |
-| **Backspace**              | Delete the last entered digit; the value becomes `null` when the last digit is removed. |
-| **Delete**                 | Clear the whole segment (the value becomes `null` until refilled).                      |
+| Key                        | Behavior                                                                                                                                                                       |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.                                                                                                                   |
+| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. An empty date part seeds from today; an empty hour from its minimum (midnight, or 1 AM in 12-hour), minute and second from 0. |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                                                                                                                                 |
+| **Home / End**             | Jump to the segment minimum / maximum.                                                                                                                                         |
+| **Backspace**              | Delete the last entered digit; the value becomes `null` when the last digit is removed.                                                                                        |
+| **Delete**                 | Clear the whole segment (the value becomes `null` until refilled).                                                                                                             |
 
 The day clamps to the current month's length (e.g. 31 → 28 in February), and a composed value is clamped into `[minDate, maxDate]`. While focus stays in the field its segments keep what was entered, so editing one part never rewrites the others; they show the clamped value once focus leaves. Stepping the hour skips a wall-clock hour the day does not have, such as a spring-forward DST gap.
 
@@ -336,18 +341,22 @@ Composes the [WAI-ARIA Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patte
 - **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`.
 - **`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]` on the root group.
+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.
 
 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).
 
+A segment is an editing host, so the browser paints a text caret in the focused one. Hide it with `caret-color: transparent` when your highlight already marks that segment.
+
 ```css
 .date-field-segment[data-placeholder] {
   color: GrayText;
 }
 .date-field-segment[data-highlighted] {
+  caret-color: transparent;
   background: Highlight;
   color: HighlightText;
 }