forty-cdk 0.33.0 → 0.35.0

package/README.md

@@ -20,14 +20,15 @@ npm install forty-cdk
 
 Required:
 
-- `@angular/common` `^22.0.1`
-- `@angular/core` `^22.0.1`
+- `@angular/common` `^22.1.0`
+- `@angular/core` `^22.1.0`
+- `@angular/platform-browser` `^22.1.0`, already installed by every Angular browser or server app
 
 Optional — install only if you use the matching entry point / primitives:
 
 | Peer                               | Needed by                                                                                                                                                                                                                                                                                                                                                                  |
 | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `@angular/forms` `^22.0.1`         | 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. |
+| `@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.                                                                   |
 
 ### Regular dependencies

package/calendar/README.md

@@ -446,7 +446,7 @@ The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`
     <h2 forCalendarHeading #h="forCalendarHeading" class="sr-only">{{ h.label() }}</h2>
   </header>
 
-  @switch (cal.view()) { @case ('day') {
+  @let view = cal.view(); @switch (view) { @case ('day') {
   <table forCalendarGrid #grid="forCalendarGrid">
     <thead forCalendarGridHeader>
       <tr>
@@ -489,7 +489,7 @@ The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`
       }
     </tbody>
   </table>
-  } }
+  } @default never; }
 </div>
 ```
 

package/carousel/README.md

@@ -57,7 +57,7 @@ Headless and styleless: it ships slide tracking, keyboard navigation, focus mana
 
 ## Examples
 
-Page through the slides with the buttons, the arrow keys or a drag. The root carries `data-orientation`, and `data-dragging` is on while a pointer holds the track.
+Page through the slides with the buttons or with the arrow keys on the dots. The root carries `data-orientation`, and only the current dot is in the tab order however the slide was reached.
 
 ```ts
 import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
@@ -144,7 +144,7 @@ interface Slide {
           <button
             forCarouselIndicator
             class="car-dot"
-            [attr.aria-label]="'Go to slide ' + (i + 1)"
+            [ariaLabel]="'Go to slide ' + (i + 1)"
           ></button>
         }
       </div>
@@ -186,7 +186,7 @@ Set `slidesPerView` above `1` to show several slides at once. Each slide is `fle
 
 ### Autoplay with pause control
 
-With `autoplay` set, the slides advance every three seconds, unless your system asks for reduced motion, in which case they wait for the rotation control. Hover the carousel or move focus into it and rotation pauses until you leave; stop it with the control and it stays stopped through hover and focus until you start it again. [Autoplay](#autoplay) has the full pause rules and why the control must be the first focusable child.
+With `autoplay` set, the slides advance every three seconds, unless your system asks for reduced motion, in which case they wait for the rotation control. Hover the carousel or move focus into it and rotation pauses until you leave; stop it with the control and it stays stopped through hover and focus until you start it again, and a Start from the control rotates straight away, with focus and the pointer still on it. [Autoplay](#autoplay) has the full pause rules and why the control must be the first focusable child.
 
 ### Pointer drag & touch swipe
 
@@ -238,8 +238,12 @@ focusable child** of the carousel to enable automatic slide rotation.
 
 **Behaviour:**
 
-- Rotation pauses on hover, on keyboard focus anywhere inside the carousel, and
-  while the browser tab is backgrounded. It resumes when none of those hold.
+- Rotation that started on its own (`autoplay`) pauses on hover, on keyboard
+  focus anywhere inside the carousel, and while the browser tab is backgrounded.
+  It resumes when none of those hold.
+- An explicit user Start (clicking the rotation control or calling `play()`)
+  rotates even while focus or the pointer is inside the carousel, which is where
+  the user is when they press it. Only a backgrounded tab still pauses it.
 - An explicit user stop (clicking the rotation control or calling `pause()`) is
   **sticky**: hover-in/out and focus-in/out will not restart it. Only an explicit
   Start does.
@@ -461,7 +465,8 @@ Reflected on the `[forCarouselViewport]` host this directive is applied to:
 ## Keyboard
 
 Keyboard navigation lives on the indicator group. Only the current
-indicator is in the tab order. Arrow keys move focus and activate the target slide
+indicator is in the tab order, including after prev / next, autoplay or a drag
+moved the slide. Arrow keys move focus and activate the target slide
 automatically.
 
 | Key                        | Action                                                                |

package/checkbox/README.md

@@ -63,6 +63,12 @@ A parent checkbox reflects `indeterminate` when only some children are selected.
 import { Component, computed, signal } from '@angular/core';
 import { ForCheckbox } from 'forty-cdk/checkbox';
 
+interface Topping {
+  readonly id: number;
+  readonly label: string;
+  readonly selected: boolean;
+}
+
 @Component({
   selector: 'demo-select-all',
   imports: [ForCheckbox],
@@ -80,7 +86,12 @@ import { ForCheckbox } from 'forty-cdk/checkbox';
       Select all toppings
     </button>
     @for (item of items(); track item.id) {
-      <button forCheckbox class="cb-row" [(checked)]="item.selected">
+      <button
+        forCheckbox
+        class="cb-row"
+        [checked]="item.selected"
+        (checkedChange)="setItem(item.id, $event)"
+      >
         <span class="cb">
           <span class="cb-check" aria-hidden="true"></span>
         </span>
@@ -90,7 +101,7 @@ import { ForCheckbox } from 'forty-cdk/checkbox';
   `,
 })
 export class DemoSelectAll {
-  readonly items = signal([
+  readonly items = signal<readonly Topping[]>([
     { id: 1, label: 'Mozzarella', selected: false },
     { id: 2, label: 'Mushrooms', selected: true },
     { id: 3, label: 'Pepperoni', selected: false },
@@ -106,6 +117,10 @@ export class DemoSelectAll {
     const next = !this.allChecked();
     this.items.update((list) => list.map((i) => ({ ...i, selected: next })));
   }
+
+  setItem(id: number, selected: boolean): void {
+    this.items.update((list) => list.map((i) => (i.id === id ? { ...i, selected } : i)));
+  }
 }
 ```
 
@@ -149,7 +164,7 @@ export class DemoCheckout {
 | `checked`                                                    | `model<boolean>`                                          | Two-way bindable on/off. Required by `FormCheckboxControl`.<br>**Default:** —                                                                                                                                        |
 | `indeterminate`                                              | `model<boolean>`                                          | Two-way bindable. When true, `aria-checked="mixed"` regardless of `checked`. Click clears it. UI-only and not part of the form value.<br>**Default:** —                                                              |
 | `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).<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:** —                                                                                                                                                                             |
 

package/combobox/README.md

@@ -220,7 +220,7 @@ Input tables are not yet tabulated for this primitive. See the feature sections
 | `[forComboboxChip]`      | `data-disabled`    | present / absent                                                    |
 | `[forComboboxSeparator]` | `data-orientation` | `horizontal` \| `vertical`                                          |
 
-Focus stays on the `<input>` the whole time the listbox is open, so options never get `:focus`. `data-highlighted` is the canonical hook for styling the keyboard-active option. A mouse press anywhere on the popup that lands on no focusable element (padding, a group label, an empty or status row) does not move focus either, so typing and the arrow keys keep working after it; the trade-off is that popup text cannot be selected with the mouse, as in a native combobox. A press on a focusable element inside the popup, such as a `[forComboboxAction]` or your own `<button>`, still focuses it.
+Focus stays on the `<input>` the whole time the listbox is open, so options never get `:focus`. `data-highlighted` is the canonical hook for styling the keyboard-active option. A mouse press anywhere on the popup that lands on no focusable element (padding, a group label, an empty or status row) does not move focus either, so typing and the arrow keys keep working after it; the trade-off is that popup text cannot be selected with the mouse, as in a native combobox. A press on a `[forComboboxAction]` still focuses it in every browser. A press on your own `<button>` inside the popup is left to the browser, and macOS Safari and Firefox do not focus a `<button>` on a press.
 
 ## Mount/visibility convention
 
@@ -280,7 +280,7 @@ The default (editable) anatomy is a text field that filters in place. A **picker
 Add two parts:
 
 - **`[forComboboxTrigger]`**: a real `<button>` outside the `@if (open())`. It opens the panel, becomes the default positioning anchor, and is where focus returns on close.
-- **`[forComboboxList]`**: the `role="listbox"` element nested inside `[forComboboxContent]`, next to the input. It owns the options and the labelled role; `[forComboboxContent]` becomes a neutral popup surface.
+- **`[forComboboxList]`**: the `role="listbox"` element nested inside `[forComboboxContent]`, next to the input. It owns the options and the labelled role; `[forComboboxContent]` becomes the `role="dialog"` the trigger opens, named by the trigger.
 
 ```html
 <div forCombobox #combobox="forCombobox" [(value)]="value" [(query)]="query" [(open)]="open">
@@ -292,20 +292,20 @@ Add two parts:
       @for (item of filtered(); track item.id) {
       <div forComboboxOption [value]="item.id" [label]="item.label">{{ item.label }}</div>
       }
-      <div forComboboxEmpty>No matches.</div>
     </div>
+    <div forComboboxEmpty>No matches.</div>
   </div>
   }
 </div>
 ```
 
-Why the list part is required, not optional: a `role="listbox"` may only own `option` / `group` children (`aria-required-owned-elements`). Nesting the input inside a listbox would be invalid, so the listbox role moves to `[forComboboxList]` and the input sits beside it under the neutral popup surface. Put non-option chrome (`[forComboboxInput]`, `[forComboboxEmpty]`, `[forComboboxStatus]`) inside `[forComboboxContent]` but **outside** `[forComboboxList]`.
+Why the list part is required, not optional: a `role="listbox"` may only own `option` / `group` children (`aria-required-owned-elements`). Nesting the input inside a listbox would be invalid, so the listbox role moves to `[forComboboxList]` and the input sits beside it inside the dialog surface. Put non-option chrome (`[forComboboxInput]`, `[forComboboxEmpty]`, `[forComboboxStatus]`) inside `[forComboboxContent]` but **outside** `[forComboboxList]`.
 
 **Focus hand-off.** Registering a trigger opts the combobox into the standard trigger-anchored focus model: on open, focus moves into the input (the search field inside the panel); on close, focus returns to the trigger. Both moves are vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)` on `[forCombobox]`, and the return is gated by `[returnFocus]` (default `true`). Escape stays owned by the input. See [Focus & the `(autoFocusOnOpen)` / `(autoFocusOnClose)` hooks](#focus--the-autofocusonopen--autofocusonclose-hooks).
 
 **A trigger that registers late still owns the hand-off.** The trigger does not have to be declared before `[forComboboxContent]`, and does not have to exist when the panel first mounts. You can project it through `<ng-content>` from a wrapper, put it under a `@defer`, or gate it on an `@if` over loaded data. One caveat: focus moving _into_ the panel is a mount-time event, so a trigger that arrives while the panel is **already open** does not retroactively pull focus out of wherever you left it. From that moment on it does own the return focus, `(autoFocusOnClose)` and the Escape fallback, and the next open moves focus into the input as usual.
 
-**Trigger keyboard.** Click / Enter / Space toggle (open moves focus into the input). ArrowDown opens with the first enabled option highlighted; ArrowUp opens with the last.
+**Trigger keyboard.** Click / Enter / Space toggle (open moves focus into the input). ArrowDown and ArrowUp open with the committed selection highlighted; with nothing selected, ArrowDown lands on the first enabled option and ArrowUp on the last.
 
 **Anchor preference.** With a trigger present the panel anchors to it by default. An explicit `[forComboboxAnchor]` still wins (explicit anchor → trigger → input), so you can wrap a decorated trigger box and anchor against it.
 
@@ -536,7 +536,7 @@ When the input is empty (no query) and the user presses Backspace, focus jumps t
 | Highlight the selection on open         | `first` | `openHighlight="selected"`                                       |
 | Restore label on close (single only)    | `false` | `[restoreQueryOnClose]="true"`                                   |
 
-`openHighlight` decides where the editable anatomy's highlight lands when the listbox opens from focus, click, ArrowDown / ArrowUp or `openOverlay()` without an argument. With `'selected'`, a single-select combobox showing "Spain" reopens on "Spain" rather than on the first option; with nothing selected, ArrowDown still lands on the first option and ArrowUp on the last. Opening from a typed query always highlights the first match, because the list is a filter result there, and the picker anatomy always opens on the selection. Both inputs take their default from the scope: `provideForComboboxDefaults({ openHighlight: 'selected', restoreQueryOnClose: true })`.
+`openHighlight` decides where the editable anatomy's highlight lands when the listbox opens from focus, click, ArrowDown / ArrowUp or `openOverlay()` without an argument. With `'selected'`, a single-select combobox showing "Spain" reopens on "Spain" rather than on the first option; with nothing selected, ArrowDown still lands on the first option and ArrowUp on the last. Opening from a typed query always highlights the first match, because the list is a filter result there, and the picker anatomy always opens on the selection. With [virtualization](#virtualization) the selection is not honoured: an open that would land on it highlights the first rendered enabled option instead. Both inputs take their default from the scope: `provideForComboboxDefaults({ openHighlight: 'selected', restoreQueryOnClose: true })`.
 
 ## Autocomplete modes
 
@@ -663,6 +663,8 @@ How navigation flows when virtualizing:
 3. Your virtualizer scrolls; the directive's `@for` mounts the option for index 999.
 4. As soon as that option registers (at the matching `posInSet`), the directive seeds `aria-activedescendant` to its id.
 
+Opening seeds the highlight from the rendered window only: the first rendered enabled option, or the last for an ArrowUp with nothing selected. An open that would land on the committed selection (`openHighlight="selected"`, the picker anatomy, `[forComboboxToggle]`) lands on the first rendered enabled option too, because the selection may sit outside the window and the directive cannot know its index.
+
 Inline autocomplete matches against the most recently rendered window overlaid with the position snapshot, so completion against off-screen labels still works. `selected().label` reads a separate, selection-keyed cache instead. That cache is bounded by the selection, so the label of a selected option survives close / re-open and any number of query rebuilds, but it is **not** resolved from the position snapshot: a value that enters the selection while its option is outside the rendered window (a `[(value)]` write restoring a saved selection, say) falls back to `[itemToStringLabel]` until that option renders once. Supply `[itemToStringLabel]` whenever the selection can be seeded from outside the list.
 
 ```html
@@ -782,7 +784,7 @@ Static and `@for`-rendered options share the same registry, navigation order (DO
 </div>
 ```
 
-For a legacy `<form action="…">` flow, set `[name]`, and the directive mirrors `[(value)]` into N `<input type="hidden">` siblings (one per array entry; zero when empty). String values land verbatim in the hidden input; object values default to `JSON.stringify` (override via `[itemToFormValue]`, see below).
+For a legacy `<form action="…">` flow, set `[name]`, and the directive mirrors `[(value)]` into N `<input type="hidden">` siblings (one per array entry; zero when empty). String values land verbatim in the hidden input; object values default to `JSON.stringify` (override via `[itemToFormValue]`, see below). A native reset of the owning `<form>` returns `value` and `query` to what they held when the combobox first rendered, and the input shows that query again.
 
 A single-select field is modeled as the same `readonly T[]`, kept at length ≤ 1, and bound with `[formField]` directly, so single mode needs no adapter. A `FieldTree<T | null>` cannot bind here; map to that shape at the edge that needs it. See [the selection value-type contract](../../../docs/selection-value-type-contract.md).
 
@@ -815,9 +817,9 @@ Hovering an option also makes it the activedescendant, so mouse and keyboard int
 Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
 
 - Apply the input directive to an actual `<input>`: the browser's caret and selection semantics are what make inline autocomplete work, and screen readers expect a real text field for `role="combobox"`.
-- `role="listbox"` lives on `[forComboboxContent]` in the editable anatomy and on `[forComboboxList]` in the picker anatomy; the input's `aria-controls` targets whichever carries it. In the picker anatomy the popup surface (`[forComboboxContent]`) is role-less so it can hold the input next to the list without an `aria-required-owned-elements` violation.
+- `role="listbox"` lives on `[forComboboxContent]` in the editable anatomy and on `[forComboboxList]` in the picker anatomy; the input's `aria-controls` targets whichever carries it. In the picker anatomy the popup surface (`[forComboboxContent]`) is a `role="dialog"` named by the trigger (`aria-labelledby`; a static `aria-label` or `aria-labelledby` on it wins), so it can hold the input next to the list without an `aria-required-owned-elements` violation. The "editable + list" shape, with no trigger, leaves it role-less.
 - `aria-multiselectable="true"` (multi mode) and the labelled role (`aria-label` / `aria-labelledby`, pointing at the input) sit on whichever element carries `role="listbox"`: content in the editable anatomy, the list in the picker anatomy.
-- `[forComboboxTrigger]` (picker anatomy) is a real `<button>` reflecting `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` (the popup surface, while open), and native `disabled` from the combobox's effective disabled. It is exempt from the popup's outside-pointer dismissal layer, like the input.
+- `[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.
 - 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.

package/date-field/README.md

@@ -163,6 +163,15 @@ With a time-capable adapter, a `granularity` coarser than `'day'` appends time s
 
 Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled`, `readonly`, `required`, `invalid`, `name`, `errors`, `touched` (bound automatically by `[formField]`).
 
+| Method    | Description                                                                                                                                                    |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `clear()` | Sets `value` to `null` and empties every segment, a partly typed entry included. Call it from a Clear button.                                                  |
+| `reset()` | Drops a partly typed entry and shows the current `value`. Signal Forms calls it on `form().reset()`, so a form reset clears the segments with no extra wiring. |
+
+A partly typed date already reports `value()` as `null`, so writing `null` through `[(value)]` changes nothing and leaves the typed digits on screen. Clear the field with `clear()` instead, which you can reach through the `#field="forDateField"` template reference.
+
+A native reset of the owning `<form>` returns `value` to what it held when the field first rendered and runs `reset()`, so a partly typed entry goes too and the hidden input submits that value again.
+
 > **Why `minDate` / `maxDate`, not `min` / `max`?** `FormUiControl.min` / `max` are reserved members typed `number | undefined` for numeric validators bound by `[formField]`. A date-typed `min` / `max` would break the `FormValueControl` contract, so the date bounds use distinct names.
 
 ### Data attributes
@@ -200,7 +209,7 @@ Set `granularity` to `'hour'`, `'minute'`, or `'second'` (`granularity > 'day'`)
 </div>
 ```
 
-On the AM/PM segment, `a` / `p` set the period and ArrowUp / ArrowDown toggle it; the period is derived from the entered hour, so clearing it is a no-op (clear or step the hour instead). The value stays `null` until every visible segment (date **and** time) is filled.
+On the AM/PM segment, `a` / `p` set the period and ArrowUp / ArrowDown toggle it (on an empty segment ArrowUp sets PM and ArrowDown sets AM). The period is never derived from the entered hour: it stays empty until you set it, and Delete / Backspace leave it as it is. In a locale whose 12-hour clock counts 0–11 (`ja-JP`), the hour segment does too. The value stays `null` until every visible segment (date **and** time) is filled.
 
 ## Scoped defaults
 
@@ -284,6 +293,8 @@ readonly booking = form(this.model);
 
 The endpoint groups each accept an `ariaLabel` input for their own group label, falling back to the scope defaults (`'Start date'` / `'End date'`). Plus the shared `FormUiControl` members bound automatically by `[formField]`.
 
+`ForDateRangeField` exposes the same `clear()` and `reset()` as `ForDateField`. They drop a half-entered range and an out-of-order one, its `data-range-error` included, which writing `null` through `[(value)]` cannot do: such a range already reports `value()` as `null`. Without them, finishing the end endpoint later would commit a range built from a start the user thought was gone. A native reset of the owning `<form>` returns the range to what it held when the field first rendered and runs `reset()`.
+
 > **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.

package/date-picker/README.md

@@ -220,6 +220,8 @@ Open the picker and click a first day: the trigger keeps its placeholder, becaus
 
 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.
+
 > **`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`.)
@@ -294,6 +296,8 @@ Set `granularity` to `'hour'`, `'minute'`, or `'second'` to turn the picker into
 
 Bind the calendar **and** the time field **one-way** to `picker.value()` (not `[(value)]`). The picker is the single source of truth: when one-way bound to a timed value the calendar preserves the time-of-day on its own selection, and the picker re-grafts the previously entered time as a defensive fallback for the case where the calendar value was null or midnight (reading its own value, which the one-way children never clobber); a time-field edit emits a full date-time the picker mirrors in. A date-time picker never closes on a calendar selection, so the user can go on to set the time.
 
+Like the calendar, the projected time field or time picker takes the picker's `readonly` and `disabled` without a binding, so a read-only or disabled picker's time source accepts no edit and shows only the committed time. A typed time the picker clamps into `[minDate, maxDate]` behaves as in a standalone time field: while focus stays in the field its segments keep what was entered, and they show the clamped value once focus leaves.
+
 The content is a field boundary. Inside a [`[forField]`](../field/README.md#how-the-control-connects) the time field does not register with the field, which keeps reflecting the picker (its label target, `invalid` state and errors) while the panel is open.
 
 ```html
@@ -379,6 +383,7 @@ With the field adopted:
 - **The field is the control.** A surrounding `[forField]` names and describes the field's `role="group"`, `aria-invalid` lands there, a label press focuses its first segment, and the picker's `focus()` goes there too.
 - **The trigger is a plain button.** It drops `role="combobox"` and the form-control `aria-*` state, and keeps `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. Give it a name of its own.
 - **A pick closes the surface at any granularity.** The time is typed in the field rather than in the surface, so a picked day keeps the field's time and the surface closes (unless `closeOnSelect` is off).
+- **A press on a segment closes the surface.** Only the trigger and the field's labels are exempt from outside dismissal, so pressing a segment to start typing closes the calendar and leaves focus on that segment.
 
 The anatomy is explicit, so a date field placed inside the surface of a trigger-anatomy picker changes nothing. With `anatomy="field"` and no projected `[forDateField]`, opening the calendar or calling `focus()` throws `FORCDK-DATE-PICKER-007` in dev mode.
 
@@ -432,7 +437,7 @@ readonly booking = form(this.model, (p) => required(p.stay));
 
 - **Form value.** The committed `DateRange<D> | null` is the `value` model. `null` is the empty state. Pair it with `required(p.stay)` so `invalid()` flips when the form demands a range and none is committed. `touched` fires on commit and on close, exactly like the single-date picker.
 - **Validity.** `start <= end` is guaranteed by construction and is never an error. Forward `minDate` / `maxDate` to the calendar's `[min]` / `[max]` so out-of-range days are disabled in the grid; a range picked in a calendar without them is clamped into `[minDate, maxDate]` on commit. Forward `minRangeLength` / `maxRangeLength` to the calendar's `[minRangeLength]` / `[maxRangeLength]` (a too-short / too-long range is rejected as a no-op by the calendar's two-click flow).
-- **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.
+- **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).
@@ -456,7 +461,7 @@ Implements the [WAI-ARIA Date Picker Dialog pattern](https://www.w3.org/WAI/ARIA
 - **`role="dialog"`** on the surface, named by `[ariaLabel]` (or `aria-labelledby` the trigger when no label is set). `aria-modal="true"` only in modal mode (truthy-only).
 - **Form-control ARIA** (`aria-readonly` / `aria-required` / `aria-invalid` / `aria-busy`) is reflected on the focusable trigger so assistive tech announces validity on the element that takes focus, alongside the `data-readonly` styling hook. The disabled state is the exception. It reflects through one channel only: the native `disabled` attribute (plus `data-disabled`), never `aria-disabled`.
 - **Inside a `[forField]` the labelled element is the trigger**, not the `[forDatePicker]` / `[forDateRangePicker]` wrapper: the field's `controlId` and its `aria-labelledby` / `aria-describedby` / `aria-errormessage` land on `[forDatePickerTrigger]`, so `[forLabel]`'s `for` points at the element that takes focus, clicking a non-`<label>` `[forLabel]` opens the surface, and Signal Forms' focus-on-error reaches the trigger. `role="combobox"` takes its name from the author, so this is the channel that names the control. The root's `[ariaLabel]` names the `role="dialog"` surface instead. In the [field anatomy](#field-anatomy) the same association lands on the date field's `role="group"` instead, and a label press focuses its first segment.
-- **Focus management**: focus enters the surface on open (the calendar's roving cell in non-modal mode) and returns to the trigger on close, both vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)`.
+- **Focus management**: focus enters the surface on open (the calendar's roving cell in non-modal mode) and returns to the trigger on close, both vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)`. The one exception in non-modal mode is an **outside-interaction close**, meaning a pointer-down or focus-out that lands outside the surface. After such a close, focus stays where the interaction moved it instead of snapping back to the trigger, so a click on the next form control keeps the user's typing there. Escape, a pick and programmatic closes still return focus.
 - **Dismissal**: Escape (`(escapeKeyDown)`) and outside-pointer (`(pointerDownOutside)` / `(interactOutside)`) close the surface, each vetoable.
 
 ## Styling
@@ -480,4 +485,4 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 
 ## Wrapping in a design system
 
-[Wrapping form primitives](../../../docs/wrapping-form-primitives.md) documents both supported wrapper patterns: `hostDirectives` with the exported `FOR_DATE_PICKER_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_PICKER_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing.
+[Wrapping form primitives](../../../docs/wrapping-form-primitives.md) documents both supported wrapper patterns: `hostDirectives` with the exported `FOR_DATE_PICKER_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_PICKER_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing. A subclass spreads [`provideForDatePicker(MyDatePicker)`](../../../docs/wrapping-form-primitives.md#date-and-time-roots-spread-their-provider-helper) or `provideForDateRangePicker(MyDateRangePicker)` as its `providers`, because the root also provides tokens its projected calendar, field and time control resolve that cannot be imported.

package/dialog/README.md

@@ -157,9 +157,9 @@ 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.<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`                                                                                                                             |
 | `alert`              | —                                                                   | Switches role to `alertdialog`.<br>**Default:** `false`                                                                                                                                                                                                           |
-| `returnFocus`        | —                                                                   | Focus returns to the previously focused element on close.<br>**Default:** `true`                                                                                                                                                                                  |
+| `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'`                                                                                                                                                                  |
 | `ariaLabel`          | —                                                                   | Manual `aria-label` if no `[forDialogTitle]` is rendered.<br>**Default:** `null`                                                                                                                                                                                  |
 | `dismiss`            | `OutputEmitterRef<ForDialogCloseReason>`                            | Output. Dialog wants to be unmounted. Reasons: `'escape'`, `'backdrop'`, `'pointerDownOutside'`, `'focusOutside'`, `'closeButton'`, `'programmatic'`. Spelled `dismiss` rather than `close` on purpose (see [Behavior notes](#behavior-notes)).<br>**Default:** — |
@@ -298,7 +298,22 @@ this.dialogs.open(ConfirmDialog, {
 }
 ```
 
-Set them once for a scope with `provideForDialogDefaults({ animateEnter, animateLeave })`; a per-`open()` value always wins over the scope default.
+A template `animate.leave` inside the opened component never runs, because Angular does not run leave animations across the outlet the manager mounts it through. The exit animation is configured with `animateLeave` for the host and `backdropAnimateLeave` for a `[forDialogBackdrop]`, whose enter stays an `animate.enter` on the element itself.
+
+Set them once with `provideForDialogDefaults({ animateEnter, animateLeave, backdropAnimateLeave })`; a per-`open()` value always wins over the default. `ForDialogManager` is provided in root and reads the defaults from the root injector, so a `provideForDialogDefaults` on a lazy route or in a component's `providers` reaches a programmatic dialog only when that scope's injector is passed as `injector`. The opened component is then parented on it too, so the scope's other providers reach it as well.
+
+<!-- snippet: fragment -->
+
+```ts
+class ScopedHost {
+  readonly #dialogs = inject(ForDialogManager);
+  readonly #injector = inject(Injector);
+
+  confirm(): void {
+    this.#dialogs.open(ConfirmDialog, { injector: this.#injector });
+  }
+}
+```
 
 | Symbol                  | Description                                                                                                                                                                                                                                                                                                                                                        |
 | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -309,26 +324,30 @@ Set them once for a scope with `provideForDialogDefaults({ animateEnter, animate
 
 ### `ForDialogOpenConfig`
 
-| Field                | Default   | Description                                                                                              |
-| -------------------- | --------- | -------------------------------------------------------------------------------------------------------- |
-| `data`               | —         | Payload available as `injectDialogData<T>()`.                                                            |
-| `dismissible`        | `true`    | Escape closes when `true`.                                                                               |
-| `modal`              | `true`    | Sets `aria-modal`, locks body scroll, traps focus.                                                       |
-| `alert`              | `false`   | Use `role="alertdialog"` instead of `"dialog"`.                                                          |
-| `returnFocus`        | `true`    | Focus returns to the previously focused element on close.                                                |
-| `initialFocus`       | `'first'` | `'first'` finds first focusable; `'container'` focuses the host.                                         |
-| `ariaLabel`          | —         | Manual accessible name when no title element is rendered.                                                |
-| `animateEnter`       | —         | CSS class applied on mount (via `animate.enter`) to play an enter animation.                             |
-| `animateLeave`       | —         | CSS class applied on close; the host stays mounted until its animation finishes, then tears down.        |
-| `class`              | —         | CSS class(es) applied to the overlay root (the `[forDialog]` host). Single or space-separated string.    |
-| `classList`          | —         | CSS class(es) applied to the overlay root, as an array or space-separated string. Merged with `class`.   |
-| `providers`          | `[]`      | Extra providers for the opened component's injector.                                                     |
-| `autoFocusOnOpen`    | —         | Callback. Receives a `VetoableEvent`; `event.preventDefault()` skips the imperative initial focus move.  |
-| `autoFocusOnClose`   | —         | Callback. Receives a `VetoableEvent`; `event.preventDefault()` skips the return-focus on close.          |
-| `escapeKeyDown`      | —         | Callback. `VetoableNativeEvent<KeyboardEvent>`; `preventDefault()` suppresses the Escape close.          |
-| `pointerDownOutside` | —         | Callback. `VetoableNativeEvent<PointerEvent>`; `preventDefault()` suppresses the outside-pointer close.  |
-| `focusOutside`       | —         | Callback. `VetoableNativeEvent<FocusEvent>`; `preventDefault()` suppresses the outside-focus close.      |
-| `interactOutside`    | —         | Callback. Composite `VetoableNativeEvent<PointerEvent \| FocusEvent>`; shares the veto of the two above. |
+| Field                  | Default   | Description                                                                                                       |
+| ---------------------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| `data`                 | —         | Payload available as `injectDialogData<T>()`.                                                                     |
+| `dismissible`          | `true`    | When `false`, Escape, backdrop, outside-pointer and outside-focus do not close the dialog.                        |
+| `modal`                | `true`    | Sets `aria-modal`, locks body scroll, traps focus, inerts siblings and returns focus on close.                    |
+| `alert`                | `false`   | Use `role="alertdialog"` instead of `"dialog"`.                                                                   |
+| `returnFocus`          | `true`    | Modal mode only: focus returns to the previously focused element on close.                                        |
+| `returnFocusTarget`    | —         | Element focus returns to. Omitted, the trigger that opened the modal chain; `null`, the element focused at mount. |
+| `initialFocus`         | `'first'` | `'first'` finds first focusable; `'container'` focuses the host.                                                  |
+| `ariaLabel`            | —         | Manual accessible name when no title element is rendered.                                                         |
+| `container`            | —         | Portal target for the surface and its backdrop, `document.body` when omitted. Pair with `modal: false`.           |
+| `animateEnter`         | —         | CSS class applied on mount (via `animate.enter`) to play an enter animation.                                      |
+| `animateLeave`         | —         | CSS class applied on close; the host stays mounted until its animation finishes, then tears down.                 |
+| `backdropAnimateLeave` | —         | CSS class applied to the `[forDialogBackdrop]` on close; it stays mounted until its animation finishes.           |
+| `class`                | —         | CSS class(es) applied to the overlay root (the `[forDialog]` host). Single or space-separated string.             |
+| `classList`            | —         | CSS class(es) applied to the overlay root, as an array or space-separated string. Merged with `class`.            |
+| `providers`            | `[]`      | Extra providers for the opened component's injector.                                                              |
+| `injector`             | —         | Caller scope: scoped `provideForDialogDefaults` and providers are read from it instead of the root.               |
+| `autoFocusOnOpen`      | —         | Callback. Receives a `VetoableEvent`; `event.preventDefault()` skips the imperative initial focus move.           |
+| `autoFocusOnClose`     | —         | Callback. Receives a `VetoableEvent`; `event.preventDefault()` skips the return-focus on close.                   |
+| `escapeKeyDown`        | —         | Callback. `VetoableNativeEvent<KeyboardEvent>`; `preventDefault()` suppresses the Escape close.                   |
+| `pointerDownOutside`   | —         | Callback. `VetoableNativeEvent<PointerEvent>`; `preventDefault()` suppresses the outside-pointer close.           |
+| `focusOutside`         | —         | Callback. `VetoableNativeEvent<FocusEvent>`; `preventDefault()` suppresses the outside-focus close.               |
+| `interactOutside`      | —         | Callback. Composite `VetoableNativeEvent<PointerEvent \| FocusEvent>`; shares the veto of the two above.          |
 
 The four dismiss callbacks mirror the declarative `(escapeKeyDown)` / `(pointerDownOutside)` / `(focusOutside)` / `(interactOutside)` outputs exactly, with the same events and the same veto semantics. See [Per-channel dismissal](#per-channel-dismissal-escape-only-dialogs).
 
@@ -372,6 +391,8 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 }
 ```
 
+The backdrop is portaled immediately before its own dialog, so with no `z-index` on either the dialog paints above it. Set one only when other positioned content on the page has to sit beneath the pair.
+
 **Stacked dialogs.** Each surface and its backdrop publish their stacking position as `data-depth` and `--for-dialog-depth` (`0` for the first dialog, `1` above it, …), shared by declarative and managed dialogs. One rule then covers every level, with each backdrop one step below its own dialog and above every dialog underneath it:
 
 ```css
@@ -406,14 +427,14 @@ forty-cdk ships no styles: put your own class on each piece and key your CSS off
 
 - **The declarative and imperative surfaces spell this differently, on purpose.** The output is `(dismiss)`, because an output named `close` would collide with the native DOM event and break any wrapper re-exposing it through `hostDirectives`. Nothing else changes name: the imperative handle method is `ForDialogRef.close()`, the directive selector is `[forDialogClose]`, and the payload type is `ForDialogCloseReason`.
 - **Mount equals open**. The directive does not manage `[hidden]` or any visibility attribute. The consumer's `@if (open())` controls presence, and `animate.enter` / `animate.leave` handle the visual transition. That is why `[forDialog]`, `[forDialogBackdrop]`, and `[forDialogClose]` carry a static `data-state="open"`: because the host only exists inside `@if (open())`, the element is present iff the dialog is open, so the attribute can never be `closed`. Exit styling is the consumer's `animate.leave`, not a `[data-state="closed"]` selector. Only `[forDialogTrigger]`, which stays mounted, toggles `open` / `closed`.
-- **Portal**: the dialog box is moved to `document.body` on first render (or to `container` when set). The backdrop portals alongside the dialog (to the same `container`, `document.body` by default). CSS scoped to ancestors won't apply, so use global styles or classes.
+- **Portal**: the dialog box is moved to `document.body` on first render (or to `container` when set). The backdrop portals to the same `container`, `document.body` by default, immediately before its dialog. CSS scoped to ancestors won't apply, so use global styles or classes.
 - **Body scroll lock** is refcounted: stacking dialogs (or a dialog + a future overlay using the same lock) only restore on the last unlock.
 - **Focus trap** scopes Tab inside the dialog box while `modal`. It does NOT itself mark the rest of the page `inert`. That is the inert-siblings utility's job (next bullet).
 - **Inert siblings**. When `modal`, every direct child of `document.body` other than the dialog box (and its backdrop) gets `inert` and `aria-hidden="true"` while open, and is restored on close. This is what `aria-modal="true"` alone is missing, since Safari + VoiceOver and several other AT pairings otherwise still announce siblings of an aria-modal node. Stacking is order-safe: when a second modal opens on top, the first becomes inert; closing the top dialog re-activates the underlying one.
 - **Vetoable dismissals**. Each of `(escapeKeyDown)`, `(pointerDownOutside)`, `(focusOutside)`, `(interactOutside)` fires before the corresponding `(dismiss)`. Call `preventDefault()` on the event to keep the dialog open (e.g. to ask "are you sure?" first).
 - **Focus callbacks are inputs, not outputs.** The `autoFocusOnOpen` / `autoFocusOnClose` shape mirrors `ForDialogManager`'s `config.autoFocusOn*` callbacks and guarantees the `autoFocusOnClose` callback fires reliably on every close path, including a direct `open.set(false)` that bypasses the `(dismiss)` output. The trigger-anchored overlays (Popover, DropdownMenu, Select, …) expose the same pair as **outputs** instead, because every close transition there runs through their own `[(open)]` model, so no path can bypass the emitter.
 - **The close button** (`[forDialogClose]`) always requests close, regardless of `dismissible`. Reason emitted is `'closeButton'`.
-- **Both flows share the same engine**: the focus trap, scroll lock, dismissible layer, and portal in `ForDialogManager.open()` use the same `_internal/` utilities as the directive. Behavior is identical.
+- **Both flows share the same engine**: `ForDialogManager.open()` renders the same `[forDialog]` directive, so the focus trap, scroll lock, dismissible layer and portal are the directive's own. Behavior is identical.
 
 ### Per-channel dismissal (Escape-only dialogs)
 

package/drag-drop/README.md

@@ -199,8 +199,10 @@ name and leave "sortable" to `aria-sort`.
 
 Applying the move in `(dragDrop)` destroys or re-inserts the lifted element, which would otherwise
 leave focus on `<body>`. So after a **keyboard** drop whose lifted item held focus, `[forDropList]`
-restores focus to the item at `currentIndex` in the target container on the next render. That item is
-the same element the user just placed, whether it stayed in this list or transferred to a connected one.
+restores focus on the next render to the item whose `[dragData]` is the dropped item, falling back to the
+item at `currentIndex` in the target container when no item carries it any more. That is the item the user
+just placed, whether it stayed in this list or transferred to a connected one, and whether the `@for`
+tracks by item identity or by `$index`.
 
 Two escape hatches:
 

package/drawer/README.md

@@ -171,7 +171,7 @@ this.#drawers.open(ConfirmDrawer, { data, side: 'bottom', class: 'my-drawer' });
 }
 ```
 
-**Enter / exit animations.** A programmatic drawer is portaled to `document.body` and torn down imperatively, so the consumer can't attach `animate.leave` to the host the way a declarative `@if` block can. Pass `animateEnter` / `animateLeave` (CSS class names) instead: the manager applies `animateEnter` on mount (via `animate.enter`) and, on `close()`, keeps the host mounted with `animateLeave` until its CSS animations / transitions finish before tearing down. `close()` still resolves its promise and flips `isClosed()` immediately. Only the visual teardown waits. Set them once for a scope with `provideForDrawerDefaults({ animateEnter, animateLeave })`; a per-`open()` value wins over the scope default.
+**Enter / exit animations.** A programmatic drawer is portaled to `document.body` and torn down imperatively, so the consumer can't attach `animate.leave` to the host the way a declarative `@if` block can. Pass `animateEnter` / `animateLeave` (CSS class names) instead: the manager applies `animateEnter` on mount (via `animate.enter`) and, on `close()`, keeps the host mounted with `animateLeave` until its CSS animations / transitions finish before tearing down. `close()` still resolves its promise and flips `isClosed()` immediately. Only the visual teardown waits. A template `animate.leave` inside the opened component never runs, because Angular does not run leave animations across the outlet the manager mounts it through; a `[forDrawerBackdrop]` takes its exit class from `backdropAnimateLeave`. Set them once with `provideForDrawerDefaults({ animateEnter, animateLeave, backdropAnimateLeave })`; a per-`open()` value wins over the default. `ForDrawerManager` is provided in root and reads the defaults from the root injector, so a `provideForDrawerDefaults` on a lazy route or in a component's `providers` reaches a programmatic drawer only when that scope's injector is passed as `injector` on the `open()` config.
 
 <!-- snippet: fragment -->
 
@@ -362,10 +362,10 @@ 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.<br>**Default:** `true`                                                                                                                                   |
+| `modal`                     | `boolean`                                                           | `aria-modal`, scroll lock, focus trap, inert siblings, return focus on close.<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`                                                           | Restore focus on close.<br>**Default:** `true`                                                                                                                                                                  |
+| `returnFocus`               | `boolean`                                                           | Modal mode only: restore focus on close. A non-modal drawer never moves focus on close.<br>**Default:** `true`                                                                                                  |
 | `initialFocus`              | `'first' \| 'container'`                                            | **Default:** `'first'`                                                                                                                                                                                          |
 | `ariaLabel`                 | `string \| null`                                                    | Use when no visible title is rendered.<br>**Default:** `null`                                                                                                                                                   |
 | `autoFocusOnOpen`           | `(e: VetoableEvent) => void` \| `undefined`                         | `event.preventDefault()` skips the imperative focus move.<br>**Default:** —                                                                                                                                     |
@@ -518,14 +518,14 @@ For a seamless release, transition **both** `translate` and your snap-position p
 - `closeThreshold` (default `0.25`) is the fraction past which a release from the lowest snap dismisses. It is measured against that snap's own extent (not the full dimension), so a small "peek" snap stays dismissible without dragging it off-screen.
 - `handleOnly: true` confines the gesture to a registered `[forDrawerHandle]`, leaving the rest of the surface free for content scroll.
 - On touch the browser would otherwise claim the swipe as a scroll. The handle always carries `touch-action: none`, and while the whole surface arms the drag (`handleOnly` off, and a drag the drawer can arm) the surface carries an inline `touch-action` that leaves the browser only the other axis: `pan-x` for a `top` / `bottom` drawer, `pan-y` for `left` / `right`. A scroller inside the surface keeps its own native scrolling, so your CSS needs no `touch-action` rule of its own.
-- Gestures starting inside a scrollable element that hasn't reached its edge are NOT treated as swipes (the helper defers to inner scroll).
+- Gestures whose press lands inside a scrollable element that hasn't reached its edge are NOT treated as swipes (the helper defers to inner scroll). The edge is read in the scroller's own writing direction, with a 1 px tolerance for fractional scroll offsets.
 - **`prefers-reduced-motion: reduce`** disables the drag entirely, snap dragging included. Escape, backdrop, outside-pointer, and close button continue to work.
 
 ## Scale background
 
 Opt in to the "viewport recedes behind the drawer" effect: when the drawer opens, the rest of the app shrinks slightly and rounds its corners to read as a layered surface. Two pieces required:
 
-1. Apply `[forDrawerWrapper]` on the element that wraps the rest of the app (typically the root shell). Only one wrapper may be registered at a time.
+1. Apply `[forDrawerWrapper]` on the element that wraps the rest of the app (typically the root shell). Keep one wrapper per page: the most recently mounted one is scaled, and a second one still mounted once the render settles warns in dev mode.
 2. Set `[scaleBackground]="true"` on the drawer that should drive the effect.
 
 ```html

package/dropdown-menu/README.md

@@ -100,7 +100,7 @@ A settings-style dropdown built from the full menu vocabulary: `forMenuGroup` wi
 | `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'` |
 | `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'`                                                                                                                                                  |
-| `disabled`                  | `input<boolean>`                                          | When `true`, trigger interactions are ignored.<br>**Default:** `false`                                                                                                                                                                                                                                                                                 |
+| `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`                                                                                                                                                                                                                                                                             |
 | `ariaLabel`                 | `input<string \| null>`                                   | Manual `aria-label` on `[forMenuContent]` if the trigger isn't a meaningful name.<br>**Default:** `null`                                                                                                                                                                                                                                               |