forty-cdk 0.41.1 → 0.42.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/button/README.md +5 -5
  2. package/calendar/README.md +23 -23
  3. package/carousel/README.md +2 -1
  4. package/checkbox/README.md +9 -9
  5. package/combobox/README.md +20 -18
  6. package/context-menu/README.md +1 -1
  7. package/date-adapter/README.md +1 -1
  8. package/date-field/README.md +2 -2
  9. package/date-picker/README.md +8 -8
  10. package/dialog/README.md +1 -1
  11. package/drag-drop/README.md +54 -14
  12. package/drawer/README.md +4 -3
  13. package/dropdown-menu/README.md +1 -1
  14. package/fesm2022/forty-cdk-accordion.mjs +16 -15
  15. package/fesm2022/forty-cdk-accordion.mjs.map +1 -1
  16. package/fesm2022/forty-cdk-aspect-ratio.mjs +3 -3
  17. package/fesm2022/forty-cdk-avatar.mjs +9 -9
  18. package/fesm2022/forty-cdk-breadcrumbs.mjs +9 -9
  19. package/fesm2022/forty-cdk-button.mjs +12 -16
  20. package/fesm2022/forty-cdk-button.mjs.map +1 -1
  21. package/fesm2022/forty-cdk-calendar.mjs +63 -48
  22. package/fesm2022/forty-cdk-calendar.mjs.map +1 -1
  23. package/fesm2022/forty-cdk-carousel.mjs +46 -34
  24. package/fesm2022/forty-cdk-carousel.mjs.map +1 -1
  25. package/fesm2022/forty-cdk-checkbox.mjs +9 -7
  26. package/fesm2022/forty-cdk-checkbox.mjs.map +1 -1
  27. package/fesm2022/forty-cdk-combobox.mjs +102 -86
  28. package/fesm2022/forty-cdk-combobox.mjs.map +1 -1
  29. package/fesm2022/forty-cdk-context-menu.mjs +11 -9
  30. package/fesm2022/forty-cdk-context-menu.mjs.map +1 -1
  31. package/fesm2022/forty-cdk-core-anchored.mjs +275 -134
  32. package/fesm2022/forty-cdk-core-anchored.mjs.map +1 -1
  33. package/fesm2022/forty-cdk-core-overlay.mjs +73 -41
  34. package/fesm2022/forty-cdk-core-overlay.mjs.map +1 -1
  35. package/fesm2022/forty-cdk-core.mjs +626 -183
  36. package/fesm2022/forty-cdk-core.mjs.map +1 -1
  37. package/fesm2022/forty-cdk-date-adapter.mjs +7 -4
  38. package/fesm2022/forty-cdk-date-adapter.mjs.map +1 -1
  39. package/fesm2022/forty-cdk-date-field.mjs +48 -41
  40. package/fesm2022/forty-cdk-date-field.mjs.map +1 -1
  41. package/fesm2022/forty-cdk-date-picker.mjs +75 -59
  42. package/fesm2022/forty-cdk-date-picker.mjs.map +1 -1
  43. package/fesm2022/forty-cdk-defaults.mjs +9 -9
  44. package/fesm2022/forty-cdk-defaults.mjs.map +1 -1
  45. package/fesm2022/forty-cdk-dialog.mjs +38 -37
  46. package/fesm2022/forty-cdk-dialog.mjs.map +1 -1
  47. package/fesm2022/forty-cdk-disclosure.mjs +9 -9
  48. package/fesm2022/forty-cdk-drag-drop.mjs +106 -76
  49. package/fesm2022/forty-cdk-drag-drop.mjs.map +1 -1
  50. package/fesm2022/forty-cdk-drawer.mjs +61 -53
  51. package/fesm2022/forty-cdk-drawer.mjs.map +1 -1
  52. package/fesm2022/forty-cdk-dropdown-menu.mjs +11 -9
  53. package/fesm2022/forty-cdk-dropdown-menu.mjs.map +1 -1
  54. package/fesm2022/forty-cdk-field.mjs +23 -22
  55. package/fesm2022/forty-cdk-field.mjs.map +1 -1
  56. package/fesm2022/forty-cdk-fieldset.mjs +6 -6
  57. package/fesm2022/forty-cdk-file-upload.mjs +9 -9
  58. package/fesm2022/forty-cdk-hover-card.mjs +59 -22
  59. package/fesm2022/forty-cdk-hover-card.mjs.map +1 -1
  60. package/fesm2022/forty-cdk-input.mjs +6 -10
  61. package/fesm2022/forty-cdk-input.mjs.map +1 -1
  62. package/fesm2022/forty-cdk-internationalized-date.mjs +6 -6
  63. package/fesm2022/forty-cdk-listbox.mjs +162 -81
  64. package/fesm2022/forty-cdk-listbox.mjs.map +1 -1
  65. package/fesm2022/forty-cdk-menu.mjs +142 -79
  66. package/fesm2022/forty-cdk-menu.mjs.map +1 -1
  67. package/fesm2022/forty-cdk-menubar.mjs +51 -36
  68. package/fesm2022/forty-cdk-menubar.mjs.map +1 -1
  69. package/fesm2022/forty-cdk-meter.mjs +6 -6
  70. package/fesm2022/forty-cdk-navigation-menu.mjs +29 -28
  71. package/fesm2022/forty-cdk-navigation-menu.mjs.map +1 -1
  72. package/fesm2022/forty-cdk-number-input.mjs +14 -15
  73. package/fesm2022/forty-cdk-number-input.mjs.map +1 -1
  74. package/fesm2022/forty-cdk-otp-input.mjs +8 -8
  75. package/fesm2022/forty-cdk-otp-input.mjs.map +1 -1
  76. package/fesm2022/forty-cdk-pagination.mjs +16 -15
  77. package/fesm2022/forty-cdk-pagination.mjs.map +1 -1
  78. package/fesm2022/forty-cdk-pane-resizer.mjs +8 -7
  79. package/fesm2022/forty-cdk-pane-resizer.mjs.map +1 -1
  80. package/fesm2022/forty-cdk-popover.mjs +37 -40
  81. package/fesm2022/forty-cdk-popover.mjs.map +1 -1
  82. package/fesm2022/forty-cdk-progress.mjs +6 -6
  83. package/fesm2022/forty-cdk-radio-group.mjs +26 -17
  84. package/fesm2022/forty-cdk-radio-group.mjs.map +1 -1
  85. package/fesm2022/forty-cdk-scroll-area.mjs +22 -21
  86. package/fesm2022/forty-cdk-scroll-area.mjs.map +1 -1
  87. package/fesm2022/forty-cdk-search.mjs +9 -11
  88. package/fesm2022/forty-cdk-search.mjs.map +1 -1
  89. package/fesm2022/forty-cdk-select.mjs +134 -114
  90. package/fesm2022/forty-cdk-select.mjs.map +1 -1
  91. package/fesm2022/forty-cdk-separator.mjs +3 -3
  92. package/fesm2022/forty-cdk-slider.mjs +21 -20
  93. package/fesm2022/forty-cdk-slider.mjs.map +1 -1
  94. package/fesm2022/forty-cdk-stepper.mjs +39 -37
  95. package/fesm2022/forty-cdk-stepper.mjs.map +1 -1
  96. package/fesm2022/forty-cdk-switch.mjs +6 -4
  97. package/fesm2022/forty-cdk-switch.mjs.map +1 -1
  98. package/fesm2022/forty-cdk-table-virtualization.mjs +3 -3
  99. package/fesm2022/forty-cdk-table.mjs +149 -131
  100. package/fesm2022/forty-cdk-table.mjs.map +1 -1
  101. package/fesm2022/forty-cdk-tabs.mjs +21 -16
  102. package/fesm2022/forty-cdk-tabs.mjs.map +1 -1
  103. package/fesm2022/forty-cdk-testing.mjs +1 -0
  104. package/fesm2022/forty-cdk-testing.mjs.map +1 -1
  105. package/fesm2022/forty-cdk-time-field.mjs +48 -41
  106. package/fesm2022/forty-cdk-time-field.mjs.map +1 -1
  107. package/fesm2022/forty-cdk-time-picker.mjs +77 -54
  108. package/fesm2022/forty-cdk-time-picker.mjs.map +1 -1
  109. package/fesm2022/forty-cdk-toast.mjs +53 -29
  110. package/fesm2022/forty-cdk-toast.mjs.map +1 -1
  111. package/fesm2022/forty-cdk-toggle.mjs +30 -21
  112. package/fesm2022/forty-cdk-toggle.mjs.map +1 -1
  113. package/fesm2022/forty-cdk-toolbar.mjs +46 -51
  114. package/fesm2022/forty-cdk-toolbar.mjs.map +1 -1
  115. package/fesm2022/forty-cdk-tooltip.mjs +70 -30
  116. package/fesm2022/forty-cdk-tooltip.mjs.map +1 -1
  117. package/fesm2022/forty-cdk-tree.mjs +268 -111
  118. package/fesm2022/forty-cdk-tree.mjs.map +1 -1
  119. package/fesm2022/forty-cdk-virtual-reorder.mjs +64 -62
  120. package/fesm2022/forty-cdk-virtual-reorder.mjs.map +1 -1
  121. package/fesm2022/forty-cdk-virtualization.mjs +10 -9
  122. package/fesm2022/forty-cdk-virtualization.mjs.map +1 -1
  123. package/field/README.md +5 -12
  124. package/hover-card/README.md +2 -0
  125. package/input/README.md +4 -3
  126. package/listbox/README.md +46 -41
  127. package/menu/README.md +24 -22
  128. package/menubar/README.md +19 -19
  129. package/number-input/README.md +2 -1
  130. package/otp-input/README.md +2 -1
  131. package/package.json +1 -1
  132. package/pagination/README.md +9 -9
  133. package/radio-group/README.md +11 -11
  134. package/search/README.md +7 -5
  135. package/select/README.md +10 -10
  136. package/slider/README.md +1 -1
  137. package/stepper/README.md +2 -1
  138. package/switch/README.md +11 -11
  139. package/table/README.md +1 -1
  140. package/tabs/README.md +2 -2
  141. package/time-field/README.md +2 -2
  142. package/time-picker/README.md +21 -18
  143. package/toast/README.md +1 -1
  144. package/toggle/README.md +4 -4
  145. package/toolbar/README.md +5 -5
  146. package/tooltip/README.md +1 -0
  147. package/tree/README.md +52 -38
  148. package/types/forty-cdk-accordion.d.ts +6 -35
  149. package/types/forty-cdk-avatar.d.ts +0 -37
  150. package/types/forty-cdk-button.d.ts +4 -2
  151. package/types/forty-cdk-calendar.d.ts +16 -49
  152. package/types/forty-cdk-carousel.d.ts +11 -82
  153. package/types/forty-cdk-combobox.d.ts +19 -390
  154. package/types/forty-cdk-context-menu.d.ts +12 -40
  155. package/types/forty-cdk-core-anchored.d.ts +233 -247
  156. package/types/forty-cdk-core-overlay.d.ts +37 -39
  157. package/types/forty-cdk-core.d.ts +628 -590
  158. package/types/forty-cdk-date-adapter.d.ts +5 -0
  159. package/types/forty-cdk-date-field.d.ts +15 -41
  160. package/types/forty-cdk-date-picker.d.ts +35 -70
  161. package/types/forty-cdk-defaults.d.ts +29 -296
  162. package/types/forty-cdk-dialog.d.ts +3 -19
  163. package/types/forty-cdk-disclosure.d.ts +0 -5
  164. package/types/forty-cdk-drag-drop.d.ts +20 -24
  165. package/types/forty-cdk-drawer.d.ts +14 -35
  166. package/types/forty-cdk-dropdown-menu.d.ts +14 -10
  167. package/types/forty-cdk-field.d.ts +9 -9
  168. package/types/forty-cdk-file-upload.d.ts +0 -5
  169. package/types/forty-cdk-hover-card.d.ts +14 -50
  170. package/types/forty-cdk-listbox.d.ts +70 -171
  171. package/types/forty-cdk-menu.d.ts +55 -21
  172. package/types/forty-cdk-menubar.d.ts +21 -13
  173. package/types/forty-cdk-meter.d.ts +0 -7
  174. package/types/forty-cdk-navigation-menu.d.ts +6 -101
  175. package/types/forty-cdk-otp-input.d.ts +0 -17
  176. package/types/forty-cdk-pagination.d.ts +6 -24
  177. package/types/forty-cdk-pane-resizer.d.ts +6 -5
  178. package/types/forty-cdk-popover.d.ts +9 -45
  179. package/types/forty-cdk-progress.d.ts +0 -7
  180. package/types/forty-cdk-radio-group.d.ts +10 -35
  181. package/types/forty-cdk-scroll-area.d.ts +7 -37
  182. package/types/forty-cdk-select.d.ts +48 -375
  183. package/types/forty-cdk-slider.d.ts +5 -15
  184. package/types/forty-cdk-stepper.d.ts +5 -31
  185. package/types/forty-cdk-table.d.ts +13 -333
  186. package/types/forty-cdk-tabs.d.ts +6 -42
  187. package/types/forty-cdk-time-field.d.ts +15 -41
  188. package/types/forty-cdk-time-picker.d.ts +19 -112
  189. package/types/forty-cdk-toast.d.ts +1 -125
  190. package/types/forty-cdk-toggle.d.ts +2 -2
  191. package/types/forty-cdk-toolbar.d.ts +10 -11
  192. package/types/forty-cdk-tooltip.d.ts +19 -31
  193. package/types/forty-cdk-tree.d.ts +45 -260
  194. package/types/forty-cdk-virtual-reorder.d.ts +7 -4
  195. package/types/forty-cdk-virtualization.d.ts +2 -28
  196. package/virtual-reorder/README.md +8 -1
  197. package/virtualization/README.md +17 -17
package/button/README.md CHANGED
@@ -45,7 +45,7 @@ export class ButtonDefaultExample {}
45
45
 
46
46
  ### Disabled stays focusable
47
47
 
48
- Per the APG, a disabled button must stay reachable so assistive tech can announce it. `forButton` never sets the native `disabled` attribute. Instead, it reflects `aria-disabled='true'` + `data-disabled` and makes activation a no-op. The native disabled button is skipped entirely.
48
+ Per the APG, a disabled button must stay reachable so assistive tech can announce it. `forButton` never sets the native `disabled` attribute. Instead, it reflects `aria-disabled='true'` + `data-disabled` and cancels every click, so neither `(activate)` nor a `(click)` bound on the button runs. The native disabled button is skipped entirely.
49
49
 
50
50
  ## Disabled
51
51
 
@@ -82,10 +82,10 @@ A binding that resolves to `null` removes the attribute, so the button falls bac
82
82
 
83
83
  ### `ForButton`
84
84
 
85
- | Property | Type | Description |
86
- | ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
87
- | `disabled` | `input<boolean>` | Suppresses activation and reflects `aria-disabled` + `data-disabled`. OR'd with a surrounding `[forFieldset]`'s disabled state.<br>**Default:** `false` |
88
- | `activate` | `output<void>` | Fires once per user activation (click, Enter, Space). Never fires when disabled.<br>**Default:** — |
85
+ | Property | Type | Description |
86
+ | ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
87
+ | `disabled` | `input<boolean>` | Cancels every click, so neither `(activate)` nor a `(click)` bound on the button runs, and reflects `aria-disabled` + `data-disabled`. OR'd with a surrounding `[forFieldset]`'s disabled state.<br>**Default:** `false` |
88
+ | `activate` | `output<void>` | Fires once per user activation (click, Enter, Space). Never fires when disabled.<br>**Default:** — |
89
89
 
90
90
  The directive reflects boolean `data-*` attributes (present with an empty-string value when true, absent when false). There is no `data-state`, because this primitive has no open/closed or checked/unchecked logical state.
91
91
 
@@ -210,22 +210,22 @@ Click the heading button to cycle from day → month → year view. Click a mont
210
210
 
211
211
  ### `ForCalendar`
212
212
 
213
- | Property | Type | Description |
214
- | ------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
215
- | `value` | `model<D \| null>` | Two-way bindable selected date, or `null`. Used in `selectionMode="single"`. `(valueChange)` fires only on internal selection.<br>**Default:** `null` |
216
- | `selectionMode` | `input<'single' \| 'range'>` | `'single'` (default) keeps the single-date `value` flow. `'range'` switches to anchor → commit and exposes `range`.<br>**Default:** `'single'` |
217
- | `range` | `model<DateRange<D> \| null>` | Two-way bindable committed range. Only used in `selectionMode="range"`. `(rangeChange)` fires only on internal commits.<br>**Default:** `null` |
218
- | `minRangeLength` | `input<number \| null>` | Minimum inclusive day count. A commit shorter than this is a no-op.<br>**Default:** `null` (no minimum) |
219
- | `maxRangeLength` | `input<number \| null>` | Maximum inclusive day count. A commit longer than this is a no-op.<br>**Default:** `null` (no maximum) |
220
- | `min` | `input<D \| null>` | Minimum selectable date (inclusive). Earlier dates are unavailable.<br>**Default:** `null` |
221
- | `max` | `input<D \| null>` | Maximum selectable date (inclusive). Later dates are unavailable.<br>**Default:** `null` |
222
- | `isDateUnavailable` | `input<(date: D) => boolean>` | Per-date predicate marking a date unavailable (present but not selectable).<br>**Default:** `() => false` |
223
- | `dateLabel` | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date).<br>**Default:** localized full date, outside-month days through the scope's `outsideMonthLabel` |
224
- | `disabled` | `input<boolean>` | Disables the whole calendar (no focus movement, no selection). Reflected as `data-disabled`.<br>**Default:** — |
225
- | `readonly` | `input<boolean>` | Read-only: dates stay focusable, selection is blocked. Reflected as `data-readonly`.<br>**Default:** — |
226
- | `firstDayOfWeek` | `input<number \| null>` | First column's weekday, **0-6** (`0` = Sunday).<br>**Default:** `null` → the adapter's value (or `provideForCalendarDefaults`) |
227
- | `locale` | `input<string \| null>` | BCP 47 locale for the heading, weekday headers, month-picker options and cell `aria-label` names. The calendar system stays Gregorian.<br>**Default:** `null` → the adapter's `locale()`, then the runtime locale |
228
- | `dir` | `input<'ltr' \| 'rtl' \| null>` | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir` and mirrors horizontal arrows |
213
+ | Property | Type | Description |
214
+ | ------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
215
+ | `value` | `model<D \| null>` | Two-way bindable selected date, or `null`. Used in `selectionMode="single"`. `(valueChange)` fires only on internal selection.<br>**Default:** `null` |
216
+ | `selectionMode` | `input<'single' \| 'range'>` | `'single'` (default) keeps the single-date `value` flow. `'range'` switches to anchor → commit and exposes `range`.<br>**Default:** `'single'` |
217
+ | `range` | `model<DateRange<D> \| null>` | Two-way bindable committed range. Only used in `selectionMode="range"`. `(rangeChange)` fires only on internal commits.<br>**Default:** `null` |
218
+ | `minRangeLength` | `input<number \| null>` | Minimum inclusive day count. A commit shorter than this is a no-op.<br>**Default:** `null` (no minimum) |
219
+ | `maxRangeLength` | `input<number \| null>` | Maximum inclusive day count. A commit longer than this is a no-op.<br>**Default:** `null` (no maximum) |
220
+ | `min` | `input<D \| null>` | Minimum selectable date (inclusive). Earlier dates are unavailable.<br>**Default:** `null` |
221
+ | `max` | `input<D \| null>` | Maximum selectable date (inclusive). Later dates are unavailable.<br>**Default:** `null` |
222
+ | `isDateUnavailable` | `input<(date: D) => boolean>` | Per-date predicate marking a date unavailable (present but not selectable).<br>**Default:** `() => false` |
223
+ | `dateLabel` | `input<CalendarDateLabelFormatter<D>>` | Formats each gridcell's `aria-label` (full accessible date).<br>**Default:** localized full date, outside-month days through the scope's `outsideMonthLabel` |
224
+ | `disabled` | `input<boolean>` | Disables the whole calendar (no focus movement, no selection). Reflected as `data-disabled`.<br>**Default:** — |
225
+ | `readonly` | `input<boolean>` | Read-only: dates stay focusable, selection is blocked. Reflected as `data-readonly`.<br>**Default:** — |
226
+ | `firstDayOfWeek` | `input<number \| null>` | First column's weekday, **0-6** (`0` = Sunday).<br>**Default:** `null` → the adapter's value (or `provideForCalendarDefaults`) |
227
+ | `locale` | `input<string \| null>` | BCP 47 locale for the heading, weekday headers, month-picker options, cell `aria-label` names and the digits of day and year labels. The calendar system stays Gregorian.<br>**Default:** `null` → the adapter's `locale()`, then the runtime locale |
228
+ | `dir` | `input<'ltr' \| 'rtl' \| null>` | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir` when set or declared and mirrors horizontal arrows |
229
229
 
230
230
  ### Data attributes
231
231
 
@@ -354,7 +354,7 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
354
354
  [maxYear]="2100"
355
355
  >
356
356
  @for (opt of y.years(); track opt.value) {
357
- <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.value }}</option>
357
+ <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.label }}</option>
358
358
  }
359
359
  </select>
360
360
  <button forCalendarNextButton [ariaLabel]="'Next month'">
@@ -385,11 +385,11 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
385
385
 
386
386
  #### `ForCalendarYearSelect` API
387
387
 
388
- | API | Description |
389
- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
390
- | `minYear` | `input<number \| null>`: the lowest listed year. Defaults to `currentYear - 100` when `null`. |
391
- | `maxYear` | `input<number \| null>`: the highest listed year. Defaults to `currentYear + 10` when `null`. |
392
- | `years()` | `Signal<readonly CalendarYearOption[]>`: years from `minYear` to `maxYear` inclusive, each `disabled` when the whole year falls outside `[min, max]`. |
388
+ | API | Description |
389
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
390
+ | `minYear` | `input<number \| null>`: the lowest listed year. Defaults to `currentYear - 100` when `null`. |
391
+ | `maxYear` | `input<number \| null>`: the highest listed year. Defaults to `currentYear + 10` when `null`. |
392
+ | `years()` | `Signal<readonly CalendarYearOption[]>`: years from `minYear` to `maxYear` inclusive, each with a `label` in the calendar locale's digits and `disabled` when the whole year falls outside `[min, max]`. |
393
393
 
394
394
  The default window is **anchored to the current year** (not the visible year), so navigating far away never drops the current year off the list. Out-of-`[min, max]` entries have `disabled: true`, matching the `CalendarYearOption` shape. Both directives set the native `disabled` attribute on the `<select>` itself when the calendar is disabled.
395
395
 
@@ -493,7 +493,7 @@ The heading's `label()` follows the active view, with the same text as the view
493
493
  @for (row of yg.rows(); track row.key) {
494
494
  <tr>
495
495
  @for (y of row.years; track y.value) {
496
- <td forCalendarYearCell [year]="y.value">{{ y.value }}</td>
496
+ <td forCalendarYearCell [year]="y.value">{{ y.label }}</td>
497
497
  }
498
498
  </tr>
499
499
  }
@@ -474,7 +474,8 @@ Reflected on the `[forCarouselViewport]` host this directive is applied to:
474
474
  Keyboard navigation lives on the indicator group. Only the current
475
475
  indicator is in the tab order, including after prev / next, autoplay or a drag
476
476
  moved the slide. Arrow keys move focus and activate the target slide
477
- automatically.
477
+ automatically. Removing the focused indicator moves focus to the indicator that
478
+ then holds the Tab stop, so focus never falls to `<body>`.
478
479
 
479
480
  | Key | Action |
480
481
  | -------------------------- | --------------------------------------------------------------------- |
@@ -130,7 +130,7 @@ One class and one directive, three states. `disabled` and `readonly` both keep t
130
130
 
131
131
  ### Signal Forms
132
132
 
133
- `forCheckbox` implements `FormCheckboxControl`, so a single `[formField]` binding wires the binary `checked` value into the form and pulls validity back out. The box is required: blur it unchecked and it reflects `data-invalid` / `data-touched`.
133
+ `forCheckbox` implements `FormCheckboxControl`, so a single `[formField]` binding wires the binary `checked` value into the form and pulls validity back out. The box is required: tick and untick it and it reflects `data-invalid` / `data-touched`.
134
134
 
135
135
  ```ts
136
136
  import { Component, signal } from '@angular/core';
@@ -159,14 +159,14 @@ export class DemoCheckout {
159
159
 
160
160
  ### `ForCheckbox`
161
161
 
162
- | Property | Type | Description |
163
- | ------------------------------------------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164
- | `checked` | `model<boolean>` | Two-way bindable on/off. Required by `FormCheckboxControl`.<br>**Default:** — |
165
- | `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:** — |
166
- | `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:** — |
167
- | `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:** `''` |
168
- | `errors` | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Validation errors fed by `[formField]`.<br>**Default:** — |
169
- | `touched` | `model<boolean>` | Set to `true` on blur.<br>**Default:** `false` |
162
+ | Property | Type | Description |
163
+ | ------------------------------------------------------------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164
+ | `checked` | `model<boolean>` | Two-way bindable on/off. Required by `FormCheckboxControl`.<br>**Default:** — |
165
+ | `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:** — |
166
+ | `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:** — |
167
+ | `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. A bound `[required]` blocks native submission while unchecked, as a native required control does: an unnamed, visually hidden `<input required>` fails constraint validation, `form:invalid` matches, and when the browser reports the form, focus moves to the checkbox.<br>**Default:** `''` |
168
+ | `errors` | `input<readonly ValidationError.WithOptionalFieldTree[]>` | Validation errors fed by `[formField]`.<br>**Default:** — |
169
+ | `touched` | `model<boolean>` | Set to `true` on activation and on blur.<br>**Default:** `false` |
170
170
 
171
171
  | Data attribute | Values |
172
172
  | --------------- | ------------------------------------------- |
@@ -355,7 +355,7 @@ Add two parts:
355
355
 
356
356
  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]`.
357
357
 
358
- **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).
358
+ **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`). Two closes skip the return, and emit no `(autoFocusOnClose)` either: an **outside-interaction close**, meaning a pointer-down or focus-out that lands outside the panel, leaves focus where the interaction moved it, and a `Tab` out leaves it where the browser advanced it. `Tab` from the last control in the panel continues from the trigger, and `Shift+Tab` from the first lands on it. Escape stays owned by the input. See [Focus & the `(autoFocusOnOpen)` / `(autoFocusOnClose)` hooks](#focus--the-autofocusonopen--autofocusonclose-hooks).
359
359
 
360
360
  **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.
361
361
 
@@ -564,6 +564,8 @@ Chips are intentionally **out of the Tab cycle**: Tab from outside lands on the
564
564
  | **Backspace / Delete** | Remove this chip + focus the previous chip (or the input if it was the only / last chip). |
565
565
  | **Escape** | Return focus to the input. |
566
566
 
567
+ On a `readonly` combobox the chips keep the arrow keys and Escape, and Backspace / Delete remove nothing.
568
+
567
569
  In RTL the chip cluster lays out right-to-left, so **ArrowRight** moves to the visually-next chip (DOM-previous) and **ArrowLeft** moves to the visually-previous one (DOM-next, hopping to the input at the leftmost visual edge).
568
570
 
569
571
  `[forComboboxChipRemove]` is a click-only target (also out of Tab cycle) with auto-generated `aria-label="Remove <chip label>"`. The name is computed per chip, so the piece takes no `[ariaLabel]` input and ignores a static `aria-label` attribute. Localize it centrally by overriding the scope's builder:
@@ -639,7 +641,7 @@ The two anatomies have different focus models:
639
641
  | `(autoFocusOnOpen)` | Just before focus enters the input on open. | Focus stays on the trigger. |
640
642
  | `(autoFocusOnClose)` | Just before focus returns to the trigger. | Focus stays where it is. |
641
643
 
642
- Return focus is also gated by `[returnFocus]` (default `true`) and is skipped on a Tab close (Tab already advanced focus past the closing panel).
644
+ Return focus is also gated by `[returnFocus]` (default `true`). It is skipped, and `(autoFocusOnClose)` is not emitted, after an outside-interaction close (a pointer-down or focus-out outside the panel, which leaves focus where it moved) and after a Tab close (Tab already advanced focus past the closing panel). Escape, a pick and programmatic closes still return focus.
643
645
 
644
646
  ## Object values
645
647
 
@@ -844,7 +846,7 @@ Static and `@for`-rendered options share the same registry, navigation order (DO
844
846
  </div>
845
847
  ```
846
848
 
847
- 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.
849
+ 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. With `[required]` bound, an empty combobox blocks native submission the way a native `<select required>` does: the directive mounts one unnamed, visually hidden `<input required tabindex="-1" aria-hidden="true">` beside the hidden inputs, so the browser's constraint validation fails and `form:invalid` matches. When the browser reports the form, focus moves to the input, or to the trigger in the picker anatomy. That input submits nothing, is skipped while the combobox is disabled, and is satisfied once a value is selected, whatever the query holds.
848
850
 
849
851
  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).
850
852
 
@@ -852,21 +854,21 @@ A single-select field is modeled as the same `readonly T[]`, kept at length ≤
852
854
 
853
855
  Focus stays in the input throughout: arrow keys move the listbox's _active descendant_ (the highlighted option), not DOM focus.
854
856
 
855
- | Key | Action |
856
- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
857
- | **ArrowDown** | Open listbox + move activedescendant to next enabled option (or first when none; the selection under `openHighlight="selected"`). |
858
- | **ArrowUp** | Open listbox + move activedescendant to previous enabled option (or last when none; the selection under `openHighlight="selected"`). |
859
- | **Home** _(open)_ | Move activedescendant to first enabled option. |
860
- | **End** _(open)_ | Move activedescendant to last enabled option. |
861
- | **PageUp** _(open)_ | Move activedescendant to first enabled option. |
862
- | **PageDown** _(open)_ | Move activedescendant to last enabled option. |
863
- | **Enter** _(open)_ | Activate the activedescendant (single: replace + close; multi: toggle + stay open). |
864
- | **Escape** _(open)_ | Close the listbox. Focus stays in the input. |
865
- | **Tab** _(open, no action)_ | Close the listbox and let Tab flow to the next focusable. |
866
- | **Tab / Shift+Tab** _(open, action present)_ | Move focus around the input↔actions ring without dismissing (see [Action items](#action-items)). |
867
- | **Backspace** _(empty input, multi only)_ | Focus the last chip; a second Backspace there removes it. |
868
- | **ArrowLeft / ArrowRight** | Move the caret, accepting a pending inline completion. |
869
- | Printable keys | Update `query`. With `'inline'` / `'both'` autocomplete, complete the rest of the first match into the input as selected text. |
857
+ | Key | Action |
858
+ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
859
+ | **ArrowDown** | Open listbox + move activedescendant to next enabled option (or first when none; the selection under `openHighlight="selected"`). |
860
+ | **ArrowUp** | Open listbox + move activedescendant to previous enabled option (or last when none; the selection under `openHighlight="selected"`). |
861
+ | **Home** _(open)_ | Move activedescendant to first enabled option. |
862
+ | **End** _(open)_ | Move activedescendant to last enabled option. |
863
+ | **PageUp** _(open)_ | Move activedescendant to first enabled option. |
864
+ | **PageDown** _(open)_ | Move activedescendant to last enabled option. |
865
+ | **Enter** _(open)_ | Activate the activedescendant (single: replace + close; multi: toggle + stay open). |
866
+ | **Escape** _(open)_ | Close the listbox. Focus stays in the input. |
867
+ | **Tab** _(open, no action)_ | Close the listbox and let Tab flow to the next focusable. In the picker anatomy Tab continues from the trigger and Shift+Tab lands on it. |
868
+ | **Tab / Shift+Tab** _(open, action present)_ | Move focus around the input↔actions ring without dismissing (see [Action items](#action-items)). |
869
+ | **Backspace** _(empty input, multi only)_ | Focus the last chip; a second Backspace there removes it. |
870
+ | **ArrowLeft / ArrowRight** | Move the caret, accepting a pending inline completion. |
871
+ | Printable keys | Update `query`. With `'inline'` / `'both'` autocomplete, complete the rest of the first match into the input as selected text. |
870
872
 
871
873
  With `'inline'` / `'both'` autocomplete, Tab, Enter with no option activated, and Home / End while closed also accept a pending completion (see [Autocomplete modes](#autocomplete-modes)).
872
874
 
@@ -97,7 +97,7 @@ The same menu vocabulary the Dropdown Menu exposes, anchored to the pointer on r
97
97
  | `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` |
98
98
  | `disabled` | `input<boolean>` | When `true`, the contextmenu event falls through to the native browser menu.<br>**Default:** `false` |
99
99
  | `dismissible` | `input<boolean>` | When `false`, Escape and outside interactions don't close.<br>**Default:** `true` |
100
- | `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` |
100
+ | `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, except after an outside or Tab close.<br>**Default:** `true` |
101
101
  | `ariaLabel` | `input<string \| null>` | Accessible name reflected as `aria-label` on `[forMenuContent]`. The root's only name hook for a context menu: the right-click region is never used as an `aria-labelledby` target.<br>**Default:** `null` |
102
102
  | `escapeKeyDown` | `output<VetoableNativeEvent<KeyboardEvent>>` | Output. Escape pressed while the menu is the topmost dismissible layer.<br>**Default:** — |
103
103
  | `pointerDownOutside` | `output<VetoableNativeEvent<PointerEvent>>` | Output. Pointer-down on a target outside content + trigger.<br>**Default:** — |
@@ -43,6 +43,6 @@ Measured on a production build of an app with four lazy routes (Tooltip, Calenda
43
43
  | `FOR_DATE_ADAPTER` | token | Holds the active adapter. A date or time primitive with no adapter in scope throws `FORCDK-CORE-002`. |
44
44
  | `NativeDateAdapter` | class | A time-capable adapter over the built-in `Date`. Subclass it and override `locale()` to format in the app's language. |
45
45
  | `provideNativeDateAdapter()` | provider | Binds `NativeDateAdapter` to `FOR_DATE_ADAPTER`. |
46
- | `createFormatterCache()` | function | Returns a function that hands back one `Intl.DateTimeFormat` per distinct `(locale, options)` pair, for an adapter of your own to format through. |
46
+ | `createFormatterCache()` | function | Returns a function that hands back one Gregorian `Intl.DateTimeFormat` per distinct `(locale, options)` pair, for an adapter of your own to format through. A `calendar` in `options` overrides it. |
47
47
 
48
48
  `injectDateAdapter` and `assertTimeCapable` are not here: they throw through the library's error helpers, which live with the primitives, and ship from [`forty-cdk/shared`](../shared).
@@ -170,7 +170,7 @@ Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled
170
170
 
171
171
  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.
172
172
 
173
- 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.
173
+ 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. A bound `[required]` blocks native submission until a complete date is entered, as a native required control does: an unnamed, visually hidden `<input required>` fails constraint validation, `form:invalid` matches, and when the browser reports the form, focus moves to the first editable segment.
174
174
 
175
175
  > **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.
176
176
 
@@ -302,7 +302,7 @@ readonly booking = form(this.model);
302
302
 
303
303
  The endpoint groups each accept an `ariaLabel` input for their own group label, falling back to the scope defaults (`'Start date'` / `'End date'`); bind `[ariaLabel]="null"` to drop the name. Plus the shared `FormUiControl` members bound automatically by `[formField]`.
304
304
 
305
- `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()`.
305
+ `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()`. A bound `[required]` blocks native submission until a complete range is entered, the same way a single field does.
306
306
 
307
307
  > **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.
308
308
 
@@ -210,7 +210,7 @@ Open the picker and click a first day: the trigger keeps its placeholder, becaus
210
210
  | `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:** — |
211
211
  | `modal` | `input<boolean>` | Trap focus + inert background + scroll lock (centered dialog) instead of an anchored popover.<br>**Default:** `false` |
212
212
  | `dismissible` | `input<boolean>` | Escape / outside-pointer dismiss the surface.<br>**Default:** `true` |
213
- | `returnFocus` | `input<boolean>` | Return focus to the trigger on close.<br>**Default:** `true` |
213
+ | `returnFocus` | `input<boolean>` | Return focus to the trigger on close, except after an outside or Tab close.<br>**Default:** `true` |
214
214
  | `formatOptions` | `input<Intl.DateTimeFormatOptions>` | Options for the text rendered by `[forDatePickerValue]`.<br>**Default:** `{ year: 'numeric', month: 'long', day: 'numeric' }` |
215
215
  | `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 |
216
216
  | `placeholder` | `input<string>` | Fallback text for `[forDatePickerValue]` when empty.<br>**Default:** `''` |
@@ -222,7 +222,7 @@ Open the picker and click a first day: the trigger keeps its placeholder, becaus
222
222
  | `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'` |
223
223
  | `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` |
224
224
  | `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` |
225
- | `dir` | `input<'ltr' \| 'rtl' \| null>` | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir` |
225
+ | `dir` | `input<'ltr' \| 'rtl' \| null>` | Writing direction.<br>**Default:** `null` resolves the ambient direction; reflected to the host `dir` when set or declared |
226
226
 
227
227
  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.
228
228
 
@@ -234,7 +234,7 @@ Plus the shared `FormUiControl` inputs from the base (`disabled`, `readonly`, `r
234
234
 
235
235
  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.
236
236
 
237
- 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.
237
+ A native reset of the owning `<form>` returns `value` to what it held when the picker first rendered. It also drops a partly typed entry in the projected field in the [field anatomy](#field-anatomy), and a partly typed time in the projected time field or time picker of a [date-time picker](#date-time-picker), in either anatomy. A Signal Forms `form().reset()` drops the same entries. A bound `[required]` blocks native submission while no date is committed, as a native required control does: an unnamed, visually hidden `<input required>` fails constraint validation, `form:invalid` matches, and when the browser reports the form, focus moves to the trigger, or to the projected field in the field anatomy.
238
238
 
239
239
  ### Data attributes
240
240
 
@@ -343,7 +343,7 @@ Set `granularity` to `'hour'`, `'minute'`, or `'second'` to turn the picker into
343
343
 
344
344
  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.
345
345
 
346
- 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.
346
+ 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. A time set before any day is picked lands on today, or on the nearest bound's day when today is outside `[minDate, maxDate]`, the day the calendar focuses.
347
347
 
348
348
  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.
349
349
 
@@ -425,7 +425,7 @@ The default anatomy makes the trigger the control: it shows the value and takes
425
425
 
426
426
  With the field adopted:
427
427
 
428
- - **One form control.** The picker stays the `FormValueControl`, so `[formField]` binds once, on the picker. A typed date and a calendar pick both write the picker's value, and both mark it dirty; a pick marks it touched, and so does focus leaving the field.
428
+ - **One form control.** The picker stays the `FormValueControl`, so `[formField]` binds once, on the picker. A typed date and a calendar pick both write the picker's value, and both mark it dirty; a pick marks it touched, and so does focus leaving the picker, while a move between the field and the trigger does not.
429
429
  - **State is set once.** `minDate`, `maxDate`, `disabled`, `readonly`, `granularity`, `hourCycle` and `locale` on the picker apply to the field. A read-only picker blocks typing and picking alike.
430
430
  - **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.
431
431
  - **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.
@@ -482,9 +482,9 @@ readonly booking = form(this.model, (p) => required(p.stay));
482
482
  </div>
483
483
  ```
484
484
 
485
- - **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.
485
+ - **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 an outside dismissal, never on Escape, exactly like the single-date picker.
486
486
  - **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).
487
- - **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.
487
+ - **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. A bound `[required]` blocks native submission until both endpoints are committed.
488
488
  - **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.
489
489
 
490
490
  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).
@@ -508,7 +508,7 @@ Implements the [WAI-ARIA Date Picker Dialog pattern](https://www.w3.org/WAI/ARIA
508
508
  - **`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).
509
509
  - **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`.
510
510
  - **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.
511
- - **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.
511
+ - **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. A `Tab` out leaves focus where the browser advanced it. Escape, a pick and programmatic closes still return focus.
512
512
  - **Dismissal**: Escape (`(escapeKeyDown)`) and outside-pointer (`(pointerDownOutside)` / `(interactOutside)`) close the surface, each vetoable.
513
513
 
514
514
  ## Styling
package/dialog/README.md CHANGED
@@ -279,7 +279,7 @@ this.dialogs.open(ConfirmDialog, { data, alert: true, class: 'my-dialog my-dialo
279
279
 
280
280
  The tokens go on the real `[forDialog]` host alongside `data-state` / `role` / `aria-modal`, merged and de-duped, never clobbering those attributes.
281
281
 
282
- **Enter / exit animations.** A programmatic dialog 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. With no class (or under `prefers-reduced-motion`, if your CSS disables the animation) close is immediate.
282
+ **Enter / exit animations.** A programmatic dialog 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, and the overlay stops being modal at the same moment: its focus trap, inert siblings, scroll lock and Escape layer are released and focus returns. Only the DOM removal waits. With no class (or under `prefers-reduced-motion`, if your CSS disables the animation) close is immediate.
283
283
 
284
284
  <!-- snippet: fragment -->
285
285
 
@@ -169,14 +169,26 @@ unchecks the item's own and no cloned media plays or frame reloads.
169
169
  | Idle | Arrow keys | Move roving focus between items |
170
170
  | Idle | Home / End | Jump to first / last item |
171
171
  | Idle | Space/Enter | **Lift** the focused item |
172
- | Lifted | Arrow keys | Step the logical drop position |
172
+ | Lifted | Arrow keys | Step the logical drop position, across connected lists |
173
173
  | Lifted | Home / End | Jump the lifted item to the first / last position |
174
174
  | Lifted | Space/Enter | **Drop** (commits, emits `(dragDrop)`, focus follows the item) |
175
175
  | Lifted | Escape | **Cancel** (no event, focus stays on item) |
176
176
 
177
+ Removing the focused item outside a drop moves focus to the item that takes over the Tab stop, the one
178
+ before it or else the one after, so focus never falls to `<body>`. A drop keeps the rules of
179
+ [Focus after a keyboard drop](#focus-after-a-keyboard-drop).
180
+
177
181
  Arrow direction follows the list's `orientation` and respects RTL via `dir`. In
178
182
  `orientation="mixed"` every arrow key steps the lifted item linearly in DOM order.
179
183
 
184
+ With connected lists (`[forDropListGroup]` or `[connectedTo]`), the lifted item steps through one
185
+ sequence of positions: every position of the list it was lifted from, then every position of each
186
+ connected list, including the append position past its last item. Connected lists come in
187
+ `[connectedTo]` order, then in the order the group's lists registered. Home and End jump to the two
188
+ ends of that sequence, and a step past either end does nothing and announces nothing. The
189
+ announcement names the list a position belongs to whenever it is not the source list, so a
190
+ transfer never sounds like a reorder.
191
+
180
192
  `[dragDisabled]` and a disabled `[forDropList]` stop a lift from starting, nothing else. A
181
193
  `[dragDisabled]` item still takes the idle arrow and Home / End keys (only a disabled list stops
182
194
  those), and an item that was already lifted when it or its list became disabled keeps every lifted
@@ -186,6 +198,24 @@ key, so Escape always ends the gesture.
186
198
 
187
199
  Keyboard lifting, stepping, dropping, and cancellation are announced via ARIA live regions. Override the default messages at any injector scope via `provideForDragDropDefaults` (see [Scoped defaults](#scoped-defaults)). Free-drag is pointer-only. There is no WAI-ARIA pattern for "reposition an element", so `[forFreeDrag]` owns no role or ARIA state; the consumer is responsible for keeping the moved element fully usable at its default position.
188
200
 
201
+ ### Item names
202
+
203
+ Every lift, move, drop and cancel announcement names the item the way a screen reader would: by
204
+ the text its `aria-labelledby` references, else by its `aria-label`, else by its text with any
205
+ `aria-hidden` content (such as a `[forDragHandle]` glyph) left out and a space between adjacent
206
+ elements. Set `[textValue]` on `[forDraggable]` to name an item in announcements by a string of
207
+ your own; an empty or `null` value falls back to the item's own name. The same name is used by
208
+ `[forVirtualReorder]` and `[forTableRowReorder]`.
209
+
210
+ ```html
211
+ <li forDraggable [dragData]="task" [textValue]="task.title">
212
+ <strong>{{ task.title }}</strong><span>{{ task.due }}</span>
213
+ </li>
214
+ ```
215
+
216
+ A list is named in an announcement by its `aria-labelledby` or `aria-label`, never by its items, so
217
+ label each list of a transfer.
218
+
189
219
  ### Role description
190
220
 
191
221
  Each `[forDraggable]` that can be lifted carries `aria-roledescription`, `"sortable"` by default.
@@ -288,13 +318,20 @@ scrolling, and the item around it leaves touch scrolling alone. Both follow the
288
318
  mounted or removed after the first render moves the `touch-action: none` between the handle and
289
319
  the item, and a disabled item or list drops it from both.
290
320
 
321
+ An item with no handle carries `touch-action: none` itself, so it takes every touch move that
322
+ starts on it. A scroller made only of handle-less items, such as a virtualized list or an
323
+ `overflow: auto` kanban column, therefore cannot be scrolled by touch. Give those items a
324
+ `[forDragHandle]`: the rest of each item then pans the scroller, and the handle starts the drag.
325
+
291
326
  ### Native drag
292
327
 
293
328
  Images, links and selected text are draggable by the browser itself, and its own drag starts
294
329
  before a pointer drag arms. A `[forDraggable]` or `[forFreeDrag]` therefore cancels the native
295
330
  `dragstart` of every press it would turn into a pointer drag, so pressing a thumbnail inside an
296
331
  item reorders the item instead of dragging a copy of the image. Content outside the item's
297
- handles, and every press while the item or its list is disabled, keeps its native drag.
332
+ handles, and every press while the item or its list is disabled, keeps its native drag. The
333
+ same holds for every pointer reorder in the library: `[forTreeNodeDrag]`, `[forListboxReorder]`,
334
+ table row reorder and `[forVirtualReorder]`.
298
335
 
299
336
  ### Nested controls
300
337
 
@@ -692,20 +729,20 @@ onDrop(event: ForDragDropEvent): void {
692
729
 
693
730
  `provideForDragDropDefaults` configures drag-drop defaults for an injector subtree, either at the application root or in any component's `providers` array. They apply to `[forDropList]` and `[forDraggable]`, and to the reorder coordinators `[forListboxReorder]`, `[forTreeNodeDrag]`, `[forTableRowReorder]` and `[forVirtualReorder]`. Partial overrides inherit unspecified keys from the parent scope (or the library fallbacks at the root).
694
731
 
695
- | Key | Library fallback | Meaning |
696
- | --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
697
- | `itemRoleDescription` | `'sortable'` | `aria-roledescription` of each item that can be lifted. An empty string drops the attribute. See [Role description](#role-description). |
698
- | `announceLift` | `'<label>, lifted. <index> of <total>.'` | Announcement when an item is lifted. `index` / `total` describe the source list. |
699
- | `announceMove` | `'<label>, moved to position <index> of <total>.'` | Announcement when the drop position changes. `index` / `total` describe the list under that position, which may be a connected list. |
700
- | `announceDrop` | `'<label>, dropped at position <index> of <total>.'` | Announcement on a committed drop. `index` / `total` describe the destination list. |
701
- | `announceCancel` | `'<label>, movement cancelled.'` | Announcement when a drag is cancelled. |
702
- | `autoScrollEdgeSize` | `50` | Distance in px from a scroll edge that arms auto-scroll during a pointer drag. See [Auto-scroll](#auto-scroll). |
703
- | `autoScrollMaxSpeed` | `16` | Maximum scroll distance in px per animation frame while auto-scrolling. |
704
- | `liftKey` | `Shift+Enter`, `Ctrl+Space` or `Cmd+Space` | Whether a keydown on a focused item lifts it into a keyboard reorder in `[forListboxReorder]`, `[forTreeNodeDrag]` and `[forTableRowReorder]` (grid mode). |
732
+ | Key | Library fallback | Meaning |
733
+ | --------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
734
+ | `itemRoleDescription` | `'sortable'` | `aria-roledescription` of each item that can be lifted. An empty string drops the attribute. See [Role description](#role-description). |
735
+ | `announceLift` | `'<label>, lifted. <index> of <total>.'` | Announcement when an item is lifted. `index` / `total` describe the source list. |
736
+ | `announceMove` | `'<label>, moved to position <index> of <total>.'` | Announcement when the drop position changes. `index` / `total` describe the list under that position, which may be a connected list: then the fallback is `'<label>, moved to <list>, position <index> of <total>.'`. |
737
+ | `announceDrop` | `'<label>, dropped at position <index> of <total>.'` | Announcement on a committed drop. `index` / `total` describe the destination list. Into a connected list the fallback is `'<label>, dropped in <list>, position <index> of <total>.'`. |
738
+ | `announceCancel` | `'<label>, movement cancelled.'` | Announcement when a drag is cancelled. |
739
+ | `autoScrollEdgeSize` | `50` | Distance in px from a scroll edge that arms auto-scroll during a pointer drag. See [Auto-scroll](#auto-scroll). |
740
+ | `autoScrollMaxSpeed` | `16` | Maximum scroll distance in px per animation frame while auto-scrolling. |
741
+ | `liftKey` | `Shift+Enter`, `Ctrl+Space` or `Cmd+Space` | Whether a keydown on a focused item lifts it into a keyboard reorder in `[forListboxReorder]`, `[forTreeNodeDrag]` and `[forTableRowReorder]` (grid mode). |
705
742
 
706
743
  `itemRoleDescription` is spoken by a screen reader, so translate it here. It accepts a string or a function returning one; a function can read a language signal, so the text follows a language the app sets or switches after bootstrap, as [Localizing default text](../shared/README.md#localizing-default-text) shows.
707
744
 
708
- The four announcers are builder functions whose return value is spoken through an ARIA live region; return the sentence in your language. `announceLift`, `announceMove` and `announceDrop` receive `(label, index, total)`, and `announceCancel` receives `(label)`. `label` is the dragged item's accessible text and `index` is the 1-based position being announced. `total` is the number of valid drop positions in the list the announcement describes, never a bare item count: the item count for a reorder inside one list, and one more than the target's item count for a transfer into a connected list, because the append gap past the last item is also a valid position. `index` therefore never exceeds `total`, and an empty transfer target announces `1 of 1`.
745
+ The four announcers are builder functions whose return value is spoken through an ARIA live region; return the sentence in your language. `announceLift`, `announceMove` and `announceDrop` receive `(label, index, total, context)`, and `announceCancel` receives `(label)`. `label` is the dragged item's name (see [Item names](#item-names)) and `index` is the 1-based position being announced. `total` is the number of valid drop positions in the list the announcement describes, never a bare item count: the item count for a reorder inside one list, and one more than the target's item count for a transfer into a connected list, because the append gap past the last item is also a valid position. `index` therefore never exceeds `total`, and an empty transfer target announces `1 of 1`. `context` is a `ForDragDropAnnouncementContext`: `list` is the accessible name of that list (`''` when it has no `aria-labelledby` or `aria-label`) and `transfer` is `true` when it is not the list the item was lifted from. The fallbacks name the list only on a transfer, and say "another list" when it has no name. A builder that ignores `context` can leave the parameter out.
709
746
 
710
747
  `liftKey` receives the `KeyboardEvent` and returns `true` when that key should lift the item. Shift+Enter is reserved by no operating system, while macOS and most IMEs claim Ctrl+Space / Cmd+Space before the page sees them. A keydown that belongs to an IME composition never lifts, whatever `liftKey` returns.
711
748
 
@@ -718,7 +755,10 @@ export const appConfig: ApplicationConfig = {
718
755
  provideForDragDropDefaults({
719
756
  itemRoleDescription: 'reordenable',
720
757
  announceLift: (label, index, total) => `${label}, levantado. ${index} de ${total}.`,
721
- announceMove: (label, index, total) => `${label}, movido a la posición ${index} de ${total}.`,
758
+ announceMove: (label, index, total, { list, transfer }) =>
759
+ transfer
760
+ ? `${label}, movido a ${list || 'otra lista'}, posición ${index} de ${total}.`
761
+ : `${label}, movido a la posición ${index} de ${total}.`,
722
762
  announceDrop: (label, index, total) =>
723
763
  `${label}, soltado en la posición ${index} de ${total}.`,
724
764
  announceCancel: (label) => `${label}, movimiento cancelado.`,
package/drawer/README.md CHANGED
@@ -180,7 +180,7 @@ this.#drawers.open(ConfirmDrawer, { data, side: 'bottom', class: 'my-drawer' });
180
180
  }
181
181
  ```
182
182
 
183
- **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; every key then applies, the scale and nested tunables included.
183
+ **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, and the overlay stops being modal at the same moment: its focus trap, inert siblings, scroll lock and Escape layer are released and focus returns. Only the DOM removal 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; every key then applies, the scale and nested tunables included.
184
184
 
185
185
  <!-- snippet: fragment -->
186
186
 
@@ -531,8 +531,9 @@ For a seamless release, transition **both** `translate` and your snap-position p
531
531
  - Dismissal and dragging are separate. With `swipeToDismiss` or `dismissible` set to `false`, a drawer with `snapPoints` still drags between them and stops at the lowest snap, and `(swipeEnd)` reports `willClose: false`; a drawer without `snapPoints` arms no drag at all.
532
532
  - `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.
533
533
  - `handleOnly: true` confines the gesture to a registered `[forDrawerHandle]`, leaving the rest of the surface free for content scroll.
534
- - 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.
535
- - 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.
534
+ - On touch the browser would otherwise claim the swipe as a scroll. While the drawer can arm the drag, the handle carries `touch-action: none`, and while the whole surface arms it (`handleOnly` off) 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.
535
+ - A surface that is itself the scroll container (`[forDrawer] { max-height: 85vh; overflow-y: auto }`) keeps touch scrolling on that axis while its content overflows it: the surface leaves that axis to the browser, so a touch drag on the content scrolls it instead of dragging the drawer. Add a `[forDrawerHandle]` to keep a touch swipe available; a mouse drag still swipes once the content is scrolled to its edge.
536
+ - Gestures whose press lands inside a scrollable element that hasn't reached its edge, the surface itself included, are NOT treated as swipes (the helper defers to the scroll). The edge is read in the scroller's own writing direction, with a 1 px tolerance for fractional scroll offsets.
536
537
  - **`prefers-reduced-motion: reduce`** disables the drag entirely, snap dragging included. Escape, backdrop, outside-pointer, and close button continue to work.
537
538
 
538
539
  ## Scale background
@@ -109,7 +109,7 @@ A settings-style dropdown built from the full menu vocabulary: `forMenuGroup` wi
109
109
  | `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` |
110
110
  | `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` |
111
111
  | `dismissible` | `input<boolean>` | When `false`, Escape and outside interactions don't close.<br>**Default:** `true` |
112
- | `returnFocus` | `input<boolean>` | When `true`, focus returns to the trigger on close.<br>**Default:** `true` |
112
+ | `returnFocus` | `input<boolean>` | When `true`, focus returns to the trigger on close, except after an outside or Tab close.<br>**Default:** `true` |
113
113
  | `ariaLabel` | `input<string \| null>` | Manual `aria-label` on `[forMenuContent]` if the trigger isn't a meaningful name.<br>**Default:** `null` |
114
114
  | `escapeKeyDown` | `output<VetoableNativeEvent<KeyboardEvent>>` | Output. Escape pressed while the menu is the topmost dismissible layer.<br>**Default:** — |
115
115
  | `pointerDownOutside` | `output<VetoableNativeEvent<PointerEvent>>` | Output. Pointer-down on a target outside content + trigger.<br>**Default:** — |