forty-cdk 0.12.0 → 0.13.0

package/combobox/README.md

@@ -36,6 +36,21 @@ The editable (default) anatomy — an `<input>` that filters a portaled listbox
 </div>
 ```
 
+**Editable + list (no trigger).** Wrapping the options in a `[forComboboxList]` without adding a `[forComboboxTrigger]` is a supported shape, and the a11y-clean way to add non-option pieces (`[forComboboxEmpty]`, `[forComboboxStatus]`, `[forComboboxAction]`) to the editable anatomy. Because content carries `role="listbox"` (which may only own `option` / `group` children), moving the options into `[forComboboxList]` makes those pieces siblings of the listbox instead of invalid listbox children — content becomes role-less and the list owns the listbox role. The role split keys off `hasList`, the focus model off `trigger()`, so focus still stays on the input the whole time:
+
+```html
+<div forComboboxContent>
+  <div forComboboxList>
+    <div forComboboxOption [value]="item.id" [label]="item.label">{{ item.label }}</div>
+  </div>
+  <div forComboboxEmpty>No matches.</div>
+</div>
+```
+
+A `[forComboboxAction]` **requires** this shape — see [Action items](#action-items).
+
+> **Editable-anatomy caveat.** For the common case of options plus only a `[forComboboxEmpty]` / `[forComboboxStatus]` message (the bare anatomy above, no `[forComboboxList]`), the message sits directly inside `[forComboboxContent]`. This is still supported and does not throw, but it leaves the `role="status"` message as an owned child of `role="listbox"`, a minor `aria-required-owned` compromise; wrap the options in a `[forComboboxList]` (the "editable + list" shape) when you want the strictly-clean tree.
+
 The picker anatomy adds a `[forComboboxTrigger]` `<button>` showing the committed selection, with the search input and a `[forComboboxList]` (`role="listbox"`) nested inside the popup — see [Picker anatomy](#picker-anatomy). Multi mode wraps the chips + input in `[forComboboxChips]` — see [Multi mode](#multi-mode). Optional `[forComboboxAnchor]`, `[forComboboxStatus]`, `[forComboboxGroup]` / `[forComboboxGroupLabel]`, and `[forComboboxSeparator]` pieces are covered in their own sections below.
 
 ## Examples
@@ -204,15 +219,24 @@ A combobox popup often needs an entry that is an **action**, not a value —
 `role="button"` actions, not `role="option"` selections, so `[forComboboxAction]`
 renders one that stays out of the option/value collection entirely.
 
+`[forComboboxAction]` **requires a `[forComboboxList]`**: content carries
+`role="listbox"` in the editable anatomy, so a `role="button"` placed directly
+inside it would be an invalid listbox child (`aria-required-owned`). Wrap the
+options in a `[forComboboxList]` so the action becomes a sibling of the listbox.
+An action rendered without a `[forComboboxList]` throws `[forty-cdk/combobox]` at
+runtime. This is the "editable + list" shape (no `[forComboboxTrigger]` needed).
+
 ```html
 <div forCombobox #combobox="forCombobox" [(query)]="query" [(value)]="value">
   <input forComboboxInput placeholder="Search…" />
   @if (combobox.open()) {
   <div forComboboxContent>
     <button forComboboxAction (action)="createNew(query())">Create "{{ query() }}"</button>
-    @for (it of filtered; track it.id) {
-    <div forComboboxOption [value]="it.id" [label]="it.label">{{ it.label }}</div>
-    }
+    <div forComboboxList>
+      @for (it of filtered; track it.id) {
+      <div forComboboxOption [value]="it.id" [label]="it.label">{{ it.label }}</div>
+      }
+    </div>
   </div>
   }
 </div>
@@ -249,9 +273,9 @@ returns focus to the input (editable anatomy) or the `[forComboboxTrigger]`
 only. With no action registered, Tab keeps its default "close and let Tab flow on"
 behaviour, so existing comboboxes are unchanged.
 
-Actions live inside `[forComboboxContent]` (beside `[forComboboxList]` in the
-picker anatomy), so they are naturally "inside" the outside-pointer / outside-focus
-dismissal checks, exactly like the input.
+Actions live inside `[forComboboxContent]` and beside `[forComboboxList]` (never
+inside it, in either anatomy), so they are naturally "inside" the outside-pointer /
+outside-focus dismissal checks, exactly like the input.
 
 ### API
 
@@ -382,6 +406,8 @@ The `autocompleteMode` input mirrors the WAI-ARIA `aria-autocomplete` property:
 
 Inline completion preserves the user's typed prefix as unselected and selects the appended remainder, so the next keystroke replaces the selection (matching native browser autofill behavior). Backspace deletes the selection without re-completing, so the user can always shorten the query.
 
+> **Pure `'inline'` needs a warm cache.** `'inline'` never opens the popup (per APG — `aria-autocomplete="inline"` has no listbox), so in the default `@if (open())` anatomy no `[forComboboxOption]` ever renders and the label cache starts cold. A first keystroke into a combobox that has never been opened completes against nothing; inline completion only works once the options have rendered at least once (the user opened the popup via ArrowDown or `[openOnFocus]`, warming the cache). If completion must work from the very first keystroke, use `'both'` (which opens the popup) or keep the options mounted rather than gating them behind `@if (open())`.
+
 ## Dismiss events
 
 Each dismiss reason emits a vetoable event from `[forCombobox]` — call `preventDefault()` on the event to keep the listbox open.
@@ -585,6 +611,7 @@ Implements the [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patte
 - `[forComboboxSeparator]` is decorative and never registers with the listbox's option collection — keyboard navigation skips it automatically.
 - `[forComboboxGroup]` is purely advisory grouping — options inside still register flatly with the root, so navigation flows through groups without interruption.
 - `[forComboboxEmpty]` carries `role="status"` + `aria-live="polite"` so the empty-state message is announced when filtering removes all matches.
+- Non-option pieces (`[forComboboxAction]`, and ideally `[forComboboxEmpty]` / `[forComboboxStatus]`) belong inside `[forComboboxContent]` but **outside** `[forComboboxList]` — `role="listbox"` may only own `option` / `group` children (`aria-required-owned-elements`). Wrapping the options in a `[forComboboxList]` (the "editable + list" shape) makes those pieces siblings of the listbox. `[forComboboxAction]` **requires** a `[forComboboxList]` and throws `[forty-cdk/combobox]` without one; `[forComboboxEmpty]` / `[forComboboxStatus]` stay lenient in the bare editable anatomy (documented compromise) — see the [editable-anatomy caveat](#anatomy).
 - The input element is exempt from the listbox's outside-pointer dismissal layer, so a click on the input while the listbox is open routes through `(click)` (toggle / focus open) instead of double-firing as an outside dismissal.
 
 ## Styling

package/date-field/README.md

@@ -146,7 +146,7 @@ Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled
 | `[forDateFieldSegment]` | `data-disabled`    | present \| absent |
 | `[forDateFieldSegment]` | `data-readonly`    | present \| absent |
 
-`data-empty` marks the whole field while any segment is still unfilled (the value is `null`); `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives. `[forDateFieldLiteral]` carries no data-\* attributes (it is `aria-hidden` and out of the tab order).
+`data-empty` marks the field only while **every** editable segment is empty (nothing has been entered); a partially-typed field is **not** empty. `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives. `[forDateFieldLiteral]` carries no data-\* attributes (it is `aria-hidden` and out of the tab order).
 
 ## Date-time field
 
@@ -192,13 +192,14 @@ providers: [
 
 Key behavior applies per segment. Horizontal arrows mirror under `dir="rtl"`.
 
-| Key                        | Behavior                                                                 |
-| -------------------------- | ------------------------------------------------------------------------ |
-| **0–9**                    | Type the value; auto-advances to the next segment when full.             |
-| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today. |
-| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                           |
-| **Home / End**             | Jump to the segment minimum / maximum.                                   |
-| **Backspace / Delete**     | Clear the segment (the value becomes `null` until refilled).             |
+| Key                        | Behavior                                                                                |
+| -------------------------- | --------------------------------------------------------------------------------------- |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.                            |
+| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today.                |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                                          |
+| **Home / End**             | Jump to the segment minimum / maximum.                                                  |
+| **Backspace**              | Delete the last entered digit; the value becomes `null` when the last digit is removed. |
+| **Delete**                 | Clear the whole segment (the value becomes `null` until refilled).                      |
 
 The day clamps to the current month's length (e.g. 31 → 28 in February), and a composed value is clamped into `[minDate, maxDate]`.
 

package/date-range-field/README.md

@@ -189,7 +189,7 @@ Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled
 | `[forDateRangeFieldSegment]` | `data-disabled`    | present \| absent |
 | `[forDateRangeFieldSegment]` | `data-readonly`    | present \| absent |
 
-`data-empty` marks the whole field while the range is `null` (either endpoint unfilled, or the two out of order); `data-range-error` marks the specific case of two complete but out-of-order endpoints; `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives.
+`data-empty` marks the field only while **both** endpoints are entirely empty; a partially-filled or complete-but-disordered range is **not** empty (`data-range-error` covers the disorder). `data-range-error` marks the specific case of two complete but out-of-order endpoints; `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives.
 
 ## Ordering
 
@@ -222,13 +222,14 @@ providers: [
 
 Key behavior applies per segment. Each endpoint is its own tab stop, so `Tab` moves from the start group to the end group to the next control; arrows move between segments **within** an endpoint. Horizontal arrows mirror under `dir="rtl"`.
 
-| Key                        | Behavior                                                                 |
-| -------------------------- | ------------------------------------------------------------------------ |
-| **0–9**                    | Type the value; auto-advances to the next segment when full.             |
-| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today. |
-| **ArrowLeft / ArrowRight** | Move to the previous / next segment in the same endpoint (no wrap).      |
-| **Home / End**             | Jump to the segment minimum / maximum.                                   |
-| **Backspace / Delete**     | Clear the segment (the range becomes `null` until refilled).             |
+| Key                        | Behavior                                                                                |
+| -------------------------- | --------------------------------------------------------------------------------------- |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.                            |
+| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today.                |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment in the same endpoint (no wrap).                     |
+| **Home / End**             | Jump to the segment minimum / maximum.                                                  |
+| **Backspace**              | Delete the last entered digit; the range becomes `null` when the last digit is removed. |
+| **Delete**                 | Clear the whole segment (the range becomes `null` until refilled).                      |
 
 The day clamps to the current month's length (e.g. 31 → 28 in February), and each composed endpoint is clamped into `[minDate, maxDate]`.
 

package/drawer/README.md

@@ -205,6 +205,20 @@ this.#drawers.open(ConfirmDrawer, {
 
 `activeSnapPointChange` fires with the landed snap on the mount-time default and every drag release — the read-back the declarative API exposes through `[(activeSnapPoint)]`. All three subscriptions are released automatically when the drawer closes.
 
+**Driving the active snap point.** `ForDrawerRef.setActiveSnapPoint(snap)` moves a snap-point drawer to a new snap after open — the programmatic equivalent of _writing_ `[(activeSnapPoint)]` on the declarative `[forDrawer]`. `ref.activeSnapPoint()` is the matching reactive read (it also reflects the drawer's own internal transitions — the mount-time default and every drag release):
+
+```ts
+const ref = this.#drawers.open(ConfirmDrawer, {
+  data,
+  snapPoints: ['148px', '50%', 1],
+  defaultSnapPoint: '148px',
+});
+ref.setActiveSnapPoint('50%'); // slide to the mid snap
+ref.activeSnapPoint(); // => '50%'
+```
+
+Like the declarative model it does not validate the argument against `snapPoints` (the drag engine tolerates a non-member), it is a no-op once the drawer has closed, and it is meaningful only when `snapPoints` are configured. The surface movement is the consumer's CSS keyed off the reflected `data-active-snap-point` attribute (see [Positioning the snaps](#positioning-the-snaps-css-contract)); `setActiveSnapPoint` only sets the state. As with `[(activeSnapPoint)]`, driving the snap this way does **not** re-fire the `activeSnapPointChange` callback (that fires only on the drawer's own internal transitions).
+
 ### Per-channel dismissal (Escape-only drawers)
 
 `dismissible` is **not** all-or-nothing. The four dismiss channels — Escape, pointer-down-outside, focus-outside, and the composite outside-interaction — are independently vetoable on both APIs, so you can keep some live and suppress others (e.g. a non-modal floater that closes on Escape but stays put on an outside click). Programmatically the channels are callbacks on the open config, mirroring the `autoFocusOn*` shape:

package/fesm2022/forty-cdk-calendar.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { computed, InjectionToken, inject, signal, Injector, model, input, booleanAttribute, numberAttribute, linkedSignal, effect, afterNextRender, Directive, ElementRef, Injectable } from '@angular/core';
-import { compareDateOf, clampToBounds, Collection, createDefaults, IdGenerator, LiveAnnouncer, injectDateAdapter, injectTextDirection, adoptHostId, registerHandle, FOR_DATE_ADAPTER } from 'forty-cdk/core';
+import { compareDateOf, clampToBounds, Collection, createDefaults, IdGenerator, LiveAnnouncer, injectDateAdapter, injectTextDirection, adoptHostId, registerHandle, createFormatterCache, FOR_DATE_ADAPTER } from 'forty-cdk/core';
 export { FOR_DATE_ADAPTER, assertTimeCapable, injectDateAdapter } from 'forty-cdk/core';
 
 /**
@@ -1963,16 +1963,7 @@ function clampDay(year, month, day, hours = 0, minutes = 0, seconds = 0, millise
  * calendar today; non-Gregorian calendar systems are deferred to #354.
  */
 class NativeDateAdapter {
-    #formatters = new Map();
-    #formatter(locale, options) {
-        const key = `${locale ?? ''}${JSON.stringify(options)}`;
-        let formatter = this.#formatters.get(key);
-        if (formatter === undefined) {
-            formatter = new Intl.DateTimeFormat(locale, options);
-            this.#formatters.set(key, formatter);
-        }
-        return formatter;
-    }
+    #formatter = createFormatterCache();
     /**
      * Today at local midnight in the runtime time zone. Subject to the
      * SSR/hydration caveat on {@link DateAdapter.today}.