forty-cdk 0.41.1 → 0.43.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 (203) hide show
  1. package/button/README.md +5 -5
  2. package/calendar/README.md +33 -29
  3. package/carousel/README.md +9 -7
  4. package/checkbox/README.md +9 -9
  5. package/combobox/README.md +30 -20
  6. package/context-menu/README.md +1 -1
  7. package/date-adapter/README.md +1 -1
  8. package/date-field/README.md +3 -2
  9. package/date-picker/README.md +8 -8
  10. package/dialog/README.md +5 -4
  11. package/drag-drop/README.md +67 -22
  12. package/drawer/README.md +46 -43
  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 +118 -72
  22. package/fesm2022/forty-cdk-calendar.mjs.map +1 -1
  23. package/fesm2022/forty-cdk-carousel.mjs +48 -37
  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 +113 -87
  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 -145
  32. package/fesm2022/forty-cdk-core-anchored.mjs.map +1 -1
  33. package/fesm2022/forty-cdk-core-overlay.mjs +90 -41
  34. package/fesm2022/forty-cdk-core-overlay.mjs.map +1 -1
  35. package/fesm2022/forty-cdk-core.mjs +775 -197
  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 +55 -43
  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 +12 -10
  44. package/fesm2022/forty-cdk-defaults.mjs.map +1 -1
  45. package/fesm2022/forty-cdk-dialog.mjs +42 -38
  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 +111 -96
  49. package/fesm2022/forty-cdk-drag-drop.mjs.map +1 -1
  50. package/fesm2022/forty-cdk-drawer.mjs +122 -66
  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 +15 -12
  70. package/fesm2022/forty-cdk-meter.mjs.map +1 -1
  71. package/fesm2022/forty-cdk-navigation-menu.mjs +29 -28
  72. package/fesm2022/forty-cdk-navigation-menu.mjs.map +1 -1
  73. package/fesm2022/forty-cdk-number-input.mjs +14 -15
  74. package/fesm2022/forty-cdk-number-input.mjs.map +1 -1
  75. package/fesm2022/forty-cdk-otp-input.mjs +12 -8
  76. package/fesm2022/forty-cdk-otp-input.mjs.map +1 -1
  77. package/fesm2022/forty-cdk-pagination.mjs +16 -15
  78. package/fesm2022/forty-cdk-pagination.mjs.map +1 -1
  79. package/fesm2022/forty-cdk-pane-resizer.mjs +8 -7
  80. package/fesm2022/forty-cdk-pane-resizer.mjs.map +1 -1
  81. package/fesm2022/forty-cdk-popover.mjs +37 -40
  82. package/fesm2022/forty-cdk-popover.mjs.map +1 -1
  83. package/fesm2022/forty-cdk-progress.mjs +7 -7
  84. package/fesm2022/forty-cdk-progress.mjs.map +1 -1
  85. package/fesm2022/forty-cdk-radio-group.mjs +46 -17
  86. package/fesm2022/forty-cdk-radio-group.mjs.map +1 -1
  87. package/fesm2022/forty-cdk-scroll-area.mjs +70 -46
  88. package/fesm2022/forty-cdk-scroll-area.mjs.map +1 -1
  89. package/fesm2022/forty-cdk-search.mjs +9 -11
  90. package/fesm2022/forty-cdk-search.mjs.map +1 -1
  91. package/fesm2022/forty-cdk-select.mjs +134 -114
  92. package/fesm2022/forty-cdk-select.mjs.map +1 -1
  93. package/fesm2022/forty-cdk-separator.mjs +3 -3
  94. package/fesm2022/forty-cdk-slider.mjs +28 -22
  95. package/fesm2022/forty-cdk-slider.mjs.map +1 -1
  96. package/fesm2022/forty-cdk-stepper.mjs +97 -63
  97. package/fesm2022/forty-cdk-stepper.mjs.map +1 -1
  98. package/fesm2022/forty-cdk-switch.mjs +6 -4
  99. package/fesm2022/forty-cdk-switch.mjs.map +1 -1
  100. package/fesm2022/forty-cdk-table-virtualization.mjs +79 -10
  101. package/fesm2022/forty-cdk-table-virtualization.mjs.map +1 -1
  102. package/fesm2022/forty-cdk-table.mjs +197 -149
  103. package/fesm2022/forty-cdk-table.mjs.map +1 -1
  104. package/fesm2022/forty-cdk-tabs.mjs +21 -16
  105. package/fesm2022/forty-cdk-tabs.mjs.map +1 -1
  106. package/fesm2022/forty-cdk-testing.mjs +1 -0
  107. package/fesm2022/forty-cdk-testing.mjs.map +1 -1
  108. package/fesm2022/forty-cdk-time-field.mjs +55 -43
  109. package/fesm2022/forty-cdk-time-field.mjs.map +1 -1
  110. package/fesm2022/forty-cdk-time-picker.mjs +116 -71
  111. package/fesm2022/forty-cdk-time-picker.mjs.map +1 -1
  112. package/fesm2022/forty-cdk-toast.mjs +64 -34
  113. package/fesm2022/forty-cdk-toast.mjs.map +1 -1
  114. package/fesm2022/forty-cdk-toggle.mjs +50 -21
  115. package/fesm2022/forty-cdk-toggle.mjs.map +1 -1
  116. package/fesm2022/forty-cdk-toolbar.mjs +46 -51
  117. package/fesm2022/forty-cdk-toolbar.mjs.map +1 -1
  118. package/fesm2022/forty-cdk-tooltip.mjs +70 -30
  119. package/fesm2022/forty-cdk-tooltip.mjs.map +1 -1
  120. package/fesm2022/forty-cdk-tree.mjs +339 -138
  121. package/fesm2022/forty-cdk-tree.mjs.map +1 -1
  122. package/fesm2022/forty-cdk-virtual-reorder.mjs +78 -64
  123. package/fesm2022/forty-cdk-virtual-reorder.mjs.map +1 -1
  124. package/fesm2022/forty-cdk-virtualization.mjs +55 -14
  125. package/fesm2022/forty-cdk-virtualization.mjs.map +1 -1
  126. package/field/README.md +6 -13
  127. package/hover-card/README.md +2 -0
  128. package/input/README.md +28 -27
  129. package/listbox/README.md +46 -41
  130. package/menu/README.md +24 -22
  131. package/menubar/README.md +19 -19
  132. package/meter/README.md +11 -11
  133. package/number-input/README.md +6 -5
  134. package/otp-input/README.md +8 -7
  135. package/package.json +1 -1
  136. package/pagination/README.md +9 -9
  137. package/progress/README.md +2 -2
  138. package/radio-group/README.md +13 -12
  139. package/scroll-area/README.md +8 -3
  140. package/search/README.md +7 -5
  141. package/select/README.md +11 -11
  142. package/slider/README.md +3 -1
  143. package/stepper/README.md +11 -7
  144. package/switch/README.md +11 -11
  145. package/table/README.md +34 -34
  146. package/tabs/README.md +2 -2
  147. package/time-field/README.md +3 -2
  148. package/time-picker/README.md +49 -46
  149. package/toast/README.md +29 -11
  150. package/toggle/README.md +34 -33
  151. package/toolbar/README.md +5 -5
  152. package/tooltip/README.md +1 -0
  153. package/tree/README.md +59 -40
  154. package/types/forty-cdk-accordion.d.ts +6 -35
  155. package/types/forty-cdk-avatar.d.ts +0 -37
  156. package/types/forty-cdk-button.d.ts +4 -2
  157. package/types/forty-cdk-calendar.d.ts +39 -60
  158. package/types/forty-cdk-carousel.d.ts +11 -82
  159. package/types/forty-cdk-combobox.d.ts +28 -391
  160. package/types/forty-cdk-context-menu.d.ts +12 -40
  161. package/types/forty-cdk-core-anchored.d.ts +233 -247
  162. package/types/forty-cdk-core-overlay.d.ts +40 -40
  163. package/types/forty-cdk-core.d.ts +745 -586
  164. package/types/forty-cdk-date-adapter.d.ts +5 -0
  165. package/types/forty-cdk-date-field.d.ts +16 -41
  166. package/types/forty-cdk-date-picker.d.ts +35 -70
  167. package/types/forty-cdk-defaults.d.ts +41 -296
  168. package/types/forty-cdk-dialog.d.ts +24 -22
  169. package/types/forty-cdk-disclosure.d.ts +0 -5
  170. package/types/forty-cdk-drag-drop.d.ts +20 -24
  171. package/types/forty-cdk-drawer.d.ts +53 -52
  172. package/types/forty-cdk-dropdown-menu.d.ts +14 -10
  173. package/types/forty-cdk-field.d.ts +9 -9
  174. package/types/forty-cdk-file-upload.d.ts +0 -5
  175. package/types/forty-cdk-hover-card.d.ts +14 -50
  176. package/types/forty-cdk-listbox.d.ts +70 -171
  177. package/types/forty-cdk-menu.d.ts +55 -21
  178. package/types/forty-cdk-menubar.d.ts +21 -13
  179. package/types/forty-cdk-meter.d.ts +12 -14
  180. package/types/forty-cdk-navigation-menu.d.ts +10 -104
  181. package/types/forty-cdk-otp-input.d.ts +4 -18
  182. package/types/forty-cdk-pagination.d.ts +6 -24
  183. package/types/forty-cdk-pane-resizer.d.ts +6 -5
  184. package/types/forty-cdk-popover.d.ts +9 -45
  185. package/types/forty-cdk-progress.d.ts +3 -8
  186. package/types/forty-cdk-radio-group.d.ts +24 -36
  187. package/types/forty-cdk-scroll-area.d.ts +21 -44
  188. package/types/forty-cdk-select.d.ts +48 -375
  189. package/types/forty-cdk-slider.d.ts +16 -17
  190. package/types/forty-cdk-stepper.d.ts +29 -50
  191. package/types/forty-cdk-table.d.ts +22 -339
  192. package/types/forty-cdk-tabs.d.ts +6 -42
  193. package/types/forty-cdk-time-field.d.ts +16 -41
  194. package/types/forty-cdk-time-picker.d.ts +21 -113
  195. package/types/forty-cdk-toast.d.ts +10 -127
  196. package/types/forty-cdk-toggle.d.ts +16 -3
  197. package/types/forty-cdk-toolbar.d.ts +10 -11
  198. package/types/forty-cdk-tooltip.d.ts +19 -31
  199. package/types/forty-cdk-tree.d.ts +62 -267
  200. package/types/forty-cdk-virtual-reorder.d.ts +9 -5
  201. package/types/forty-cdk-virtualization.d.ts +11 -33
  202. package/virtual-reorder/README.md +9 -2
  203. package/virtualization/README.md +21 -19
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
 
@@ -290,7 +290,9 @@ Set `selectionMode="range"` and bind `[(range)]` to get date-range selection. In
290
290
  }
291
291
  ```
292
292
 
293
- **`aria-selected`** in range mode is `"true"` across every committed-range cell (inclusive), and the grid carries `aria-multiselectable="true"`. While a new anchor is pending, `aria-selected` is `"false"` everywhere, but `range` keeps the previously committed range until the second click replaces it.
293
+ **`aria-selected`** in range mode is `"true"` across every committed-range cell (inclusive), and the grid carries `aria-multiselectable="true"`. While a new anchor is pending, the committed cells keep `aria-selected="true"`, matching `range`, which holds the previously committed range until the second click replaces it, and the anchor cell is selected too. The preview band is never selected; it is exposed only through `data-range-preview`.
294
+
295
+ **Announcements.** Setting the anchor and committing a range are each announced politely, with the dates formatted as day, month and year in the calendar's `locale`: `"Start date June 20, 2026. Choose the end date."` and `"Selected June 20, 2026 to June 24, 2026."`. A click the length limits reject announces nothing. Both strings are localizable through `provideForCalendarDefaults` (see [Scoped defaults](#scoped-defaults)).
294
296
 
295
297
  **Scope.** Range mode is day-granular only: `granularity` / time is orthogonal and not supported alongside it.
296
298
 
@@ -354,7 +356,7 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
354
356
  [maxYear]="2100"
355
357
  >
356
358
  @for (opt of y.years(); track opt.value) {
357
- <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.value }}</option>
359
+ <option [value]="opt.value" [disabled]="opt.disabled">{{ opt.label }}</option>
358
360
  }
359
361
  </select>
360
362
  <button forCalendarNextButton [ariaLabel]="'Next month'">
@@ -385,11 +387,11 @@ The recommended path is `[forCalendarMonthSelect]` and `[forCalendarYearSelect]`
385
387
 
386
388
  #### `ForCalendarYearSelect` API
387
389
 
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]`. |
390
+ | API | Description |
391
+ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
392
+ | `minYear` | `input<number \| null>`: the lowest listed year. Defaults to `currentYear - 100` when `null`. |
393
+ | `maxYear` | `input<number \| null>`: the highest listed year. Defaults to `currentYear + 10` when `null`. |
394
+ | `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
395
 
394
396
  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
397
 
@@ -403,7 +405,7 @@ The lower-level hooks (`visibleMonthNumber()`, `visibleYear()`, `monthOptions()`
403
405
 
404
406
  `ForCalendar` supports two additional views (**month grid** and **year grid**) so users can jump quickly to a different month or year without paging one at a time. All three views share a single `[(view)]` model and the same `focusedDate` cursor.
405
407
 
406
- The heading's `label()` follows the active view, with the same text as the view trigger: the month and year in day view, the year in month view, the block of years in year view. Every grid is named by the heading, so each one is named after the period it shows. A keyboard move or a prev / next press that changes that period announces it. Drilling down changes no value, so a `readonly` calendar still drills from a year to its months and from a month to its days.
408
+ The heading's `label()` follows the active view, with the same text as the view trigger: the month and year in day view, the year in month view, the block of years in year view. Every grid is named by the heading, so each one is named after the period it shows. A keyboard move or a prev / next press that changes that period announces it. Drilling down changes no value, so a `readonly` calendar still drills from a year to its months and from a month to its days. The view trigger and a drill-down move DOM focus to the active cell of the new grid; a consumer write to `[(view)]` switches the grid and leaves focus where it is.
407
409
 
408
410
  ### Pieces
409
411
 
@@ -417,10 +419,10 @@ The heading's `label()` follows the active view, with the same text as the view
417
419
 
418
420
  ### `view` model — `ForCalendar`
419
421
 
420
- | API | Type | Description |
421
- | --------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
422
- | `view` | `model<CalendarView>` (`'day' \| 'month' \| 'year'`) | Active view. Default `'day'`. `[(view)]` for two-way binding or read `cal.view()`. |
423
- | `yearBlockSize` | `input<number>` | Years per year-grid page (must be a multiple of 3). Default `12`. |
422
+ | API | Type | Description |
423
+ | --------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
424
+ | `view` | `model<CalendarView>` (`'day' \| 'month' \| 'year'`) | Active view. Default `'day'`. `[(view)]` for two-way binding or read `cal.view()`. A consumer write leaves DOM focus where it is. |
425
+ | `yearBlockSize` | `input<number>` | Years per year-grid page (must be a multiple of 3). Default `12`. |
424
426
 
425
427
  ### Usage
426
428
 
@@ -493,7 +495,7 @@ The heading's `label()` follows the active view, with the same text as the view
493
495
  @for (row of yg.rows(); track row.key) {
494
496
  <tr>
495
497
  @for (y of row.years; track y.value) {
496
- <td forCalendarYearCell [year]="y.value">{{ y.value }}</td>
498
+ <td forCalendarYearCell [year]="y.value">{{ y.label }}</td>
497
499
  }
498
500
  </tr>
499
501
  }
@@ -562,6 +564,8 @@ providers: [
562
564
 
563
565
  `outsideMonthLabel` builds the `aria-label` of a padding day outside the visible month from its formatted full date (default `"<date> (outside month)"`), so assistive tech can tell it apart from the month on screen. A calendar bound to its own `[dateLabel]` formatter ignores it.
564
566
 
567
+ `rangeStartAnnouncement` and `rangeSelectedAnnouncement` build the polite announcements a range calendar makes when it sets its anchor and when it commits a range, from the dates already formatted as day, month and year (defaults `"Start date <start>. Choose the end date."` and `"Selected <start> to <end>."`).
568
+
565
569
  ## Keyboard
566
570
 
567
571
  LTR (horizontal arrows mirror under `dir="rtl"`):
@@ -182,7 +182,7 @@ export class CarouselDefaultExample {
182
182
 
183
183
  ### Multiple slides per view
184
184
 
185
- Set `slidesPerView` above `1` to show several slides at once. Each slide is `flex: 0 0 calc(100% / var(--for-carousel-slides-per-view))`; `loop` wraps once the last visible set is reached.
185
+ Set `slidesPerView` above `1` to show several slides at once. Each slide is `flex: 0 0 calc(100% / var(--for-carousel-slides-per-view))`. Navigation still moves one slide at a time, with one indicator per slide, so the views past the last full set would show empty space. This example sets `containScroll`, which holds the track once the last full set is in view; under `loop` the clamp is off and the carousel wraps only after the last slide, so pair `slidesPerView` with `containScroll` rather than `loop` when every view has to be full. See [Contain scroll](#contain-scroll).
186
186
 
187
187
  ### Autoplay with pause control
188
188
 
@@ -346,9 +346,9 @@ so compose it **without** the `-1` factor the consumer may apply to
346
346
 
347
347
  ### Reduced motion
348
348
 
349
- Under `prefers-reduced-motion: reduce` the directive does **not** publish
350
- `--for-carousel-swipe-movement-x` / `-y` (no live track motion). The gesture still snaps
351
- `activeIndex` on release. Only the continuous live offset is suppressed.
349
+ Under `prefers-reduced-motion: reduce` the gesture stays and the motion goes, as on every swipe
350
+ surface in the library: the directive does **not** publish `--for-carousel-swipe-movement-x` / `-y`
351
+ (no live track motion), and the gesture still snaps `activeIndex` on release.
352
352
 
353
353
  ### Cross-axis / touch
354
354
 
@@ -454,8 +454,9 @@ viewport's trailing edge:
454
454
 
455
455
  Every slide still has its own indicator; trailing indicators that would map to the
456
456
  same clamped view simply share the same visual position. The clamp has no effect
457
- when `loop` is enabled (the entire range is valid when wrapping) or when
458
- `slidesPerView` is `1` (a single-view carousel never overscrolls).
457
+ when `slidesPerView` is `1` (a single-view carousel never overscrolls) or when
458
+ `loop` is enabled: a looping carousel with `slidesPerView > 1` overscrolls into
459
+ the same empty space and wraps only after the last slide.
459
460
 
460
461
  ### `ForCarouselDrag` inputs
461
462
 
@@ -474,7 +475,8 @@ Reflected on the `[forCarouselViewport]` host this directive is applied to:
474
475
  Keyboard navigation lives on the indicator group. Only the current
475
476
  indicator is in the tab order, including after prev / next, autoplay or a drag
476
477
  moved the slide. Arrow keys move focus and activate the target slide
477
- automatically.
478
+ automatically. Removing the focused indicator moves focus to the indicator that
479
+ then holds the Tab stop, so focus never falls to `<body>`.
478
480
 
479
481
  | Key | Action |
480
482
  | -------------------------- | --------------------------------------------------------------------- |
@@ -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:** `false` |
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:** `false` |
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:** `false` |
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 FieldValidationError[]>` | 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
  | --------------- | ------------------------------------------- |
@@ -338,7 +338,10 @@ Add two parts:
338
338
 
339
339
  ```html
340
340
  <div forCombobox #combobox="forCombobox" [(value)]="value" [(query)]="query" [(open)]="open">
341
- <button forComboboxTrigger>{{ selectedLabel() }}</button>
341
+ <span id="country-label">Country</span>
342
+ <button forComboboxTrigger aria-labelledby="country-label country-value">
343
+ <span id="country-value">{{ selectedLabel() }}</span>
344
+ </button>
342
345
  @if (combobox.open()) {
343
346
  <div forComboboxContent>
344
347
  <input forComboboxInput placeholder="Search…" />
@@ -355,7 +358,7 @@ Add two parts:
355
358
 
356
359
  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
360
 
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).
361
+ **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
362
 
360
363
  **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
364
 
@@ -378,7 +381,10 @@ Why the list part is required, not optional: a `role="listbox"` may only own `op
378
381
  </div>
379
382
 
380
383
  <ng-template #trig let-root="root">
381
- <button [forComboboxTrigger]="root">{{ selectedLabel() }}</button>
384
+ <span id="country-label">Country</span>
385
+ <button [forComboboxTrigger]="root" aria-labelledby="country-label country-value">
386
+ <span id="country-value">{{ selectedLabel() }}</span>
387
+ </button>
382
388
  </ng-template>
383
389
  ```
384
390
 
@@ -564,6 +570,8 @@ Chips are intentionally **out of the Tab cycle**: Tab from outside lands on the
564
570
  | **Backspace / Delete** | Remove this chip + focus the previous chip (or the input if it was the only / last chip). |
565
571
  | **Escape** | Return focus to the input. |
566
572
 
573
+ On a `readonly` combobox the chips keep the arrow keys and Escape, and Backspace / Delete remove nothing.
574
+
567
575
  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
576
 
569
577
  `[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 +647,7 @@ The two anatomies have different focus models:
639
647
  | `(autoFocusOnOpen)` | Just before focus enters the input on open. | Focus stays on the trigger. |
640
648
  | `(autoFocusOnClose)` | Just before focus returns to the trigger. | Focus stays where it is. |
641
649
 
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).
650
+ 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
651
 
644
652
  ## Object values
645
653
 
@@ -844,7 +852,9 @@ Static and `@for`-rendered options share the same registry, navigation order (DO
844
852
  </div>
845
853
  ```
846
854
 
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.
855
+ A Signal Forms reset (`form().reset()` or `form.country().reset(value)`) rewrites `query` too, so the input never keeps text the reset value does not hold. In the editable single-select anatomy with `commitOnSelect`, the input shows the label of the selection the reset leaves, and it is empty when that selection is. In multi mode, in the picker anatomy and without `commitOnSelect`, the reset empties it.
856
+
857
+ 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
858
 
849
859
  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
860
 
@@ -852,21 +862,21 @@ A single-select field is modeled as the same `readonly T[]`, kept at length ≤
852
862
 
853
863
  Focus stays in the input throughout: arrow keys move the listbox's _active descendant_ (the highlighted option), not DOM focus.
854
864
 
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. |
865
+ | Key | Action |
866
+ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
867
+ | **ArrowDown** | Open listbox + move activedescendant to next enabled option (or first when none; the selection under `openHighlight="selected"`). |
868
+ | **ArrowUp** | Open listbox + move activedescendant to previous enabled option (or last when none; the selection under `openHighlight="selected"`). |
869
+ | **Home** _(open)_ | Move activedescendant to first enabled option. |
870
+ | **End** _(open)_ | Move activedescendant to last enabled option. |
871
+ | **PageUp** _(open)_ | Move activedescendant to first enabled option. |
872
+ | **PageDown** _(open)_ | Move activedescendant to last enabled option. |
873
+ | **Enter** _(open)_ | Activate the activedescendant (single: replace + close; multi: toggle + stay open). |
874
+ | **Escape** _(open)_ | Close the listbox. Focus stays in the input. |
875
+ | **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. |
876
+ | **Tab / Shift+Tab** _(open, action present)_ | Move focus around the input↔actions ring without dismissing (see [Action items](#action-items)). |
877
+ | **Backspace** _(empty input, multi only)_ | Focus the last chip; a second Backspace there removes it. |
878
+ | **ArrowLeft / ArrowRight** | Move the caret, accepting a pending inline completion. |
879
+ | Printable keys | Update `query`. With `'inline'` / `'both'` autocomplete, complete the rest of the first match into the input as selected text. |
870
880
 
871
881
  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
882
 
@@ -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
 
@@ -345,6 +345,7 @@ Composes the [WAI-ARIA Spinbutton pattern](https://www.w3.org/WAI/ARIA/apg/patte
345
345
  - **Literals are `aria-hidden`** and never focusable, so assistive tech reads only the spinbutton segments.
346
346
  - **Boolean `data-*`** on each segment, present when true and absent when false: `data-highlighted` (the roving tab stop, kept after blur), `data-placeholder` (empty), `data-disabled`, `data-readonly`.
347
347
  - **`aria-readonly` belongs on the segments, not the group.** WAI-ARIA supports it on `role="spinbutton"` but not on `role="group"`, so each segment carries `aria-readonly="true"` while the group reflects the `data-readonly` styling hook only.
348
+ - **`aria-busy="true"` on the group while `pending`**, beside the `data-pending` hook, so an async validator in flight is announced as it is on the other form controls. A picker in the field anatomy passes its own `pending` to the field it adopts, so the composite carries it once, on the group.
348
349
  - **On-screen keyboards work.** A segment of a field that is neither disabled nor read-only is a `contenteditable="plaintext-only"` editing host with `inputmode="numeric"`, so tapping it on a touch device opens the numeric keypad (the AM/PM segment opens the text keyboard). What the keyboard or an input method types goes through the [Keyboard](#keyboard) map above and is never inserted into the segment, which keeps rendering `{{ seg.text }}`.
349
350
 
350
351
  ## Styling
@@ -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
@@ -225,8 +225,8 @@ import {
225
225
  FOR_DIALOG_CONTRACT,
226
226
  type ForDialogContract,
227
227
  ForDialogManager,
228
- ForDialogRef,
229
228
  injectDialogData,
229
+ injectDialogRef,
230
230
  } from 'forty-cdk/dialog';
231
231
 
232
232
  interface ConfirmData {
@@ -245,7 +245,7 @@ type ConfirmResult = 'confirm' | 'cancel';
245
245
  class ConfirmDialog {
246
246
  declare readonly [FOR_DIALOG_CONTRACT]: ForDialogContract<ConfirmData, ConfirmResult>;
247
247
  readonly data = injectDialogData<ConfirmDialog>();
248
- readonly ref = inject(ForDialogRef<ConfirmResult>);
248
+ readonly ref = injectDialogRef<ConfirmDialog>();
249
249
  }
250
250
 
251
251
  @Component({
@@ -265,7 +265,7 @@ export class DemoHost {
265
265
  }
266
266
  ```
267
267
 
268
- **Typing the payload and the result.** The `[FOR_DIALOG_CONTRACT]` member states, once, the data a dialog component reads and the result it closes with. Declare it with `declare` and no initializer, and keep it public. `open()` then infers both from the component: a `data` of any other shape fails to compile, and the returned ref is a `ForDialogRef<ConfirmResult>`. `injectDialogData<ConfirmDialog>()` reads the payload at the type the contract names, so the component and every caller share one definition. A component without the member keeps an unchecked `data` and an `unknown` result, and `injectDialogData<T>()` with a plain type still types the payload as `T`. Explicit type arguments (`open<ConfirmDialog, ConfirmResult>`) override what the contract supplies.
268
+ **Typing the payload and the result.** The `[FOR_DIALOG_CONTRACT]` member states, once, the data a dialog component reads and the result it closes with. Declare it with `declare` and no initializer, and keep it public. `open()` then infers both from the component: a `data` of any other shape fails to compile, and the returned ref is a `ForDialogRef<ConfirmResult>`. `injectDialogData<ConfirmDialog>()` reads the payload at the type the contract names, and `injectDialogRef<ConfirmDialog>()` hands the component its own ref typed with the declared result, so `ref.close(42)` fails to compile and the component and every caller share one definition. A `[forDialogClose]` button's `[closeWith]` is not checked against the contract, so close through that ref wherever the result type matters. A component without the member keeps an unchecked `data` and an `unknown` result, and `injectDialogData<T>()` with a plain type still types the payload as `T`. Explicit type arguments (`open<ConfirmDialog, ConfirmResult>`) override what the contract supplies.
269
269
 
270
270
  `injectDialogData()` returns `null` too: the manager provides `null` when `open()` is called without `data`, so guard (`data?.message`) before dereferencing the payload.
271
271
 
@@ -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
 
@@ -332,6 +332,7 @@ class ScopedHost {
332
332
  | `ForDialogManager` | Injectable. `open(component, config?)` returns a `ForDialogRef<R>`. `closeAll(result?)` closes every open dialog, topmost first, with reason `'programmatic'`; exit animations still play and focus ends where the bottom dialog returns it. `openCount` is a `Signal<number>` of the dialogs still open, counting a closed one until its exit animation finishes. |
333
333
  | `ForDialogRef<R>` | `close(result?)`, `closed: Promise<{ reason: ForDialogCloseReason; result: R \| undefined }>`, `result: Signal<R \| undefined>`, `isClosed: Signal<boolean>`. |
334
334
  | `FOR_DIALOG_DATA` | Token for the `data` payload. Inject in the opened component. |
335
+ | `injectDialogRef<T>()` | Typed accessor for the opened component's own `ForDialogRef`: `ForDialogRef<R>` for the result `R` the contract names when `T` is a component declaring `FOR_DIALOG_CONTRACT`, else `ForDialogRef<T>`. |
335
336
  | `injectDialogData<T>()` | Typed accessor for `FOR_DIALOG_DATA`. Returns `T \| null` (`null` when `open()` got no `data`), or the data type the contract names when `T` is a component declaring `FOR_DIALOG_CONTRACT`. |
336
337
  | `FOR_DIALOG_CONTRACT` | Key of the member a dialog component declares as `ForDialogContract<D, R>` so `open()` checks `data` against `D` and returns a `ForDialogRef<R>`. `ForDialogDataOf<C>` / `ForDialogResultOf<C>` read the two types off a component. |
337
338