forty-cdk 0.18.0 → 0.19.0

package/combobox/README.md

@@ -20,11 +20,11 @@ Two anatomies share the same core:
 The editable (default) anatomy — an `<input>` that filters a portaled listbox in place:
 
 ```html
-<div forCombobox [(query)]="query" [(value)]="value">
+<div forCombobox #combobox="forCombobox" [(query)]="query" [(value)]="value">
   <input forComboboxInput placeholder="Search…" />
   <button forComboboxClear>×</button>
 
-  <!-- @if (open()) { -->
+  <!-- @if (combobox.open()) { -->
   <div forComboboxContent>
     <div forComboboxOption [value]="item.id" [label]="item.label">
       <span forComboboxIndicator>✓</span>
@@ -106,7 +106,7 @@ Static and `@for`-rendered options share the same registry, navigation order (DO
 
 For a legacy `<form action="…">` flow, set `[name]` — 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).
 
-When the consumer models a single-select field as `T | null` (not `readonly T[]`), bridge it with `forSingleValueField` so the same `[formField]` wiring works unchanged: `[formField]="forSingleValueField(form.country)"`. See [Signal Forms helpers](../signal-forms/README.md).
+A single-select field is modeled as the same `readonly T[]`, kept at length ≤ 1, and bound with `[formField]` directly — 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).
 
 ## API
 
@@ -191,6 +191,8 @@ Why the list part is required, not optional: a `role="listbox"` may only own `op
 
 **Focus hand-off.** Registering a trigger opts the combobox into the standard trigger-anchored focus model: on open, focus moves into the input (the search field inside the panel); on close, focus returns to the trigger. Both moves are vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)` on `[forCombobox]`, and the return is gated by `[returnFocus]` (default `true`). Escape stays owned by the input. See [Focus & the `(autoFocusOnOpen)` / `(autoFocusOnClose)` hooks](#focus--the-autofocusonopen--autofocusonclose-hooks).
 
+**A trigger that registers late still owns the hand-off.** The trigger does not have to be declared before `[forComboboxContent]`, and does not have to exist when the panel first mounts — project it through `<ng-content>` from a wrapper, put it under a `@defer`, or gate it on an `@if` over loaded data. One caveat: focus moving _into_ the panel is a mount-time event, so a trigger that arrives while the panel is **already open** does not retroactively pull focus out of wherever you left it. From that moment on it does own the return focus, `(autoFocusOnClose)` and the Escape fallback, and the next open moves focus into the input as usual.
+
 **Trigger keyboard.** Click / Enter / Space toggle (open moves focus into the input). ArrowDown opens with the first enabled option highlighted; ArrowUp opens with the last.
 
 **Anchor preference.** With a trigger present the panel anchors to it by default. An explicit `[forComboboxAnchor]` still wins (explicit anchor → trigger → input), so you can wrap a decorated trigger box and anchor against it.
@@ -415,7 +417,7 @@ 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())`.
+> **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'` — it opens the popup, so the options render and the cache warms. Leaving `[forComboboxContent]` permanently mounted instead is not a supported shape and warns in dev mode: mount **is** the open state for this surface, so it never runs `animate.enter` / `animate.leave`, and its dismissible layer stays active while closed.
 
 ## Dismiss events
 
@@ -518,7 +520,7 @@ How navigation flows when virtualizing:
 3. Your virtualizer scrolls; the directive's `@for` mounts the option for index 999.
 4. As soon as that option registers (at the matching `posInSet`), the directive seeds `aria-activedescendant` to its id.
 
-Typeahead, inline autocomplete, and `selected().label` all read from a merged snapshot that retains entries for options scrolled out of view, so completion against off-screen labels still works.
+Inline autocomplete matches against the most recently rendered window overlaid with the position snapshot, so completion against off-screen labels still works. `selected().label` reads a separate, selection-keyed cache instead — bounded by the selection, so the label of a selected option survives close / re-open and any number of query rebuilds, but it is **not** resolved from the position snapshot: a value that enters the selection while its option is outside the rendered window (a `[(value)]` write restoring a saved selection, say) falls back to `[itemToStringLabel]` until that option renders once. Supply `[itemToStringLabel]` whenever the selection can be seeded from outside the list.
 
 ```html
 <div

package/date-picker/README.md

@@ -18,18 +18,19 @@ All date math and formatting go through a `DateAdapter<D>`, shared with `ForCale
 ## Anatomy
 
 ```html
-<div forDatePicker [(value)]="date" [(open)]="open" name="dob">
+<div forDatePicker #picker="forDatePicker" [(value)]="date" [(open)]="open" name="dob">
   <!-- optional: wrap a decorated field box in [forDatePickerAnchor] to position against it -->
   <button forDatePickerTrigger>
     <span forDatePickerValue placeholder="Pick a date"></span>
   </button>
 
-  <!-- present in the DOM only while open -->
+  <!-- @if (picker.open()) { -->
   <div forDatePickerContent>
     <div forCalendar [(value)]="date">
       <!-- …calendar header + grid… -->
     </div>
   </div>
+  <!-- } -->
 </div>
 ```
 

package/fesm2022/forty-cdk-combobox.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
-import { linkedSignal, untracked, InjectionToken, inject, computed, model, input, booleanAttribute, numberAttribute, output, effect, Directive, ElementRef, DOCUMENT, isDevMode, signal, afterNextRender } from '@angular/core';
-import { tryReadHandle, createDefaults, VirtualizedNavigator as VirtualizedNavigator$1, FormUiControlBase, ElementRegistry, Collection, defaultItemToFormValue, injectTextDirection, InitialFocusState, CloseReasonState, createPointerSuppression, LabelSnapshot, singleSelected, injectHiddenInput, isInArray, toggleInArray, nextEnabledHandle, emitVetoableEvent, emitVetoableNativeEvent, registerHandle, hostButtonType, reflectDisabled, foldTypeaheadText, hostAriaLabel, hostLabelledBy, injectOverlayShell, hostId, accessibleTextContent, registerA11yName } from 'forty-cdk/core';
+import { linkedSignal, untracked, InjectionToken, inject, computed, model, input, booleanAttribute, numberAttribute, output, effect, Directive, ElementRef, DOCUMENT, signal, afterNextRender } from '@angular/core';
+import { isUnset, runVirtualizedNavigatorBridge, createDefaults, VirtualizedNavigator as VirtualizedNavigator$1, FormUiControlBase, ElementRegistry, Collection, defaultItemToFormValue, injectTextDirection, InitialFocusState, CloseReasonState, createPointerSuppression, LabelCache, singleSelected, injectHiddenInput, isInArray, toggleInArray, nextEnabledHandle, emitVetoableEvent, emitVetoableNativeEvent, registerHandle, hostButtonType, reflectDisabled, foldTypeaheadText, hostAriaLabel, hostLabelledBy, warnIfMountedWhileClosed, injectOverlayShell, unsetInput, hostId, accessibleTextContent, assertInputBound, registerA11yName } from 'forty-cdk/core';
 
 /**
  * Build the host's activedescendant pointer as a `linkedSignal` so the
@@ -59,7 +59,7 @@ function createActiveIdSignal(source) {
  * Resolve the auto-highlight seed for the **non-virtualized** combobox: the id
  * of the option `aria-activedescendant` should fall on when the listbox is open
  * and no pointer survives. Returns `null` when no enabled option qualifies (or
- * when a `'selected'` seed can't yet read its options — see `tryReadHandle`).
+ * when a `'selected'` seed can't yet read its options — see `isUnset`).
  *
  * Pure over its inputs — no signal reads, no DOM access — so the host can call
  * it from inside its `#activeId` linkedSignal computation without leaking the
@@ -109,11 +109,11 @@ function findSelectedEnabled(items, values, equals) {
         if (item.disabled()) {
             continue;
         }
-        const read = tryReadHandle(() => ({ value: item.value() }));
-        if (read === null) {
+        const value = item.value();
+        if (isUnset(value)) {
             return NOT_READY;
         }
-        if (values.some((sel) => equals(read.value, sel))) {
+        if (values.some((sel) => equals(value, sel))) {
             return item;
         }
     }
@@ -125,13 +125,20 @@ function findSelectedEnabled(items, values, equals) {
  * {@link createActiveIdSignal}; this only performs the side effects that escape
  * the reactive graph. It reacts to `items()`, `autoHighlight()` and `open()`:
  *
- * 1. Primes the label cache so its `linkedSignal` `prev` slot gets seeded while
- *    the listbox is open — without an eager pull the lazy cache never runs
- *    during the open cycle in non-virtualized usage and persistence across
- *    close → re-open would start from an empty `prev`. The virtualization
- *    navigator (and its position-map) is primed only when the consumer set
- *    `totalCount()`, so a plain combobox never builds it.
- * 2. Virtualized only: resolves a pending `(scrollToIndex)` navigation — once
+ * The label cache is deliberately **not** pulled here: pulling it tracks the
+ * selection, and this effect writes activedescendant and scrolls, so it would
+ * re-run those writes on every commit of `value`. The root owns a separate
+ * read-only effect for that pull, and `require-sanctioned-pull-marker` now
+ * enforces the split. The position-map pull runs through the shared
+ * {@link runVirtualizedNavigatorBridge} and **does** share this effect with
+ * those writes — the one place in the library where a pull and a write live
+ * together. It is the asymmetry that makes it safe: the position map's sources
+ * (`items` / `totalCount` / the data version) are the ones this bridge already
+ * tracks through its own `items()` read, so priming it widens nothing, whereas
+ * the label cache would have added the selection. It runs only when the consumer
+ * set `totalCount()`, so a plain combobox never builds the navigator.
+ *
+ * 1. Virtualized only: resolves a pending `(scrollToIndex)` navigation — once
  *    the option for the requested posInSet mounts, `tryResolvePending` seeds
  *    activedescendant to its id and scrolls it into view. This is the single
  *    sanctioned activedescendant write from an effect, and it is a legitimate
@@ -141,7 +148,7 @@ function findSelectedEnabled(items, values, equals) {
  *    linkedSignal. `seedFromIndexedSnapshot` then seeds the topmost / bottommost
  *    *rendered* enabled option (ordered by absolute `posInSet`) deliberately
  *    passively — it only moves the pointer, never the consumer's scroll position.
- * 3. Non-virtualized: scrolls the auto-highlight-seeded option into view so a
+ * 2. Non-virtualized: scrolls the auto-highlight-seeded option into view so a
  *    seed that lands below the fold is visible, for parity with `navigate()`.
  *    The seed itself comes from the linkedSignal; this is its imperative tail.
  *    The activedescendant is read `untracked` so the scroll never re-triggers
@@ -157,15 +164,18 @@ function findSelectedEnabled(items, values, equals) {
  * Internal — not re-exported from `combobox/index.ts` or `public-api.ts`.
  */
 function runAutoHighlightBridge(deps) {
-    deps.labelCache.prime();
     const items = deps.items();
     const open = deps.open();
     const autoHighlight = deps.autoHighlight();
     const virtualized = deps.virtualized();
     if (virtualized) {
         const navigator = deps.requireNavigator();
-        navigator.prime();
-        if (navigator.tryResolvePending()) {
+        const resolved = runVirtualizedNavigatorBridge({
+            items: deps.items,
+            virtualized: deps.virtualized,
+            requireNavigator: () => navigator,
+        });
+        if (resolved) {
             return;
         }
         if (autoHighlight && open && untracked(() => deps.getActiveId()) === null && items.length > 0) {
@@ -267,13 +277,48 @@ function provideForComboboxDefaults(defaults = {}) {
     return provideDefaults(defaults);
 }
 
+/**
+ * Overlay the virtualized position snapshot onto the label cache's window
+ * entries, so inline autocomplete keeps matching options scrolled out of view.
+ *
+ * The label cache holds one window at a time, while the navigator's position map
+ * accumulates every position it has folded (bounded by `totalCount`, purged on a
+ * dataset rebuild). Window entries take precedence — they are the freshest read —
+ * and off-window entries follow, sorted by absolute position so a completion walk
+ * meets them in list order. De-duplication is by serialized form value, not by
+ * `id`: an option that unmounts and remounts under a new id but the same value is
+ * one option.
+ *
+ * Pass an empty map (the non-virtualized case) to get `entries` back unchanged.
+ *
+ * Internal — not re-exported from `combobox/public-api.ts`.
+ */
+function mergeOffWindowEntries(entries, indexed, toFormValue) {
+    if (indexed.size === 0) {
+        return entries;
+    }
+    const seen = new Set(entries.map((entry) => toFormValue(entry.value)));
+    const merged = [...entries];
+    for (const pos of [...indexed.keys()].sort((a, b) => a - b)) {
+        const entry = indexed.get(pos);
+        const key = toFormValue(entry.value);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        merged.push(entry);
+    }
+    return merged;
+}
+
 /**
  * Virtualization navigation engine for `ForCombobox`. A thin adapter over the
  * shared `_internal/virtualized-navigator` engine. Maps the combobox option
- * handle (whose `posInSet` is optional) onto the engine's accessors, reads the
- * option through the single NG0950 read guard, and overrides scroll-into-view
- * with the host's pointer-suppression wrapper. Adds the combobox-only
- * auto-highlight seed that stays passive (never scrolls the window).
+ * handle (whose `posInSet` is optional) onto the engine's accessors, skips an
+ * option whose `[value]` binding is not written yet, and overrides
+ * scroll-into-view with the host's pointer-suppression wrapper. Adds the
+ * combobox-only auto-highlight seed that stays passive (never scrolls the
+ * window).
  *
  * Internal — not re-exported from `combobox/index.ts` or `public-api.ts`.
  */
@@ -286,12 +331,11 @@ class VirtualizedNavigator {
             posOf: (o) => o.posInSet?.() ?? null,
             idOf: (o) => o.id(),
             hostOf: (o) => o.host,
-            readEntry: (o) => tryReadHandle(() => ({
-                id: o.id(),
-                value: o.value(),
-                label: o.label(),
-                disabled: o.disabled(),
-            })),
+            readEntry: (o) => {
+                const id = o.id();
+                const value = o.value();
+                return isUnset(value) ? null : { id, value, label: o.label(), disabled: o.disabled() };
+            },
             scrollIntoView: (host) => deps.scrollActiveIntoView(host),
         }, { deferFoldOnTotalTransition: true });
     }
@@ -679,14 +723,18 @@ class ForCombobox extends FormUiControlBase {
     #lastPositionedId = null;
     #pointerSuppression = createPointerSuppression();
     /**
-     * Always-on label snapshot — keeps `{ id, value, label }` tuples across
-     * close/open and scroll-out-of-view to drive inline autocomplete matching
-     * and the `selected` label fallback. The value-keyed fold itself lives in
-     * `forty-cdk/core`, shared with `[forSelect]`.
+     * Bounded option-label cache, shared with `[forSelect]` through
+     * `forty-cdk/core`. Keeps `{ id, value, label, disabled }` tuples across
+     * close/open in two projections: the selection-keyed one backs
+     * {@link selected}'s chip labels (bounded by the selection, so a long-lived
+     * remote-search combobox retains the labels of what is selected and nothing
+     * else), and the last-window one backs {@link completionEntries} for inline
+     * autocomplete. Off-window matching while virtualizing comes from the
+     * navigator's position map instead — see {@link completionEntries}.
      */
-    #labelCache = new LabelSnapshot({
+    #labelCache = new LabelCache({
         items: this.#items.items,
-        totalCount: this.totalCount,
+        value: this.value,
         itemToFormValue: this.itemToFormValue,
     });
     /**
@@ -727,10 +775,7 @@ class ForCombobox extends FormUiControlBase {
         if (values.length === 0) {
             return [];
         }
-        // `cachedOptions()` already merges off-window entries from the indexed
-        // snapshot when virtualizing, so a selected option scrolled out of view
-        // still resolves here without a separate position-map lookup.
-        const cached = this.cachedOptions();
+        const cached = this.selectedEntries();
         const equals = this.compareWith();
         const toLabel = this.itemToStringLabel();
         return values.map((v) => {
@@ -782,14 +827,22 @@ class ForCombobox extends FormUiControlBase {
             serialize: (item) => this.itemToFormValue()(item),
             disabled: this.effectiveDisabled,
         });
+        // @sanctioned-pull(label-cache-window): the option window exists only while
+        // the listbox is open, and the closed-state fallback reading it has no
+        // reader during that cycle.
+        effect(() => {
+            this.#labelCache.prime();
+        });
         // The activedescendant *decision* is a pure derivation in `#activeId`; this
-        // effect runs only its imperative tail (label-cache priming, virtualized
-        // pending-nav resolution + passive seed, non-virtualized scroll-into-view).
-        // Full rationale lives with `runAutoHighlightBridge` in
-        // `combobox-auto-highlight.ts`.
+        // effect runs only its imperative tail (virtualized pending-nav resolution +
+        // passive seed, non-virtualized scroll-into-view). It is the library's one
+        // pull sharing an effect with writes: the position map's sources are the ones
+        // the bridge already tracks, so priming it widens nothing. Full rationale
+        // lives with `runAutoHighlightBridge` in `combobox-auto-highlight.ts`.
+        // @sanctioned-pull(navigator-position-map): the rendered window is transient,
+        // so a window nothing reads during is lost to the lazy fold.
         effect(() => {
             runAutoHighlightBridge({
-                labelCache: this.#labelCache,
                 requireNavigator: () => this.#requireNavigator(),
                 items: this.#items.items,
                 open: this.open,
@@ -901,6 +954,9 @@ class ForCombobox extends FormUiControlBase {
             return;
         }
         const v = handle.value();
+        if (isUnset(v)) {
+            return;
+        }
         if (this.multiple()) {
             // Toggle in/out of the array. Stay open so the user can keep picking.
             this.value.set(toggleInArray(this.value(), v, this.compareWith()));
@@ -1041,25 +1097,19 @@ class ForCombobox extends FormUiControlBase {
         active.host.scrollIntoView?.({ block: 'nearest' });
         this.#lastPositionedId = id;
     }
-    #cachedOptionsMemo = computed(() => {
-        if (this.totalCount() === undefined) {
-            return this.#labelCache.entries();
-        }
-        return this.#labelCache.mergedEntries(this.#requireNavigator().snapshotByPos());
-    }, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "#cachedOptionsMemo" }] : /* istanbul ignore next */ []));
-    cachedOptions() {
-        return this.#cachedOptionsMemo();
+    selectedEntries() {
+        return this.#labelCache.selectedEntries();
     }
-    #inlineCompletionOptionsMemo = computed(() => {
+    #completionEntriesMemo = computed(() => {
+        const liveWindow = this.#labelCache.windowEntries();
         if (this.totalCount() === undefined) {
-            return this.#labelCache.liveEntries();
+            return liveWindow;
         }
-        return this.#labelCache.mergedEntries(this.#requireNavigator().snapshotByPos());
+        return mergeOffWindowEntries(liveWindow, this.#requireNavigator().snapshotByPos(), this.itemToFormValue());
     }, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "#inlineCompletionOptionsMemo" }] : /* istanbul ignore next */ []));
-    inlineCompletionOptions() {
-        return this.#inlineCompletionOptionsMemo();
+    ...(ngDevMode ? [{ debugName: "#completionEntriesMemo" }] : /* istanbul ignore next */ []));
+    completionEntries() {
+        return this.#completionEntriesMemo();
     }
     clear(clearQuery = true) {
         if (this.effectiveDisabled() || this.readonly()) {
@@ -1516,7 +1566,7 @@ class ForComboboxInput {
             }
         }
         const match = this.ctx
-            .inlineCompletionOptions()
+            .completionEntries()
             .find((o) => !o.disabled && foldTypeaheadText(o.label).startsWith(folded));
         return match ? match.label : null;
     }
@@ -1677,7 +1727,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImpor
  * `@floating-ui/dom` against the anchor (explicit `[forComboboxAnchor]` →
  * `[forComboboxTrigger]` → input).
  *
- * Two anatomies, picked by whether an inner `[forComboboxList]` is present:
+ * Two anatomies. The **role split** is picked by whether an inner
+ * `[forComboboxList]` is present:
  *
  * - **Editable (no list)** — content itself carries `role="listbox"`,
  *   `tabindex="-1"`, `aria-multiselectable`, and the labelled role
@@ -1696,19 +1747,32 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImpor
  * trigger are exempt from outside checks.
  *
  * Focus:
- * - **Editable anatomy** — focus normally stays in the input across the whole
- *   open lifecycle and active-option highlighting is `aria-activedescendant`-
- *   driven, so the directive exposes no focus hooks. The surface itself is
- *   focusable (`tabindex="-1"`), so a click on non-option padding can move focus
- *   onto it; the input's inline Escape handler then never sees the key, so the
- *   shell wires a fallback Escape channel that closes the popup and returns focus
- *   to the input.
- * - **Picker anatomy** — on open, focus moves into the input (the search field
- *   inside the panel); on close it returns to the trigger. Both moves are
- *   vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)` on `[forCombobox]`,
- *   and the return is gated by `[returnFocus]`. Escape from the input is owned by
- *   the input directive; the shell's fallback channel covers presses that land on
- *   the surface or list instead.
+ * - **Editable anatomy (no trigger)** — focus normally stays in the input
+ *   across the whole open lifecycle and active-option highlighting is
+ *   `aria-activedescendant`-driven, so the directive exposes no focus hooks. The
+ *   surface itself is focusable (`tabindex="-1"`), so a click on non-option
+ *   padding can move focus onto it; the input's inline Escape handler then never
+ *   sees the key, so the shell wires a fallback Escape channel that closes the
+ *   popup and returns focus to the input.
+ * - **Picker anatomy (trigger present)** — on open, focus moves into the input
+ *   (the search field inside the panel); on close it returns to the trigger.
+ *   Both moves are vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)` on
+ *   `[forCombobox]`, and the return is gated by `[returnFocus]`. Escape from the
+ *   input is owned by the input directive; the shell's fallback channel covers
+ *   presses that land on the surface or list instead.
+ *
+ * So the two splits are keyed independently — roles off `hasList`, focus off
+ * the trigger — and the trigger check is a `computed`, consulted at each
+ * decision point rather than snapshotted at construction
+ * ([#1581](https://github.com/tutkli/forty-cdk/issues/1581)) — so a trigger
+ * declared after this content, projected through `<ng-content>`, or gated by a
+ * `@defer` / data-driven `@if` upgrades the surface instead of leaving it with
+ * no focus management at all. Initial focus stays a mount-time event (the shell
+ * decides it in `afterNextRender`, by which point a trigger constructed in the
+ * same pass has registered), so a trigger arriving in a later pass while the
+ * surface is already open does not retroactively pull focus out of wherever the
+ * user left it — it takes over the return focus, `(autoFocusOnClose)` and the
+ * Escape fallback from there on.
  *
  * The lifecycle (positioner + dismissible layer, plus the picker anatomy's
  * focus bundles) is owned by the shared `injectOverlayShell` helper.
@@ -1723,27 +1787,20 @@ class ForComboboxContent {
     constructor() {
         const ctx = this.ctx;
         registerHandle(this.#host.nativeElement, (el) => ctx.registerContent(el), (el) => ctx.unregisterContent(el));
-        // The picker anatomy opts back into the shell's focus bundles. `trigger()`
-        // is read once on construction: the trigger renders outside the `@if (open())`
-        // that gates this content, so it has already registered by the time the
-        // surface mounts. Without a trigger (editable anatomy) the bundles are
-        // omitted entirely and focus stays in the input — byte-for-byte unchanged.
-        // That assumption is dev-verified: a trigger that registers late (after this
-        // content was constructed) trips a dev-mode `console.warn`.
-        const hasTrigger = ctx.trigger() !== null;
-        if (isDevMode() && !hasTrigger) {
-            let warned = false;
-            effect(() => {
-                if (!warned && ctx.trigger() !== null) {
-                    warned = true;
-                    console.warn('[forty-cdk/combobox] [forComboboxTrigger] registered after [forComboboxContent] was constructed, ' +
-                        'so the picker focus behavior was not wired for this content: focus will not move into ' +
-                        '[forComboboxInput] on open, will not return to the trigger on close, and (autoFocusOnOpen) / ' +
-                        '(autoFocusOnClose) will not fire. Declare [forComboboxTrigger] before (and outside) the ' +
-                        '@if (open()) block that gates [forComboboxContent] so it registers first.');
-                }
-            });
-        }
+        warnIfMountedWhileClosed({
+            primitive: 'combobox',
+            piece: '[forComboboxContent]',
+            condition: 'combobox.open()',
+            open: ctx.open,
+        });
+        // Both focus bundles are always handed to the shell; the anatomy gates them
+        // from inside their own callbacks, which the shell runs after construction
+        // (`initialFocus` in `afterNextRender`, `returnFocus` on destroy). So the
+        // gate reads a fresh `trigger()` at each decision point instead of a
+        // construction-time snapshot, and the editable anatomy still performs no
+        // imperative move and fires neither hook.
+        const hasTrigger = computed(() => ctx.trigger() !== null, /* @ts-ignore */
+        ...(ngDevMode ? [{ debugName: "hasTrigger" }] : /* istanbul ignore next */ []));
         const config = {
             positioner: {
                 kind: 'floating',
@@ -1766,7 +1823,7 @@ class ForComboboxContent {
                 requestClose: (reason) => ctx.requestClose(reason),
                 emitEscapeKeyDown: (event) => {
                     ctx.emitEscapeKeyDown(event);
-                    if (!hasTrigger && !ctx.open()) {
+                    if (!hasTrigger() && !ctx.open()) {
                         ctx.input()?.focus();
                     }
                 },
@@ -1791,36 +1848,36 @@ class ForComboboxContent {
                 },
             },
             // Picker anatomy only: move focus into the input on open, return it to the
-            // trigger on close. Editable anatomy keeps focus in the input throughout,
-            // so both bundles stay absent (no imperative move, no hooks).
-            ...(hasTrigger
-                ? {
-                    initialFocus: {
-                        move: () => {
-                            const input = ctx.input();
-                            if (input) {
-                                input.focus();
-                                return true;
-                            }
-                            return false;
-                        },
-                        veto: () => ctx.emitAutoFocusOnOpen(),
-                    },
-                    returnFocus: {
-                        enabled: ctx.returnFocus,
-                        target: () => ctx.trigger(),
-                        veto: () => ctx.emitAutoFocusOnClose(),
-                        // On Tab and on outside dismissal (pointer-down-outside /
-                        // focus-outside) focus already landed where the user tabbed or
-                        // clicked; re-focusing the trigger would steal it back (native
-                        // <select> parity, mirroring popover #1310).
-                        skip: () => {
-                            const reason = ctx.lastCloseReason();
-                            return (reason === 'tab' || reason === 'pointerDownOutside' || reason === 'focusOutside');
-                        },
-                    },
-                }
-                : {}),
+            // trigger on close. The editable anatomy keeps focus in the input
+            // throughout, so its gate vetoes / skips before either hook is emitted.
+            initialFocus: {
+                move: () => {
+                    const input = ctx.input();
+                    if (input) {
+                        input.focus();
+                        return true;
+                    }
+                    return false;
+                },
+                veto: () => !hasTrigger() || ctx.emitAutoFocusOnOpen(),
+            },
+            returnFocus: {
+                enabled: ctx.returnFocus,
+                target: () => ctx.trigger(),
+                veto: () => ctx.emitAutoFocusOnClose(),
+                // The anatomy gate comes first: the editable anatomy never reaches
+                // `veto`, so it never emits. Then, on Tab and on outside dismissal
+                // (pointer-down-outside / focus-outside) focus already landed where the
+                // user tabbed or clicked; re-focusing the trigger would steal it back
+                // (native <select> parity, mirroring popover #1310).
+                skip: () => {
+                    if (!hasTrigger()) {
+                        return true;
+                    }
+                    const reason = ctx.lastCloseReason();
+                    return reason === 'tab' || reason === 'pointerDownOutside' || reason === 'focusOutside';
+                },
+            },
         };
         injectOverlayShell(config);
     }
@@ -1943,8 +2000,12 @@ class ForComboboxOption {
      * the parent `[forCombobox]` over a richer `T`. The parent's
      * `[compareWith]` decides how options are matched against the
      * committed selection.
+     *
+     * Mandatory: it is seeded with the `unsetInput` sentinel rather than declared
+     * `input.required` so the parent can skip an option that has registered but
+     * not been bound yet, and an unbound option throws in dev mode.
      */
-    value = input.required(/* @ts-ignore */
+    value = input(unsetInput(), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
     /**
      * Visible label used by `[forComboboxInput]` for inline autocomplete
@@ -1966,7 +2027,10 @@ class ForComboboxOption {
     posInSet = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "posInSet" }] : /* istanbul ignore next */ []));
     id = hostId('for-combobox-option');
-    selected = computed(() => this.#ctx.isSelected(this.value()), /* @ts-ignore */
+    selected = computed(() => {
+        const value = this.value();
+        return isUnset(value) ? false : this.#ctx.isSelected(value);
+    }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "selected" }] : /* istanbul ignore next */ []));
     /** True when this option is the current activedescendant. Reflected as `data-highlighted`. */
     highlighted = computed(() => this.#ctx.isActive(this.id()), /* @ts-ignore */
@@ -2001,6 +2065,9 @@ class ForComboboxOption {
             return explicit;
         }
         const v = this.value();
+        if (isUnset(v)) {
+            return '';
+        }
         if (typeof v === 'string') {
             // String mode: the trimmed `textContent` is the canonical fallback,
             // identical to the pre-generic behaviour. Lets consumers omit
@@ -2021,6 +2088,7 @@ class ForComboboxOption {
         posInSet: this.posInSet,
     };
     constructor() {
+        assertInputBound(this.value, 'combobox', '[forComboboxOption]', 'value');
         registerHandle(this.#handle, (h) => this.#ctx.registerOption(h), (h) => this.#ctx.unregisterOption(h));
     }
     onClick() {
@@ -2038,7 +2106,7 @@ class ForComboboxOption {
         }
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForComboboxOption, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForComboboxOption, isStandalone: true, selector: "[forComboboxOption]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: true, transformFunction: null }, label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, posInSet: { classPropertyName: "posInSet", publicName: "posInSet", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "option" }, listeners: { "click": "onClick()", "pointermove": "onPointerMove()" }, properties: { "id": "id()", "attr.aria-selected": "ariaSelected()", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-posinset": "ariaPosInSet()", "attr.aria-setsize": "ariaSetSize()", "attr.data-state": "selected() ? \"checked\" : \"unchecked\"", "attr.data-highlighted": "highlighted() ? \"\" : null", "attr.data-disabled": "effectiveDisabled() ? \"\" : null" } }, providers: [{ provide: FOR_COMBOBOX_OPTION, useExisting: ForComboboxOption }], exportAs: ["forComboboxOption"], ngImport: i0 });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForComboboxOption, isStandalone: true, selector: "[forComboboxOption]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, posInSet: { classPropertyName: "posInSet", publicName: "posInSet", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "role": "option" }, listeners: { "click": "onClick()", "pointermove": "onPointerMove()" }, properties: { "id": "id()", "attr.aria-selected": "ariaSelected()", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-posinset": "ariaPosInSet()", "attr.aria-setsize": "ariaSetSize()", "attr.data-state": "selected() ? \"checked\" : \"unchecked\"", "attr.data-highlighted": "highlighted() ? \"\" : null", "attr.data-disabled": "effectiveDisabled() ? \"\" : null" } }, providers: [{ provide: FOR_COMBOBOX_OPTION, useExisting: ForComboboxOption }], exportAs: ["forComboboxOption"], ngImport: i0 });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForComboboxOption, decorators: [{
             type: Directive,
@@ -2060,7 +2128,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImpor
                         '(pointermove)': 'onPointerMove()',
                     },
                 }]
-        }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: true }] }], label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], posInSet: [{ type: i0.Input, args: [{ isSignal: true, alias: "posInSet", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], posInSet: [{ type: i0.Input, args: [{ isSignal: true, alias: "posInSet", required: false }] }] } });
 
 /**
  * Visibility helper inside a `[forComboboxOption]`. The directive flips a
@@ -2547,7 +2615,7 @@ class ForComboboxChip {
     label = computed(() => {
         const v = this.value();
         const equals = this.ctx.compareWith();
-        const cached = this.ctx.cachedOptions().find((o) => equals(o.value, v));
+        const cached = this.ctx.selectedEntries().find((o) => equals(o.value, v));
         if (cached) {
             return cached.label;
         }