forty-cdk 0.36.0 → 0.37.0

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/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`.
 

package/checkbox/README.md

@@ -173,6 +173,10 @@ export class DemoCheckout {
 | `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
 
@@ -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;
 }

package/date-picker/README.md

@@ -11,7 +11,7 @@ A trigger that opens a floating calendar to pick a date, composing ForCalendar i
 
 Reinterpreted idiomatically for modern Angular: a focusable trigger that opens a floating surface wrapping a projected [`ForCalendar`](../calendar/README.md).
 
-`ForDatePicker` is the root **and** the form value: it implements `FormValueControl<D | null>` from `@angular/forms/signals`, so it auto-wires with `[formField]`. The trigger is the focusable control that carries `name` / `disabled` / `invalid`; selection state flows root → projected calendar via `[(value)]`. The library reuses its existing overlay stack (trigger-anchored Popover positioning, dismissible layer, return-focus) rather than re-implementing positioning, dismissal, or focus return. The modal opt-in routes through the shared modal shell (focus trap + inert background + scroll lock).
+`ForDatePicker` is the root **and** the form value: it implements `FormValueControl<D | null>` from `@angular/forms/signals`, so it auto-wires with `[formField]`. The trigger is the focusable control that carries `disabled` / `invalid` / `required` / `readonly`, while `name` submits the value through a hidden input (see [Native submission](#native-submission)); selection state flows root → projected calendar via `[(value)]`. The library reuses its existing overlay stack (trigger-anchored Popover positioning, dismissible layer, return-focus) rather than re-implementing positioning, dismissal, or focus return. The modal opt-in routes through the shared modal shell (focus trap + inert background + scroll lock).
 
 ## When to choose
 
@@ -187,7 +187,7 @@ With `granularity="minute"` and a time-capable adapter the picker becomes a date
 
 ### Constraints
 
-`minDate` disables every day before today and `isDateUnavailable` blocks weekends. The picker forwards both to the projected calendar, where they reflect `aria-disabled` and refuse selection while the arrow keys still travel across them. Only an available weekday can be committed.
+`minDate` disables every day before today and `isDateUnavailable` blocks weekends. Forward both to the projected calendar's `[min]` / `[isDateUnavailable]`, where they reflect `aria-disabled` and refuse selection while the arrow keys still travel across them. Only an available weekday can be committed. The picker does not forward them itself: on a calendar bound without them, it clamps an out-of-range pick into `[minDate, maxDate]` and commits an unavailable date as picked.
 
 ### Range selection
 
@@ -197,35 +197,46 @@ Open the picker and click a first day: the trigger keeps its placeholder, becaus
 
 ### `ForDatePicker`
 
-| Property            | Type                                             | Description                                                                                                                                                                                                    |
-| ------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `value`             | `model<D \| null>`                               | Two-way bindable selected date. `(valueChange)` fires only on internal commits.<br>**Default:** `null`                                                                                                         |
-| `open`              | `model<boolean>`                                 | Two-way bindable surface visibility. `(openChange)` fires only on internal transitions.<br>**Default:** `false`                                                                                                |
-| `minDate`           | `input<D \| null>`                               | Minimum selectable date (inclusive). Forward to the projected calendar's `[min]`.<br>**Default:** `null`                                                                                                       |
-| `maxDate`           | `input<D \| null>`                               | Maximum selectable date (inclusive). Forward to the projected calendar's `[max]`.<br>**Default:** `null`                                                                                                       |
-| `isDateUnavailable` | `input<(date: D) => boolean>`                    | Per-date predicate. Forward to the projected calendar's `[isDateUnavailable]`.<br>**Default:** `() => false`                                                                                                   |
-| `closeOnSelect`     | `input<boolean>`                                 | Close the surface after a date is picked. Honoured at `granularity="day"`, and at any granularity with `anatomy="field"`.<br>**Default:** `true`                                                               |
-| `anatomy`           | `input<'trigger' \| 'field'>`                    | Which piece is the control. `'field'` makes a projected `[forDateField]` the control and the trigger a plain button; see [Field anatomy](#field-anatomy).<br>**Default:** `'trigger'`                          |
-| `granularity`       | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` (default) is a pure date picker; coarser-than-day off composes a time field.<br>**Default:** `'day'`                                                                              |
-| `hourCycle`         | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the value display; a projected time field takes `resolvedHourCycle()`.<br>**Default:** `null` → the scope's `hourCycle` (`provideForDatePickerDefaults`), then the locale                 |
-| `resolvedHourCycle` | `Signal<12 \| 24 \| null>`                       | The effective cycle: `hourCycle`, then the scope's, or `null` for the locale. Bind it to a projected time field's `[hourCycle]`.<br>**Default:** —                                                             |
-| `modal`             | `input<boolean>`                                 | Trap focus + inert background + scroll lock (centered dialog) instead of an anchored popover.<br>**Default:** `false`                                                                                          |
-| `dismissible`       | `input<boolean>`                                 | Escape / outside-pointer dismiss the surface.<br>**Default:** `true`                                                                                                                                           |
-| `returnFocus`       | `input<boolean>`                                 | Return focus to the trigger on close.<br>**Default:** `true`                                                                                                                                                   |
-| `formatOptions`     | `input<Intl.DateTimeFormatOptions>`              | Options for the text rendered by `[forDatePickerValue]`.<br>**Default:** `{ year: 'numeric', month: 'long', day: 'numeric' }`                                                                                  |
-| `locale`            | `input<string \| null>`                          | BCP 47 locale for the text rendered by `[forDatePickerValue]`. Not forwarded to the projected calendar, so bind its `[locale]` too.<br>**Default:** `null` → the adapter's `locale()`, then the runtime locale |
-| `placeholder`       | `input<string>`                                  | Fallback text for `[forDatePickerValue]` when empty.<br>**Default:** `''`                                                                                                                                      |
-| `side` / `align`    | `input`                                          | Anchored placement (popover mode only). Defaults from `provideForDatePickerDefaults` / `provideForDateRangePickerDefaults`.<br>**Default:** `'bottom'` / `'start'`                                             |
-| `dir`               | `input<'ltr' \| 'rtl' \| null>`                  | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir`                                                                                                          |
-
-Plus the shared `FormUiControl` inputs from the base (`disabled`, `readonly`, `required`, `invalid`, `pending`, `dirty`, `name`, `errors`, and the `touched` model) and the floating tunables (`sideOffset`, `alignOffset`, `avoidCollisions`, `collisionPadding`, `sticky`, `hideWhenDetached`).
-
-A native reset of the owning `<form>` returns `value` to what it held when the picker first rendered. In the [field anatomy](#field-anatomy) it also drops a partly typed entry in the projected field.
+| Property              | Type                                             | Description                                                                                                                                                                                                    |
+| --------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`               | `model<D \| null>`                               | Two-way bindable selected date. `(valueChange)` fires only on internal commits.<br>**Default:** `null`                                                                                                         |
+| `open`                | `model<boolean>`                                 | Two-way bindable surface visibility. `(openChange)` fires only on internal transitions.<br>**Default:** `false`                                                                                                |
+| `minDate`             | `input<D \| null>`                               | Minimum selectable date (inclusive). Forward to the projected calendar's `[min]`.<br>**Default:** `null`                                                                                                       |
+| `maxDate`             | `input<D \| null>`                               | Maximum selectable date (inclusive). Forward to the projected calendar's `[max]`.<br>**Default:** `null`                                                                                                       |
+| `isDateUnavailable`   | `input<(date: D) => boolean>`                    | Per-date predicate. Forward to the projected calendar's `[isDateUnavailable]`.<br>**Default:** `() => false`                                                                                                   |
+| `closeOnSelect`       | `input<boolean>`                                 | Close the surface after a date is picked. Honoured at `granularity="day"`, and at any granularity with `anatomy="field"`.<br>**Default:** `true`                                                               |
+| `anatomy`             | `input<'trigger' \| 'field'>`                    | Which piece is the control. `'field'` makes a projected `[forDateField]` the control and the trigger a plain button; see [Field anatomy](#field-anatomy).<br>**Default:** `'trigger'`                          |
+| `granularity`         | `input<'day' \| 'hour' \| 'minute' \| 'second'>` | Date-time precision. `'day'` (default) is a pure date picker; a finer granularity composes a time field.<br>**Default:** `'day'`                                                                               |
+| `hourCycle`           | `input<12 \| 24 \| null>`                        | 12/24-hour cycle for the value display; a projected time field takes `resolvedHourCycle()`.<br>**Default:** `null` → the scope's `hourCycle` (`provideForDatePickerDefaults`), then the locale                 |
+| `resolvedHourCycle`   | `Signal<12 \| 24 \| null>`                       | The effective cycle: `hourCycle`, then the scope's, or `null` for the locale. Bind it to a projected time field's `[hourCycle]`.<br>**Default:** —                                                             |
+| `modal`               | `input<boolean>`                                 | Trap focus + inert background + scroll lock (centered dialog) instead of an anchored popover.<br>**Default:** `false`                                                                                          |
+| `dismissible`         | `input<boolean>`                                 | Escape / outside-pointer dismiss the surface.<br>**Default:** `true`                                                                                                                                           |
+| `returnFocus`         | `input<boolean>`                                 | Return focus to the trigger on close.<br>**Default:** `true`                                                                                                                                                   |
+| `formatOptions`       | `input<Intl.DateTimeFormatOptions>`              | Options for the text rendered by `[forDatePickerValue]`.<br>**Default:** `{ year: 'numeric', month: 'long', day: 'numeric' }`                                                                                  |
+| `locale`              | `input<string \| null>`                          | BCP 47 locale for the text rendered by `[forDatePickerValue]`. Not forwarded to the projected calendar, so bind its `[locale]` too.<br>**Default:** `null` → the adapter's `locale()`, then the runtime locale |
+| `placeholder`         | `input<string>`                                  | Fallback text for `[forDatePickerValue]` when empty.<br>**Default:** `''`                                                                                                                                      |
+| `side` / `align`      | `input`                                          | Anchored placement (popover mode only). Defaults from `provideForDatePickerDefaults` / `provideForDateRangePickerDefaults`.<br>**Default:** `'bottom'` / `'start'`                                             |
+| `sideOffset`          | `input<number>`                                  | Gap (px) between the anchor and the content along the main axis. Defaults from `provideForDatePickerDefaults` / `provideForDateRangePickerDefaults`.<br>**Default:** `8`                                       |
+| `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. Defaults from `provideForDatePickerDefaults` / `provideForDateRangePickerDefaults`.<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`                          |
+| `dir`                 | `input<'ltr' \| 'rtl' \| null>`                  | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir`                                                                                                          |
+
+Plus the shared `FormUiControl` inputs from the base (`disabled`, `readonly`, `required`, `invalid`, `pending`, `dirty`, `name`, `errors`, and the `touched` model). The positioning inputs (`side` through `clipUntilPositioned`) apply in popover mode only; `modal` centres the surface instead of anchoring it.
 
 > **`locale` only styles the trigger display.** It drives the text rendered by `[forDatePickerValue]` (both here and on `ForDateRangePicker`); it is **not** forwarded to the projected `ForCalendar`. Bind the calendar's own `[locale]` to localize its heading / weekday / cell labels, exactly as you forward `[min]` / `[max]`.
 
 > **Why `minDate` / `maxDate`, not `min` / `max`?** `ForDatePicker` is a `FormValueControl`, and `FormUiControl` reserves `min` / `max` for numeric validators (`InputSignal<number | undefined>`). A date-typed `min` / `max` would break that contract, so the date bounds use the `*Date` suffix. (`ForCalendar` is not a form control, so it keeps `min` / `max`.)
 
+### Native submission
+
+When `name` is set, a hidden `<input name="…">` is mounted right after the `[forDatePicker]` element and mirrors the committed value as an ISO date (`YYYY-MM-DD`), or as an ISO date-time (`YYYY-MM-DDTHH:mm`, plus `:ss` at `granularity="second"`) at a granularity finer than `'day'`. It is removed while the value is `null` and disabled with the picker. The trigger itself carries no `name` attribute.
+
+A native reset of the owning `<form>` returns `value` to what it held when the picker first rendered. In the [field anatomy](#field-anatomy) it also drops a partly typed entry in the projected field.
+
 ### Data attributes
 
 | Piece                    | Attribute          | Values             |
@@ -233,9 +244,17 @@ A native reset of the owning `<form>` returns `value` to what it held when the p
 | `[forDatePicker]`        | `data-state`       | `open` \| `closed` |
 | `[forDatePicker]`        | `data-disabled`    | present \| absent  |
 | `[forDatePicker]`        | `data-readonly`    | present \| absent  |
+| `[forDatePicker]`        | `data-touched`     | present \| absent  |
+| `[forDatePicker]`        | `data-dirty`       | present \| absent  |
+| `[forDatePicker]`        | `data-pending`     | present \| absent  |
+| `[forDatePicker]`        | `data-invalid`     | present \| absent  |
 | `[forDateRangePicker]`   | `data-state`       | `open` \| `closed` |
 | `[forDateRangePicker]`   | `data-disabled`    | present \| absent  |
 | `[forDateRangePicker]`   | `data-readonly`    | present \| absent  |
+| `[forDateRangePicker]`   | `data-touched`     | present \| absent  |
+| `[forDateRangePicker]`   | `data-dirty`       | present \| absent  |
+| `[forDateRangePicker]`   | `data-pending`     | present \| absent  |
+| `[forDateRangePicker]`   | `data-invalid`     | present \| absent  |
 | `[forDatePickerTrigger]` | `data-state`       | `open` \| `closed` |
 | `[forDatePickerTrigger]` | `data-disabled`    | present \| absent  |
 | `[forDatePickerTrigger]` | `data-readonly`    | present \| absent  |
@@ -440,7 +459,7 @@ readonly booking = form(this.model, (p) => required(p.stay));
 - **Native submission.** When `name` is set, two hidden inputs `<name>-start` / `<name>-end` mirror the committed endpoints as ISO `YYYY-MM-DD` for native `<form>` posts. A native reset of the owning `<form>` returns `value` to what it held when the picker first rendered.
 - **Bounds naming.** `minDate` / `maxDate` (not `min` / `max`) for the same reason as `ForDatePicker`, and additionally because `FormUiControl.min` / `max` are typed `NonNullable<TValue>` (the range object itself), which is meaningless as a bound.
 
-Defaults are configured with `provideForDateRangePickerDefaults` (`side` / `align` / `sideOffset` / `collisionPadding`), and both wrapper patterns work via the exported `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_OUTPUTS` tuples. See [Wrapping form primitives](../../../docs/wrapping-form-primitives.md).
+Its positioning inputs are the ones the [`ForDatePicker` table](#fordatepicker) lists, with the same defaults. Defaults are configured with `provideForDateRangePickerDefaults` (`side` / `align` / `sideOffset` / `collisionPadding`), and both wrapper patterns work via the exported `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_OUTPUTS` tuples. See [Wrapping form primitives](../../../docs/wrapping-form-primitives.md).
 
 ## Keyboard
 
@@ -451,7 +470,7 @@ Defaults are configured with `provideForDateRangePickerDefaults` (`side` / `alig
 | **Escape**                                         | Dismiss the surface and return focus to the trigger (when `dismissible`).                                                                                        |
 | **Tab / Shift+Tab** past either end of the surface | Non-modal: Tab moves on to the element after the trigger and Shift+Tab lands on the trigger, closing the surface when `dismissible`. Modal: focus stays trapped. |
 
-Inside the surface, the projected `ForCalendar` owns the full grid keyboard map (arrows / `Home` / `End` / `PageUp` / `PageDown` / `Enter` / `Space`). On open, focus lands on the calendar's focused cell (`value ?? today`, with today clamped into the calendar's `[min, max]`) in non-modal mode, or the first focusable element in modal mode.
+Inside the surface, the projected `ForCalendar` owns the full grid keyboard map (arrows / `Home` / `End` / `PageUp` / `PageDown` / `Enter` / `Space`). On open, focus lands on the calendar's focused cell (`value ?? today`, with today clamped into the calendar's `[min, max]`) in both modes. When no cell can take focus, the surface itself is focused.
 
 ## Accessibility
 

package/dialog/README.md

@@ -157,7 +157,7 @@ Open a component imperatively and await its result. The manager mounts it under
 | Property             | Type                                                                | Description                                                                                                                                                                                                                                                       |
 | -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dismissible`        | —                                                                   | When `false`, Escape, backdrop, outside-pointer, and outside-focus do not request close. The close button still does.<br>**Default:** `true`                                                                                                                      |
-| `modal`              | —                                                                   | When `false`, no `aria-modal`, no scroll lock, no focus trap, no inert siblings, and no return focus on close.<br>**Default:** `true`                                                                                                                             |
+| `modal`              | —                                                                   | When `false`, no `aria-modal`, no scroll lock, no focus trap, no inert siblings, and no return focus on close. Read once at mount: a change while the dialog is open takes effect on the next open.<br>**Default:** `true`                                        |
 | `alert`              | —                                                                   | Switches role to `alertdialog`.<br>**Default:** `false`                                                                                                                                                                                                           |
 | `returnFocus`        | —                                                                   | Modal mode only: focus returns to the previously focused element on close. A non-modal dialog never moves focus on close.<br>**Default:** `true`                                                                                                                  |
 | `initialFocus`       | —                                                                   | `'first'` (first focusable inside) or `'container'` (the dialog host).<br>**Default:** `'first'`                                                                                                                                                                  |

package/drawer/README.md

@@ -362,7 +362,7 @@ Press the button: the manager opens the confirmation as a bottom drawer, and the
 | Property                    | Type                                                                | Description                                                                                                                                                                                                     |
 | --------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `side`                      | `'top' \| 'right' \| 'bottom' \| 'left'`                            | Anchored edge. Drives swipe direction and `data-side`.<br>**Default:** `'bottom'`                                                                                                                               |
-| `modal`                     | `boolean`                                                           | `aria-modal`, scroll lock, focus trap, inert siblings, return focus on close.<br>**Default:** `true`                                                                                                            |
+| `modal`                     | `boolean`                                                           | `aria-modal`, scroll lock, focus trap, inert siblings, return focus on close. Read once at mount: a change while the drawer is open takes effect on the next open.<br>**Default:** `true`                       |
 | `dismissible`               | `boolean`                                                           | Whether Escape / backdrop / outside / swipe close. When `false`, no swipe dismisses; `snapPoints` still drag between snaps.<br>**Default:** `true`                                                              |
 | `alert`                     | `boolean`                                                           | `role="alertdialog"`.<br>**Default:** `false`                                                                                                                                                                   |
 | `returnFocus`               | `boolean`                                                           | Modal mode only: restore focus on close. A non-modal drawer never moves focus on close.<br>**Default:** `true`                                                                                                  |

package/dropdown-menu/README.md

@@ -98,8 +98,13 @@ A settings-style dropdown built from the full menu vocabulary: `forMenuGroup` wi
 | `sideOffset`                | `input<number>`                                           | Gap (px) between the trigger and the content along the main axis.<br>**Default:** `4`                                                                                                                                                                                                                                                                  |
 | `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 `provideForDropdownMenuDefaults` for the surrounding scope, so 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 `provideForDropdownMenuDefaults` 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 at the ends.<br>**Default:** `true`                                                                                                                                                                                                                                                                                     |
-| `dir`                       | `input<string>`                                           | Writing direction. In RTL, ArrowLeft opens submenus and ArrowRight closes them. The swap is automatic. 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, ArrowLeft opens submenus and ArrowRight closes them. The swap is automatic. Inherited by every nested `[forMenuSub]` underneath unless overridden.<br>**Default:** `null`                                                                                 |
 | `disabled`                  | `input<boolean>`                                          | When `true`, trigger interactions are ignored and every item of the menu and its submenus is disabled. An open menu stays open, and keyboard navigation, Tab and Escape keep working.<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 to the trigger on close.<br>**Default:** `true`                                                                                                                                                                                                                                                                             |