forty-cdk 0.2.0 → 0.3.0

package/fesm2022/forty-cdk-select.mjs

@@ -0,0 +1,1661 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, computed, model, input, booleanAttribute, numberAttribute, output, signal, linkedSignal, effect, Directive, ElementRef } from '@angular/core';
+import { createDefaults, VirtualizedNavigator, readEntryGuarded, FormUiControlBase, IdGenerator, injectTypeahead, defaultItemToFormValue, singleSelected, injectTextDirection, ListboxOverlayController, isRequiredInputUnset, injectHiddenInput, isInArray, toggleInArray, findTypeaheadMatch, resolveListNavigation, registerHandle, reflectDisabled, injectModalShell, injectOverlayShell, hostId, registerA11yName } from 'forty-cdk/core';
+
+const FOR_SELECT_CONTEXT = new InjectionToken('FOR_SELECT_CONTEXT');
+function injectSelectContext(piece) {
+    const ctx = inject(FOR_SELECT_CONTEXT, { optional: true });
+    if (!ctx) {
+        throw new Error(`[forty-cdk/select] ${piece} must be used inside a [forSelect] element. ` +
+            "If it is declared inside an ng-template, DI resolves at the template's declaration site — " +
+            'not where it is stamped (e.g. via ngTemplateOutlet) — so declare the template inside the ' +
+            '[forSelect] root.');
+    }
+    return ctx;
+}
+/**
+ * Resolves the trigger's root context: the explicit reference when the
+ * `[forSelectTrigger]` input carries one, the injected `FOR_SELECT_CONTEXT`
+ * otherwise. The orphan error only fires when neither resolves, on first read
+ * of the returned signal. Must be called in an injection context.
+ */
+function injectSelectTriggerContext(explicitRoot) {
+    const injected = inject(FOR_SELECT_CONTEXT, { optional: true });
+    return computed(() => {
+        const explicit = explicitRoot();
+        if (explicit !== '') {
+            return explicit;
+        }
+        if (injected) {
+            return injected;
+        }
+        throw new Error('[forty-cdk/select] ForSelectTrigger could not resolve its [forSelect] root: ' +
+            'no FOR_SELECT_CONTEXT provider is visible and no explicit root reference was passed. ' +
+            "If this trigger is declared inside an ng-template, DI resolves at the template's declaration " +
+            'site — not where it is stamped — so either declare the template inside the root or pass the ' +
+            'root explicitly: [forSelectTrigger]="root" with #root="forSelect".');
+    });
+}
+
+/**
+ * Library fallback for select defaults, read at the root injector when no
+ * consumer has called `provideForSelectDefaults`. Exported for the shared defaults
+ * contract spec; not re-exported from the primitive's public entry.
+ */
+const FOR_SELECT_FALLBACK_DEFAULTS = {
+    sideOffset: 4,
+    collisionPadding: 8,
+};
+const { token, provideDefaults } = createDefaults('FOR_SELECT_DEFAULTS', FOR_SELECT_FALLBACK_DEFAULTS);
+/** Token holding the resolved select defaults for the current scope. */
+const FOR_SELECT_DEFAULTS = token;
+/**
+ * Configures forty-cdk select defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+function provideForSelectDefaults(defaults = {}) {
+    return provideDefaults(defaults);
+}
+
+/**
+ * Virtualization navigation engine for `ForSelect`. A thin adapter over the
+ * shared `_internal/virtualized-navigator` engine: it maps the select option
+ * handle onto the engine's accessors (the option carries its raw `value` so the
+ * root can resolve the committed option's index on open) and reads the option's
+ * `value` through the single NG0950 read guard.
+ *
+ * Internal — not re-exported from `select/index.ts` or `public-api.ts`.
+ */
+class SelectVirtualizedNavigator {
+    #core;
+    constructor(deps) {
+        this.#core = new VirtualizedNavigator({ ...deps, loop: deps.loop }, {
+            posOf: (o) => o.posInSet(),
+            idOf: (o) => o.id(),
+            hostOf: (o) => o.host,
+            readEntry: (o) => readEntryGuarded(() => ({ id: o.id(), value: o.value(), disabled: o.disabled() })),
+        });
+    }
+    /** @see VirtualizedNavigator.prime */
+    prime() {
+        this.#core.prime();
+    }
+    /** @see VirtualizedNavigator.tryResolvePending */
+    tryResolvePending() {
+        return this.#core.tryResolvePending();
+    }
+    /** @see VirtualizedNavigator.navigate */
+    navigate(direction) {
+        this.#core.navigate(direction);
+    }
+    /**
+     * Read-only position snapshot for the root's committed-index resolution.
+     * Keyed by absolute `posInSet`; persists across close → reopen while
+     * `totalCount` is unchanged.
+     */
+    snapshotByPos() {
+        return this.#core.snapshotByPos();
+    }
+    /** @see VirtualizedNavigator.seedActive */
+    seedActive(index) {
+        this.#core.seedActive(index);
+    }
+    /** @see VirtualizedNavigator.resetPending */
+    resetPending() {
+        this.#core.resetPending();
+    }
+}
+
+/** Sentinel for an option handle whose `input.required` `[value]` is not yet written. */
+const NO_VALUE = Symbol('forty-cdk/select:no-value');
+/**
+ * Headless implementation of the [WAI-ARIA select-only combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).
+ * Implements `FormValueControl<readonly T[]>` from
+ * `@angular/forms/signals` for `[formField]` auto-wiring.
+ *
+ * Generic over the option value type `T` (default `string`). When the
+ * consumer binds object items the directive infers `T` from `[(value)]` and
+ * `[forSelectOption][value]`; object identity is resolved by the
+ * consumer-supplied `[isItemEqualToValue]` and the hidden inputs serialize
+ * via `[itemToFormValue]`. Option display text is read from the rendered
+ * `textContent`, so no separate label function is needed — supply the
+ * optional `[itemToLabel]` only when a pre-set object value must render its
+ * label before the listbox is ever opened (the documented `@if (open())`
+ * pattern).
+ *
+ * Selection is always modeled as `readonly T[]`:
+ * - In single mode (`multiple=false`, default), the array has 0 or 1 element
+ *   and option activation closes the listbox.
+ * - In multi mode, option activation toggles and the listbox stays open.
+ *
+ * Typeahead has two modes mirroring native `<select>`:
+ * - **Closed trigger** (single mode only): printable keys select the matching
+ *   option immediately without opening the listbox.
+ * - **Open listbox**: printable keys move focus to the first matching option
+ *   (selection still requires Enter / Space / click).
+ */
+class ForSelect extends FormUiControlBase {
+    #idGen = inject(IdGenerator);
+    #typeahead = injectTypeahead();
+    #closedTypeahead = injectTypeahead();
+    #defaults = inject(FOR_SELECT_DEFAULTS);
+    /**
+     * Two-way bindable. Selected option values. Single-mode keeps 0 or 1
+     * element. The `model()` change emitter (`(valueChange)`) fires only on
+     * internal selection changes, never on consumer writes via `[(value)]`.
+     */
+    value = model([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
+    /**
+     * Compare two items for equality. Defaults to `===`, which is the
+     * correct identity for primitive `T` (e.g. strings, numbers). Override
+     * when binding object items so the directive can locate selected entries
+     * by id (or any other stable key) instead of by reference:
+     * `[isItemEqualToValue]="(a, b) => a.id === b.id"`.
+     */
+    isItemEqualToValue = input((a, b) => a === b, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isItemEqualToValue" }] : /* istanbul ignore next */ []));
+    /**
+     * Serialize an item for the hidden input that participates in native
+     * form submission. Defaults to identity for strings and to
+     * `JSON.stringify` for non-string items so the primitive works out of
+     * the box round-tripping objects. Override to emit a specific wire
+     * format — typically a per-item id — when the backend expects that:
+     * `[itemToFormValue]="(it) => it.id"`.
+     */
+    itemToFormValue = input(defaultItemToFormValue, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "itemToFormValue" }] : /* istanbul ignore next */ []));
+    /**
+     * Resolve the display label for an item without the listbox mounted.
+     * When set, {@link selectedLabels} (and therefore `[forSelectValue]`)
+     * renders this for any selected value, so a pre-set object value shows
+     * its label on first paint — before the listbox has ever been opened, in
+     * the documented `@if (forSelect.open())` pattern. Without it, object-value
+     * labels resolve from the rendered option `textContent`, which is only
+     * available once the content mounts; the serialized form value is shown as
+     * a last-resort fallback in the meantime: `[itemToLabel]="(c) => c.name"`.
+     *
+     * Defaults to `undefined` (string mode renders the value verbatim, so no
+     * label function is needed).
+     */
+    itemToLabel = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "itemToLabel" }] : /* istanbul ignore next */ []));
+    /**
+     * Read-only single-select convenience view of {@link value}. Returns the
+     * sole value when exactly one is selected (regardless of `multiple`),
+     * otherwise `null` (zero, or 2+ selected). Lets single-select consumers
+     * read `selected()` instead of unwrapping `value()[0]`. The array-backed
+     * `value` model remains the source of truth and the `FormValueControl`
+     * contract; this is a derived accessor.
+     */
+    selected = singleSelected(this.value);
+    /**
+     * Two-way bindable. Whether the listbox is currently shown. The `model()`
+     * change emitter (`(openChange)`) fires only on internal transitions
+     * (trigger toggle, Escape, outside dismissal, single-mode option select),
+     * never on consumer writes via `[(open)]`.
+     */
+    open = model(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "open" }] : /* istanbul ignore next */ []));
+    multiple = input(false, { ...(ngDevMode ? { debugName: "multiple" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Presentation mode. When `true`, `[forSelectContent]` mounts as a trapped /
+     * inert / scroll-locked modal surface (routed through `_internal/modal-shell`)
+     * instead of the default anchored popover — the batteries-included touch
+     * presentation a consumer opts into with `[modal]="isCoarsePointer()"`. The
+     * form-value wiring (`[(value)]`, `name`) is unchanged.
+     *
+     * Read once when the content mounts (the two shells are structurally
+     * different; switching at runtime would need a remount, and the surface
+     * mounts lazily via `@if (open())` well after `modal` settles). Every
+     * anchored-positioning input — `position`, `side`, `align`, `sideOffset`,
+     * `alignOffset`, `sticky`, `hideWhenDetached`, `clipUntilPositioned`, `avoidCollisions`,
+     * `collisionPadding`, `arrowPadding` — is a no-op in this mode. Default
+     * `false` (non-breaking). The swipe / snap-point sheet is deliberately not
+     * this mode — compose a `ForListbox` inside a `ForDrawer` for that.
+     */
+    modal = input(false, { ...(ngDevMode ? { debugName: "modal" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Positioning algorithm.
+     *
+     * - `'popper'` (default): standard floating-ui anchored placement using
+     *   `side` / `align` / `sideOffset` / `alignOffset`, with `flip` + `shift`
+     *   collision handling. Same path as Popover / DropdownMenu.
+     * - `'item-aligned'`: the listbox overlays the trigger so the selected
+     *   option's vertical center aligns with the trigger's vertical center
+     *   — visually the menu "snaps over" the trigger when opened, mirroring
+     *   macOS native `<select>`. Falls back to the first enabled option when
+     *   nothing is selected. `side`, `align`, `sideOffset`, `alignOffset`,
+     *   `sticky`, `hideWhenDetached`, `clipUntilPositioned`, and `avoidCollisions` are ignored in
+     *   this mode; only `collisionPadding` is honored.
+     */
+    position = input('popper', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "position" }] : /* istanbul ignore next */ []));
+    /**
+     * Side the listbox is anchored to. Defaults to `'bottom'`. Pair with
+     * `align` for the full positioning API. Ignored when
+     * `position="item-aligned"`.
+     */
+    side = input('bottom', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "side" }] : /* istanbul ignore next */ []));
+    /** Alignment along the chosen `side`. Defaults to `'start'`. */
+    align = input('start', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "align" }] : /* istanbul ignore next */ []));
+    /**
+     * Gap (px) between trigger and listbox along the main axis. Default `4`.
+     * The default is read from
+     * `provideForSelectDefaults` for the surrounding scope.
+     */
+    sideOffset = input(this.#defaults.sideOffset, { ...(ngDevMode ? { debugName: "sideOffset" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Gap (px) along the cross axis. Default `0`. */
+    alignOffset = input(0, { ...(ngDevMode ? { debugName: "alignOffset" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** When `true` (default), `flip` and `shift` keep the listbox inside the viewport. */
+    avoidCollisions = input(true, { ...(ngDevMode ? { debugName: "avoidCollisions" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Padding (px) applied uniformly to flip / shift / size. Default `8`.
+     * The default is read from `provideForSelectDefaults` for the surrounding
+     * scope.
+     */
+    collisionPadding = input(this.#defaults.collisionPadding, { ...(ngDevMode ? { debugName: "collisionPadding" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Padding (px) for the `arrow` middleware. Default `0`. */
+    arrowPadding = input(0, { ...(ngDevMode ? { debugName: "arrowPadding" } : /* istanbul ignore next */ {}), transform: numberAttribute });
+    /** Stickiness behaviour for `shift`. Default `'partial'`. */
+    sticky = input('partial', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "sticky" }] : /* istanbul ignore next */ []));
+    /** When `true`, sets `data-detached=""` while the trigger is scrolled off-screen. */
+    hideWhenDetached = input(false, { ...(ngDevMode ? { debugName: "hideWhenDetached" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * When `true` (default), the content is clipped until floating-ui resolves
+     * its first position, preventing a flash at the viewport corner. Set to
+     * `false` so a dramatic `animate.enter` plays from its first frame (the
+     * surface may flash briefly at the unresolved position while positioning
+     * computes).
+     */
+    clipUntilPositioned = input(true, { ...(ngDevMode ? { debugName: "clipUntilPositioned" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    loop = input(true, { ...(ngDevMode ? { debugName: "loop" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    orientation = input('vertical', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "orientation" }] : /* istanbul ignore next */ []));
+    /**
+     * Total number of items in the source data. When set, switches the listbox
+     * to the virtualized `aria-activedescendant` focus model and populates
+     * `aria-setsize` on each rendered option. Leave unset (default) for the
+     * standard DOM-focus model.
+     */
+    totalCount = input(undefined, { ...(ngDevMode ? { debugName: "totalCount" } : /* istanbul ignore next */ {}), transform: (v) => (v == null ? undefined : numberAttribute(v)) });
+    /**
+     * Inclusive-exclusive `[start, end)` index range of the currently rendered
+     * options, provided by `injectVirtualizer`. Used to decide whether a
+     * navigation target is in the visible window.
+     */
+    visibleRange = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "visibleRange" }] : /* istanbul ignore next */ []));
+    /**
+     * Emitted when navigation (or open-time scroll-to-selected) reaches an
+     * option outside the rendered window. Pass to `injectVirtualizer`'s
+     * `scrollToIndex` so the correct option mounts.
+     */
+    scrollToIndex = output();
+    /**
+     * Writing direction. When unset (default `null`), the inherited ambient
+     * direction is resolved from the nearest ancestor carrying a `dir` attribute
+     * (or `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]` always wins.
+     * The resolved value is reflected to the host `dir` attribute.
+     */
+    _dirInput = input(null, { ...(ngDevMode ? { debugName: "_dirInput" } : /* istanbul ignore next */ {}), alias: 'dir' });
+    dir = injectTextDirection(this._dirInput);
+    /**
+     * Single-mode only. When true, arrow nav also selects the focused option
+     * while the listbox is open. APG calls this optional and recommends
+     * caution — leave off unless your UX truly benefits. Default `false`.
+     */
+    selectionFollowsFocus = input(false, { ...(ngDevMode ? { debugName: "selectionFollowsFocus" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Placeholder shown by `[forSelectValue]` when no option is selected. */
+    placeholder = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /** When true (default), Escape, pointer-down outside, and focus outside close the listbox. */
+    dismissible = input(true, { ...(ngDevMode ? { debugName: "dismissible" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** When true (default), focus returns to the trigger on close. */
+    returnFocus = input(true, { ...(ngDevMode ? { debugName: "returnFocus" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Manual `aria-label` on `[forSelectContent]` when the trigger isn't a meaningful name. */
+    ariaLabel = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaLabel" }] : /* istanbul ignore next */ []));
+    escapeKeyDown = output();
+    pointerDownOutside = output();
+    focusOutside = output();
+    interactOutside = output();
+    /**
+     * Fires just before the listbox sends focus to the selected option
+     * (or first / last enabled) on mount. Call `preventDefault()` on the
+     * emitted veto to skip the imperative focus move.
+     */
+    autoFocusOnOpen = output();
+    /**
+     * Fires just before focus returns to the trigger on unmount. Call
+     * `preventDefault()` on the veto to suppress the return-focus.
+     */
+    autoFocusOnClose = output();
+    #virtualized = computed(() => this.totalCount() !== undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#virtualized" }] : /* istanbul ignore next */ []));
+    #activeId = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#activeId" }] : /* istanbul ignore next */ []));
+    /**
+     * Shared overlay-listbox state machine: option collection, trigger / anchor /
+     * content registries + ids, DOM-focus navigation, the open / close machine,
+     * the initial-focus / close-reason state, and the dismiss / auto-focus emit
+     * forwarders. The value-specific behaviour (`isSelected`, `activate`,
+     * `focusSelectedOption`, typeahead, the virtualized activedescendant path,
+     * `commitOnTab`'s value set) stays in this root; close-time virtualized
+     * cleanup and the post-navigate scroll / `selectionFollowsFocus` move are
+     * threaded through the controller's side-effect callbacks.
+     */
+    #controller = new ListboxOverlayController(this.#idGen, {
+        idPrefix: 'for-select',
+        multipleAnchorsError: '[forty-cdk/select] Multiple [forSelectAnchor] inside the same [forSelect]; only one is allowed.',
+        defaultInitialFocus: 'selected',
+        effectiveDisabled: this.effectiveDisabled,
+        setOpen: (open) => this.open.set(open),
+        isOpen: () => this.open(),
+        emit: {
+            escapeKeyDown: this.escapeKeyDown,
+            pointerDownOutside: this.pointerDownOutside,
+            focusOutside: this.focusOutside,
+            interactOutside: this.interactOutside,
+            autoFocusOnOpen: this.autoFocusOnOpen,
+            autoFocusOnClose: this.autoFocusOnClose,
+        },
+        markTouched: () => this.markTouched(),
+        onClose: () => {
+            if (this.#virtualized()) {
+                this.#activeId.set(null);
+                this.#navigator?.resetPending();
+            }
+        },
+        onNavigateFocus: (target) => {
+            target.host.scrollIntoView?.({ block: 'nearest' });
+            if (!this.multiple() && this.selectionFollowsFocus() && !this.readonly()) {
+                this.#setSingle(target.value());
+            }
+        },
+        onUnregisterOption: (handle) => {
+            if (this.#virtualized() && this.#activeId() === handle.id()) {
+                this.#activeId.set(null);
+            }
+        },
+    });
+    triggerId = this.#controller.triggerId;
+    contentId = this.#controller.contentId;
+    initialFocus = this.#controller.initialFocus;
+    lastCloseReason = this.#controller.lastCloseReason;
+    trigger = this.#controller.trigger;
+    /**
+     * Element floating-ui anchors the listbox against. Prefers an optional
+     * `[forSelectAnchor]` when registered, otherwise falls back to the trigger
+     * so existing selects without an anchor keep their behavior. Decoupled from
+     * `trigger` so the trigger keeps driving `aria-controls`, the click toggle,
+     * focus return, and its dismissal exemption regardless of where the listbox
+     * paints.
+     */
+    anchor = this.#controller.anchor;
+    content = this.#controller.content;
+    options = this.#controller.options;
+    /** The active option's `id` in the virtualized path, `null` in the default path. */
+    activeDescendantId = computed(() => this.#virtualized() ? this.#activeId() : null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "activeDescendantId" }] : /* istanbul ignore next */ []));
+    #navigator = null;
+    #requireNavigator() {
+        return (this.#navigator ??= new SelectVirtualizedNavigator({
+            items: this.options,
+            totalCount: this.totalCount,
+            visibleRange: this.visibleRange,
+            loop: this.loop,
+            getActiveId: () => this.#activeId(),
+            setActiveId: (id) => this.#activeId.set(id),
+            emitScrollToIndex: (idx) => this.scrollToIndex.emit(idx),
+        }));
+    }
+    /**
+     * Persisted snapshot of the registered options as `{ value, label }` tuples,
+     * keyed internally by serialized form value. Drives closed-state typeahead
+     * and `[forSelectValue]` label rendering — the live `options` registry is
+     * empty whenever `[forSelectContent]` is unmounted, so the snapshot carries
+     * the last non-empty option set across close → re-open cycles.
+     *
+     * A `linkedSignal` that folds the live option set on every `options()`
+     * change: when the listbox unmounts (`items().length === 0`) it returns the
+     * previous accumulator unchanged so labels stay resolvable while closed. Each
+     * option's `label` is itself a `Signal<string>`, so this never reads
+     * `textContent` from inside the fold — the canonical replacement for the
+     * previous `afterEveryRender(() => signal.set(...))` snapshot (no
+     * state-propagation inside an `effect`). A statically-rendered option that
+     * registers before its `[value]` binding is written is skipped this fold and
+     * folded in on the re-run the binding triggers (see {@link #readHandleValue}).
+     */
+    #cachedOptions = linkedSignal({ ...(ngDevMode ? { debugName: "#cachedOptions" } : /* istanbul ignore next */ {}), source: () => this.options(),
+        computation: (items, prev) => {
+            if (items.length === 0) {
+                return prev?.value ?? [];
+            }
+            const toFormValue = this.itemToFormValue();
+            const merged = new Map();
+            for (const entry of prev?.value ?? []) {
+                merged.set(toFormValue(entry.value), entry);
+            }
+            for (const item of items) {
+                const value = this.#readHandleValue(item);
+                if (value === NO_VALUE) {
+                    continue;
+                }
+                merged.set(toFormValue(value), { value, label: item.label() });
+            }
+            return [...merged.values()];
+        } });
+    /**
+     * Trimmed display labels of the selected values, in selection order. Pure
+     * derivation: when `[itemToLabel]` is supplied it is authoritative; otherwise
+     * resolve from the persisted option snapshot, then the serialized form value
+     * so non-string items still render meaningfully on a cold cache.
+     *
+     * The snapshot's labels come from each option's reactive `label` signal,
+     * which reads the rendered `textContent`. `textContent` is not a signal, so a
+     * label whose rendered text changes without a value change does not self-heal
+     * here — supply `[itemToLabel]` for a pure signal derivation that observes
+     * label changes directly.
+     */
+    selectedLabels = computed(() => {
+        const values = this.value();
+        if (values.length === 0) {
+            return [];
+        }
+        // When `[itemToLabel]` is supplied it is authoritative: the label resolves
+        // without the listbox mounted, so a pre-set object value renders correctly
+        // on first paint in the documented `@if (open())` pattern and never flickers
+        // from a serialized id to the real label once the listbox is first opened.
+        const itemToLabel = this.itemToLabel();
+        if (itemToLabel) {
+            return values.map(itemToLabel);
+        }
+        const cached = this.#cachedOptions();
+        const toFormValue = this.itemToFormValue();
+        const cachedByKey = new Map();
+        for (const o of cached) {
+            cachedByKey.set(toFormValue(o.value), o);
+        }
+        const labels = [];
+        for (const v of values) {
+            const key = toFormValue(v);
+            const opt = cachedByKey.get(key);
+            labels.push(opt ? opt.label : typeof v === 'string' ? v : key);
+        }
+        return labels;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "selectedLabels" }] : /* istanbul ignore next */ []));
+    selectedOptionEl = computed(() => {
+        const values = this.value();
+        if (values.length === 0) {
+            return null;
+        }
+        const items = this.options();
+        const toFormValue = this.itemToFormValue();
+        const byKey = new Map();
+        for (const o of items) {
+            byKey.set(toFormValue(o.value()), o);
+        }
+        for (const v of values) {
+            const opt = byKey.get(toFormValue(v));
+            if (opt) {
+                return opt.host;
+            }
+        }
+        return null;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "selectedOptionEl" }] : /* istanbul ignore next */ []));
+    fieldLabelledElement() {
+        return this.trigger();
+    }
+    fieldLabelledElementId() {
+        return this.triggerId();
+    }
+    /**
+     * Read an option handle's `value()` inside the snapshot fold, tolerating the
+     * NG0950 thrown while a statically-rendered option is between registering
+     * (its constructor, during the content view's creation pass) and having its
+     * `input.required` `[value]` binding written (that view's update pass). The
+     * fold's prime read can run in that gap, so a static option above a `@for`
+     * list would otherwise hard-crash on open. Returns {@link NO_VALUE} in that
+     * window; the fold skips the option and folds it in on the re-run the binding
+     * triggers (the required-input producer is accessed before the read throws,
+     * so the dependency is still tracked). Any non-NG0950 error propagates.
+     */
+    #readHandleValue(item) {
+        try {
+            return item.value();
+        }
+        catch (error) {
+            if (isRequiredInputUnset(error)) {
+                return NO_VALUE;
+            }
+            throw error;
+        }
+    }
+    constructor() {
+        super();
+        injectHiddenInput({
+            name: this.name,
+            values: this.value,
+            serialize: (item) => this.itemToFormValue()(item),
+            disabled: this.effectiveDisabled,
+        });
+        // Prime the snapshot fold while the listbox is open so its `linkedSignal`
+        // `prev` slot is seeded with the live options before they unmount — closed-
+        // state typeahead and `[forSelectValue]` then resolve labels even when no
+        // `[forSelectValue]` pulls the cache during the open cycle. A read, not a
+        // write: this is a legitimate side effect (forcing the lazy fold to run),
+        // not state propagation inside an `effect`.
+        effect(() => {
+            if (this.open()) {
+                this.#cachedOptions();
+            }
+        });
+        effect(() => {
+            this.options();
+            if (!this.#virtualized()) {
+                return;
+            }
+            const navigator = this.#requireNavigator();
+            navigator.prime();
+            navigator.tryResolvePending();
+        });
+    }
+    setInitialFocus(target) {
+        this.#controller.setInitialFocus(target);
+    }
+    registerTrigger(el) {
+        this.#controller.registerTrigger(el);
+    }
+    unregisterTrigger(el) {
+        this.#controller.unregisterTrigger(el);
+    }
+    registerAnchor(el) {
+        this.#controller.registerAnchor(el);
+    }
+    unregisterAnchor(el) {
+        this.#controller.unregisterAnchor(el);
+    }
+    registerContent(el) {
+        this.#controller.registerContent(el);
+    }
+    unregisterContent(el) {
+        this.#controller.unregisterContent(el);
+    }
+    registerOption(handle) {
+        this.#controller.registerOption(handle);
+    }
+    unregisterOption(handle) {
+        this.#controller.unregisterOption(handle);
+    }
+    isSelected(v) {
+        return isInArray(this.value(), v, this.isItemEqualToValue());
+    }
+    #setSingle(v) {
+        if (this.value().length === 1 && this.isSelected(v)) {
+            return;
+        }
+        this.value.set([v]);
+    }
+    activate(v) {
+        if (this.effectiveDisabled() || this.readonly()) {
+            return;
+        }
+        if (this.multiple()) {
+            this.value.set(toggleInArray(this.value(), v, this.isItemEqualToValue()));
+            // Multi-select stays open — consumer closes via outside pointer / Escape / Tab.
+            return;
+        }
+        // Single-mode: idempotent select + close. Skip the redundant set (and its
+        // `valueChange` emission) when the same sole value is already selected.
+        this.#setSingle(v);
+        this.closeMenu('select');
+    }
+    navigate(currentOption, action) {
+        this.#controller.navigate(currentOption, action, this.loop());
+    }
+    handleTypeahead(event) {
+        if (!this.#typeahead.handle(event)) {
+            return;
+        }
+        const match = findTypeaheadMatch(this.options(), { buffer: this.#typeahead.buffer(), repeated: false, anchorIndex: -1 }, (o) => o.host.textContent ?? '', (o) => o.disabled());
+        match?.host.focus();
+    }
+    handleClosedTypeahead(event) {
+        // Only single-mode replicates native <select>'s "type-to-select" behavior.
+        // Multi-select is ambiguous (which one wins?) — caller falls back to opening.
+        if (this.multiple() || this.effectiveDisabled() || this.readonly()) {
+            return false;
+        }
+        if (!this.#closedTypeahead.handle(event)) {
+            return false;
+        }
+        const buffer = this.#closedTypeahead.buffer().toLowerCase();
+        if (!buffer) {
+            return true;
+        }
+        // Closed-state lookup goes through the cached snapshot — `[forSelectContent]`
+        // is unmounted, so the live `options` registry is empty here. The cache
+        // populates the first time the listbox opens and renders options.
+        const cached = this.#cachedOptions();
+        const match = cached.find((o) => o.label.toLowerCase().startsWith(buffer));
+        if (match) {
+            this.value.set([match.value]);
+        }
+        return true;
+    }
+    focusFirstEnabledOption() {
+        return this.#controller.focusFirstEnabledOption();
+    }
+    focusLastEnabledOption() {
+        return this.#controller.focusLastEnabledOption();
+    }
+    focusSelectedOption() {
+        const values = this.value();
+        if (values.length === 0) {
+            return false;
+        }
+        const equals = this.isItemEqualToValue();
+        const items = this.options();
+        for (const v of values) {
+            const opt = items.find((o) => equals(o.value(), v) && !o.disabled());
+            if (opt) {
+                opt.host.focus();
+                return true;
+            }
+        }
+        return false;
+    }
+    toggle(initialFocus = 'selected') {
+        this.#controller.toggle(initialFocus);
+    }
+    openMenu(initialFocus = 'selected') {
+        this.#controller.openMenu(initialFocus);
+    }
+    closeMenu(reason) {
+        this.#controller.closeMenu(reason);
+    }
+    commitOnTab(value) {
+        if (this.effectiveDisabled()) {
+            return;
+        }
+        if (!this.multiple() && !this.readonly()) {
+            this.#setSingle(value);
+        }
+        // Move focus to the trigger BEFORE the unmount + close so the browser's
+        // Tab default action has a stable active element to advance from. The
+        // content's `DestroyRef` reads `lastCloseReason() === 'tab'` and skips
+        // its own re-focus — otherwise it would steal focus back from wherever
+        // the browser advanced it.
+        this.#controller.focusTrigger();
+        this.closeMenu('tab');
+    }
+    emitEscapeKeyDown(event) {
+        this.#controller.emitEscapeKeyDown(event, this.dismissible(), 'escape');
+    }
+    /**
+     * Outside-interaction emit forwarders. The shared `#pendingOutsideVeto`
+     * reuse between the specific outside channels and the composite
+     * `interactOutside` lives in `injectOverlayShell`; these only fire the
+     * matching output with the veto the shell built.
+     */
+    emitPointerDownOutside(veto) {
+        this.#controller.emitPointerDownOutside(veto);
+    }
+    emitFocusOutside(veto) {
+        this.#controller.emitFocusOutside(veto);
+    }
+    emitInteractOutside(veto) {
+        this.#controller.emitInteractOutside(veto);
+    }
+    /** Modal-path Escape forwarder: emit only; the modal shell owns the close. */
+    forwardEscapeKeyDown(veto) {
+        this.#controller.forwardEscapeKeyDown(veto);
+    }
+    /**
+     * Implicit close requested by the shell after an un-vetoed outside
+     * interaction. Marks the control touched (mirroring the trigger blur) and
+     * closes with the channel's reason.
+     */
+    requestClose(reason) {
+        this.#controller.requestClose(reason);
+    }
+    emitAutoFocusOnOpen() {
+        return this.#controller.emitAutoFocusOnOpen();
+    }
+    emitAutoFocusOnClose() {
+        return this.#controller.emitAutoFocusOnClose();
+    }
+    markTouched() {
+        super.markTouched();
+    }
+    seedVirtualizedInitialFocus() {
+        if (!this.#virtualized()) {
+            return;
+        }
+        const navigator = this.#requireNavigator();
+        const committed = this.#committedIndex(navigator);
+        if (committed !== null) {
+            navigator.seedActive(committed);
+            return;
+        }
+        navigator.navigate('first');
+    }
+    handleVirtualizedKeydown(event) {
+        if (!this.#virtualized() || this.effectiveDisabled()) {
+            return;
+        }
+        if (event.key === 'Tab') {
+            if (this.modal()) {
+                return;
+            }
+            this.#commitActiveDescendantOnTab();
+            return;
+        }
+        if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            this.#activateActiveDescendant();
+            return;
+        }
+        const action = resolveListNavigation(event, {
+            orientation: this.orientation(),
+            dir: this.dir(),
+            pageKeys: true,
+        });
+        if (action) {
+            event.preventDefault();
+            this.#requireNavigator().navigate(action);
+            return;
+        }
+        this.#typeaheadVirtualized(event);
+    }
+    notifyOptionClick(optionId) {
+        if (!this.#virtualized()) {
+            return;
+        }
+        this.#activeId.set(optionId);
+        this.content()?.focus();
+    }
+    #committedIndex(navigator) {
+        const values = this.value();
+        if (values.length === 0) {
+            return null;
+        }
+        const equals = this.isItemEqualToValue();
+        const snapshot = navigator.snapshotByPos();
+        for (const v of values) {
+            for (const [pos, entry] of snapshot) {
+                if (!entry.disabled && equals(entry.value, v)) {
+                    return pos;
+                }
+            }
+        }
+        return null;
+    }
+    #activateActiveDescendant() {
+        const id = this.#activeId();
+        if (id === null) {
+            return;
+        }
+        const handle = this.options().find((o) => o.id() === id);
+        if (!handle || handle.disabled()) {
+            return;
+        }
+        this.activate(handle.value());
+    }
+    #commitActiveDescendantOnTab() {
+        const id = this.#activeId();
+        const handle = id === null ? undefined : this.options().find((o) => o.id() === id);
+        if (handle && !handle.disabled()) {
+            this.commitOnTab(handle.value());
+            return;
+        }
+        this.closeMenu('tab');
+    }
+    #typeaheadVirtualized(event) {
+        if (!this.#typeahead.handle(event)) {
+            return;
+        }
+        const match = findTypeaheadMatch(this.options(), { buffer: this.#typeahead.buffer(), repeated: false, anchorIndex: -1 }, (o) => o.host.textContent ?? '', (o) => o.disabled());
+        if (match) {
+            this.#activeId.set(match.id());
+            match.host.scrollIntoView?.({ block: 'nearest' });
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelect, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForSelect, isStandalone: true, selector: "[forSelect]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, isItemEqualToValue: { classPropertyName: "isItemEqualToValue", publicName: "isItemEqualToValue", isSignal: true, isRequired: false, transformFunction: null }, itemToFormValue: { classPropertyName: "itemToFormValue", publicName: "itemToFormValue", isSignal: true, isRequired: false, transformFunction: null }, itemToLabel: { classPropertyName: "itemToLabel", publicName: "itemToLabel", isSignal: true, isRequired: false, transformFunction: null }, open: { classPropertyName: "open", publicName: "open", isSignal: true, isRequired: false, transformFunction: null }, multiple: { classPropertyName: "multiple", publicName: "multiple", isSignal: true, isRequired: false, transformFunction: null }, modal: { classPropertyName: "modal", publicName: "modal", isSignal: true, isRequired: false, transformFunction: null }, position: { classPropertyName: "position", publicName: "position", isSignal: true, isRequired: false, transformFunction: null }, side: { classPropertyName: "side", publicName: "side", isSignal: true, isRequired: false, transformFunction: null }, align: { classPropertyName: "align", publicName: "align", isSignal: true, isRequired: false, transformFunction: null }, sideOffset: { classPropertyName: "sideOffset", publicName: "sideOffset", isSignal: true, isRequired: false, transformFunction: null }, alignOffset: { classPropertyName: "alignOffset", publicName: "alignOffset", isSignal: true, isRequired: false, transformFunction: null }, avoidCollisions: { classPropertyName: "avoidCollisions", publicName: "avoidCollisions", isSignal: true, isRequired: false, transformFunction: null }, collisionPadding: { classPropertyName: "collisionPadding", publicName: "collisionPadding", isSignal: true, isRequired: false, transformFunction: null }, arrowPadding: { classPropertyName: "arrowPadding", publicName: "arrowPadding", isSignal: true, isRequired: false, transformFunction: null }, sticky: { classPropertyName: "sticky", publicName: "sticky", isSignal: true, isRequired: false, transformFunction: null }, hideWhenDetached: { classPropertyName: "hideWhenDetached", publicName: "hideWhenDetached", isSignal: true, isRequired: false, transformFunction: null }, clipUntilPositioned: { classPropertyName: "clipUntilPositioned", publicName: "clipUntilPositioned", isSignal: true, isRequired: false, transformFunction: null }, loop: { classPropertyName: "loop", publicName: "loop", isSignal: true, isRequired: false, transformFunction: null }, orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, totalCount: { classPropertyName: "totalCount", publicName: "totalCount", isSignal: true, isRequired: false, transformFunction: null }, visibleRange: { classPropertyName: "visibleRange", publicName: "visibleRange", isSignal: true, isRequired: false, transformFunction: null }, _dirInput: { classPropertyName: "_dirInput", publicName: "dir", isSignal: true, isRequired: false, transformFunction: null }, selectionFollowsFocus: { classPropertyName: "selectionFollowsFocus", publicName: "selectionFollowsFocus", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, dismissible: { classPropertyName: "dismissible", publicName: "dismissible", isSignal: true, isRequired: false, transformFunction: null }, returnFocus: { classPropertyName: "returnFocus", publicName: "returnFocus", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", open: "openChange", scrollToIndex: "scrollToIndex", escapeKeyDown: "escapeKeyDown", pointerDownOutside: "pointerDownOutside", focusOutside: "focusOutside", interactOutside: "interactOutside", autoFocusOnOpen: "autoFocusOnOpen", autoFocusOnClose: "autoFocusOnClose" }, host: { properties: { "attr.data-state": "open() ? \"open\" : \"closed\"", "attr.data-disabled": "effectiveDisabled() ? \"\" : null", "attr.dir": "dir()" } }, providers: [{ provide: FOR_SELECT_CONTEXT, useExisting: ForSelect }], exportAs: ["forSelect"], usesInheritance: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelect, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelect]',
+                    exportAs: 'forSelect',
+                    host: {
+                        '[attr.data-state]': 'open() ? "open" : "closed"',
+                        '[attr.data-disabled]': 'effectiveDisabled() ? "" : null',
+                        '[attr.dir]': 'dir()',
+                    },
+                    providers: [{ provide: FOR_SELECT_CONTEXT, useExisting: ForSelect }],
+                }]
+        }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }, { type: i0.Output, args: ["valueChange"] }], isItemEqualToValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "isItemEqualToValue", required: false }] }], itemToFormValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "itemToFormValue", required: false }] }], itemToLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "itemToLabel", required: false }] }], open: [{ type: i0.Input, args: [{ isSignal: true, alias: "open", required: false }] }, { type: i0.Output, args: ["openChange"] }], multiple: [{ type: i0.Input, args: [{ isSignal: true, alias: "multiple", required: false }] }], modal: [{ type: i0.Input, args: [{ isSignal: true, alias: "modal", required: false }] }], position: [{ type: i0.Input, args: [{ isSignal: true, alias: "position", required: false }] }], side: [{ type: i0.Input, args: [{ isSignal: true, alias: "side", required: false }] }], align: [{ type: i0.Input, args: [{ isSignal: true, alias: "align", required: false }] }], sideOffset: [{ type: i0.Input, args: [{ isSignal: true, alias: "sideOffset", required: false }] }], alignOffset: [{ type: i0.Input, args: [{ isSignal: true, alias: "alignOffset", required: false }] }], avoidCollisions: [{ type: i0.Input, args: [{ isSignal: true, alias: "avoidCollisions", required: false }] }], collisionPadding: [{ type: i0.Input, args: [{ isSignal: true, alias: "collisionPadding", required: false }] }], arrowPadding: [{ type: i0.Input, args: [{ isSignal: true, alias: "arrowPadding", required: false }] }], sticky: [{ type: i0.Input, args: [{ isSignal: true, alias: "sticky", required: false }] }], hideWhenDetached: [{ type: i0.Input, args: [{ isSignal: true, alias: "hideWhenDetached", required: false }] }], clipUntilPositioned: [{ type: i0.Input, args: [{ isSignal: true, alias: "clipUntilPositioned", required: false }] }], loop: [{ type: i0.Input, args: [{ isSignal: true, alias: "loop", required: false }] }], orientation: [{ type: i0.Input, args: [{ isSignal: true, alias: "orientation", required: false }] }], totalCount: [{ type: i0.Input, args: [{ isSignal: true, alias: "totalCount", required: false }] }], visibleRange: [{ type: i0.Input, args: [{ isSignal: true, alias: "visibleRange", required: false }] }], scrollToIndex: [{ type: i0.Output, args: ["scrollToIndex"] }], _dirInput: [{ type: i0.Input, args: [{ isSignal: true, alias: "dir", required: false }] }], selectionFollowsFocus: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectionFollowsFocus", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], dismissible: [{ type: i0.Input, args: [{ isSignal: true, alias: "dismissible", required: false }] }], returnFocus: [{ type: i0.Input, args: [{ isSignal: true, alias: "returnFocus", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], escapeKeyDown: [{ type: i0.Output, args: ["escapeKeyDown"] }], pointerDownOutside: [{ type: i0.Output, args: ["pointerDownOutside"] }], focusOutside: [{ type: i0.Output, args: ["focusOutside"] }], interactOutside: [{ type: i0.Output, args: ["interactOutside"] }], autoFocusOnOpen: [{ type: i0.Output, args: ["autoFocusOnOpen"] }], autoFocusOnClose: [{ type: i0.Output, args: ["autoFocusOnClose"] }] } });
+
+/**
+ * Optional positioning anchor. When present, `[forSelectContent]` is
+ * positioned against this element instead of `[forSelectTrigger]` — useful
+ * when the trigger lives inside a decorated field box (padding, prefix icon,
+ * clear / chevron buttons) and the listbox should match the visible field
+ * rather than the inner button.
+ *
+ * Only positioning changes: the trigger still owns `aria-controls`,
+ * `aria-expanded`, the click toggle, focus return on close, and its exemption
+ * from outside-pointer dismissal. If no anchor is registered the listbox falls
+ * back to anchoring against the trigger, so existing usages are unaffected.
+ *
+ * At most one `[forSelectAnchor]` may be registered per `[forSelect]`; a second
+ * one throws.
+ *
+ * ```html
+ * <div forSelect [(value)]="v">
+ *   <div forSelectAnchor class="field-box">
+ *     <icon />
+ *     <button forSelectTrigger>…</button>
+ *     <button class="clear">×</button>
+ *   </div>
+ *   @if (open()) {
+ *     <div forSelectContent>…</div>
+ *   }
+ * </div>
+ * ```
+ */
+class ForSelectAnchor {
+    #ctx = injectSelectContext('ForSelectAnchor');
+    #host = inject(ElementRef);
+    constructor() {
+        registerHandle(this.#host.nativeElement, (el) => this.#ctx.registerAnchor(el), (el) => this.#ctx.unregisterAnchor(el));
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectAnchor, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectAnchor, isStandalone: true, selector: "[forSelectAnchor]", exportAs: ["forSelectAnchor"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectAnchor, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectAnchor]',
+                    exportAs: 'forSelectAnchor',
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Combobox button that opens the listbox. Apply on a `<button>` so
+ * Space / Enter dispatch native click events that toggle via `(click)`.
+ *
+ * Wires APG select-only combobox attributes: `role="combobox"`,
+ * `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls` pointing
+ * to the listbox. The button is exempt from the listbox's dismissable
+ * layer — clicks on it route through `(click)` instead of triggering an
+ * outside-pointer dismissal race.
+ *
+ * The root is normally resolved via DI from the enclosing `[forSelect]`.
+ * When the trigger is declared inside an `ng-template` stamped into the root
+ * (e.g. via `ngTemplateOutlet`), DI resolves at the template's declaration
+ * site and misses the root — pass it explicitly through the selector input,
+ * `routerLink`-style: `[forSelectTrigger]="root"` with `#root="forSelect"`.
+ *
+ * Keyboard:
+ * - **Click / Enter / Space** — toggle (open focuses the selected option, or first).
+ * - **ArrowDown** — open + focus selected option (or first).
+ * - **ArrowUp** — open + focus selected option (or last when none selected).
+ * - **Typeahead** (single mode only) — printable keys select the matching
+ *   option immediately without opening the listbox, mirroring native
+ *   `<select>`. In multi mode the buffered key is ignored at the trigger;
+ *   open the listbox first to typeahead-focus.
+ */
+class ForSelectTrigger {
+    #host = inject(ElementRef);
+    /**
+     * Optional explicit reference to the `[forSelect]` root, named after the
+     * selector `routerLink`-style. The bare valueless attribute keeps resolving
+     * the enclosing root via DI; pass the root explicitly
+     * (`[forSelectTrigger]="root"`, with `#root="forSelect"`) when the trigger
+     * is declared in an `ng-template` stamped inside the root — DI resolves at
+     * the template's declaration site, so the enclosing root is invisible there.
+     * The empty string (what the valueless attribute yields) is treated as unset.
+     */
+    forSelectTrigger = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "forSelectTrigger" }] : /* istanbul ignore next */ []));
+    ctx = injectSelectTriggerContext(this.forSelectTrigger);
+    constructor() {
+        const el = this.#host.nativeElement;
+        // Registration is an imperative call into the resolved root's registry,
+        // not state derivation — the effect only re-registers the element when the
+        // resolved root changes (explicit reference swapped at runtime).
+        effect((onCleanup) => {
+            const ctx = this.ctx();
+            ctx.registerTrigger(el);
+            onCleanup(() => ctx.unregisterTrigger(el));
+        });
+        reflectDisabled(computed(() => this.ctx().effectiveDisabled()));
+    }
+    onClick() {
+        this.ctx().toggle('selected');
+    }
+    onKeyDown(event) {
+        if (this.ctx().effectiveDisabled()) {
+            return;
+        }
+        if (event.key === 'ArrowDown') {
+            event.preventDefault();
+            this.ctx().openMenu('selected');
+            return;
+        }
+        if (event.key === 'ArrowUp') {
+            event.preventDefault();
+            // ArrowUp lands on the selected option if any, else the last enabled.
+            this.ctx().openMenu(this.ctx().value().length > 0 ? 'selected' : 'last');
+            return;
+        }
+        // Closed-state typeahead — single-mode shortcut to match native <select>.
+        // No-op (returns false) in multi mode or when the key isn't a printable
+        // single char, so default browser behavior (e.g. nothing) takes over.
+        this.ctx().handleClosedTypeahead(event);
+    }
+    onFocusOut(event) {
+        const next = event.relatedTarget;
+        if (next) {
+            // Focus moving into the listbox content (we just opened it) — not a leave.
+            const content = this.ctx().content();
+            if (content && content.contains(next)) {
+                return;
+            }
+            // Focus going to a sibling inside the [forSelect] wrapper — also not a leave.
+            if (this.#host.nativeElement.contains(next)) {
+                return;
+            }
+        }
+        this.ctx().markTouched();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectTrigger, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForSelectTrigger, isStandalone: true, selector: "[forSelectTrigger]", inputs: { forSelectTrigger: { classPropertyName: "forSelectTrigger", publicName: "forSelectTrigger", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "type": "button", "role": "combobox" }, listeners: { "click": "onClick()", "keydown": "onKeyDown($event)", "focusout": "onFocusOut($event)" }, properties: { "id": "ctx().triggerId()", "attr.aria-haspopup": "\"listbox\"", "attr.aria-expanded": "ctx().open() ? \"true\" : \"false\"", "attr.aria-controls": "ctx().open() ? ctx().contentId() : null", "attr.aria-disabled": "ctx().effectiveDisabled() ? \"true\" : null", "attr.aria-readonly": "ctx().readonly() ? \"true\" : null", "attr.aria-required": "ctx().required() ? \"true\" : null", "attr.aria-invalid": "ctx().invalid() ? \"true\" : null", "attr.aria-busy": "ctx().pending() ? \"true\" : null", "attr.data-state": "ctx().open() ? \"open\" : \"closed\"", "attr.data-disabled": "ctx().effectiveDisabled() ? \"\" : null" } }, exportAs: ["forSelectTrigger"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectTrigger, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectTrigger]',
+                    exportAs: 'forSelectTrigger',
+                    host: {
+                        type: 'button',
+                        role: 'combobox',
+                        '[id]': 'ctx().triggerId()',
+                        '[attr.aria-haspopup]': '"listbox"',
+                        '[attr.aria-expanded]': 'ctx().open() ? "true" : "false"',
+                        '[attr.aria-controls]': 'ctx().open() ? ctx().contentId() : null',
+                        '[attr.aria-disabled]': 'ctx().effectiveDisabled() ? "true" : null',
+                        '[attr.aria-readonly]': 'ctx().readonly() ? "true" : null',
+                        '[attr.aria-required]': 'ctx().required() ? "true" : null',
+                        '[attr.aria-invalid]': 'ctx().invalid() ? "true" : null',
+                        '[attr.aria-busy]': 'ctx().pending() ? "true" : null',
+                        '[attr.data-state]': 'ctx().open() ? "open" : "closed"',
+                        '[attr.data-disabled]': 'ctx().effectiveDisabled() ? "" : null',
+                        '(click)': 'onClick()',
+                        '(keydown)': 'onKeyDown($event)',
+                        '(focusout)': 'onFocusOut($event)',
+                    },
+                }]
+        }], ctorParameters: () => [], propDecorators: { forSelectTrigger: [{ type: i0.Input, args: [{ isSignal: true, alias: "forSelectTrigger", required: false }] }] } });
+
+/**
+ * Renders the currently-selected option's text — or the configured
+ * placeholder when nothing is selected — into its host element via
+ * `textContent`. Apply on a `<span>` (or any inline element) inside
+ * `[forSelectTrigger]`:
+ *
+ * ```html
+ * <button forSelectTrigger>
+ *   <span forSelectValue placeholder="Select fruit…"></span>
+ * </button>
+ * ```
+ *
+ * In multi mode the labels are joined by `separator` (default `', '`). For
+ * fully custom rendering, drop this directive and read
+ * `forSelect.selectedLabels()` / `forSelect.value()` from your template.
+ */
+class ForSelectValue {
+    #ctx = injectSelectContext('ForSelectValue');
+    /** Text shown when nothing is selected. Falls back to `[forSelect][placeholder]`. */
+    placeholder = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /** Joiner for multi-mode label rendering. Default `', '`. */
+    separator = input(', ', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "separator" }] : /* istanbul ignore next */ []));
+    isPlaceholder = computed(() => this.#ctx.value().length === 0, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isPlaceholder" }] : /* istanbul ignore next */ []));
+    displayText = computed(() => {
+        const labels = this.#ctx.selectedLabels();
+        if (labels.length === 0) {
+            return this.placeholder() || this.#ctx.placeholder();
+        }
+        return labels.join(this.separator());
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "displayText" }] : /* istanbul ignore next */ []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectValue, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForSelectValue, isStandalone: true, selector: "[forSelectValue]", inputs: { placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, separator: { classPropertyName: "separator", publicName: "separator", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "textContent": "displayText()", "attr.data-placeholder": "isPlaceholder() ? \"\" : null" } }, exportAs: ["forSelectValue"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectValue, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectValue]',
+                    exportAs: 'forSelectValue',
+                    host: {
+                        '[textContent]': 'displayText()',
+                        '[attr.data-placeholder]': 'isPlaceholder() ? "" : null',
+                    },
+                }]
+        }], propDecorators: { placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], separator: [{ type: i0.Input, args: [{ isSignal: true, alias: "separator", required: false }] }] } });
+
+/**
+ * The listbox surface. Carries `role="listbox"`, is portaled to
+ * `document.body`, and is positioned by `@floating-ui/dom` against the
+ * trigger.
+ *
+ * Mount/unmount of the visible content is the consumer's responsibility —
+ * wrap with `@if (open())` so `animate.enter` / `animate.leave` fire on the
+ * natural mount cycle. While mounted, a `DismissableLayer` activates
+ * (Escape, pointer-down outside, focus outside); the trigger element is
+ * exempt from outside-pointer checks so trigger clicks toggle without
+ * dismissal racing.
+ *
+ * Initial focus is sent to the selected option (`'selected'`), the first
+ * enabled option (`'first'`), or the last enabled option (`'last'`)
+ * according to the trigger's hint. On destroy, focus returns to the
+ * trigger when `returnFocus` is true.
+ *
+ * The lifecycle is owned by one of the two shared shells, picked once on
+ * construction from `[forSelect].modal`:
+ *
+ * - **non-modal (default)** — `injectOverlayShell` anchors the listbox to the
+ *   trigger and branches on `[forSelect].position`:
+ *   - `'popper'` (default) — standard `injectFloating` path with full
+ *     anchored placement (`side`, `align`, `sideOffset`,
+ *     `alignOffset`, `flip`, `shift`, `arrow`, `hideWhenDetached`).
+ *   - `'item-aligned'` — `injectItemAlignedPositioner` overlays the listbox so
+ *     the selected option's center aligns with the trigger's center. The
+ *     anchored-placement inputs are documented as no-ops in this mode.
+ * - **modal** — `injectModalShell` traps focus, inerts the background, and
+ *   locks body scroll (a centered surface the consumer positions with CSS, not
+ *   trigger-anchored). The batteries-included touch presentation. Same Escape /
+ *   outside-pointer dismiss, `dismissible` / `returnFocus` / `ariaLabel`, and
+ *   `autoFocusOnOpen` / `autoFocusOnClose` veto hooks; every anchored-
+ *   positioning input is a no-op. `aria-modal="true"` is reflected as a hint —
+ *   the real modality comes from the `inert` siblings the shell applies (the
+ *   surface keeps `role="listbox"`, for which several screen readers ignore
+ *   `aria-modal`).
+ *
+ * Mount/unmount of the visible content is the consumer's responsibility —
+ * wrap with `@if (open())` so `animate.enter` / `animate.leave` fire on the
+ * natural mount cycle.
+ */
+class ForSelectContent {
+    ctx = injectSelectContext('ForSelectContent');
+    #host = inject(ElementRef);
+    constructor() {
+        const ctx = this.ctx;
+        registerHandle(this.#host.nativeElement, (el) => ctx.registerContent(el), (el) => ctx.unregisterContent(el));
+        // Primitive-owned initial-focus algorithm shared by both shells.
+        // `'selected'` falls back to the first enabled option when nothing is
+        // selected; returns `false` so the shell focuses the container on a miss.
+        const focusInitial = () => {
+            if (ctx.totalCount() !== undefined) {
+                this.#host.nativeElement.focus();
+                ctx.seedVirtualizedInitialFocus();
+                return true;
+            }
+            const target = ctx.initialFocus();
+            if (target === 'selected') {
+                return ctx.focusSelectedOption() || ctx.focusFirstEnabledOption();
+            }
+            if (target === 'last') {
+                return ctx.focusLastEnabledOption();
+            }
+            return ctx.focusFirstEnabledOption();
+        };
+        // Static branch — `modal` (and `position`) is read once on construction.
+        // Switching modes at runtime would require re-creating the directive
+        // (mount / unmount cycle), which is the expected pattern for primitives
+        // whose surface is structurally different. The surface mounts lazily via
+        // `@if (open())`, well after `modal` settles.
+        if (ctx.modal()) {
+            injectModalShell({
+                modal: ctx.modal,
+                returnFocus: ctx.returnFocus,
+                // The trap owns Tab; the shell runs `focusInitial()` (selected →
+                // first → last) instead of its own first-focusable move.
+                initialFocus: {
+                    move: focusInitial,
+                    veto: () => ctx.emitAutoFocusOnOpen(),
+                },
+                autoFocusOnClose: () => (event) => {
+                    if (ctx.emitAutoFocusOnClose()) {
+                        event.preventDefault();
+                    }
+                },
+                dismiss: {
+                    dismissible: ctx.dismissible,
+                    // The shell builds the veto and calls this when not vetoed; mirror
+                    // the anchored path's touched-on-dismiss behaviour.
+                    requestClose: (reason) => {
+                        ctx.markTouched();
+                        ctx.closeMenu(reason);
+                    },
+                    emitEscapeKeyDown: (veto) => ctx.forwardEscapeKeyDown(veto),
+                    emitPointerDownOutside: (veto) => ctx.emitPointerDownOutside(veto),
+                    emitFocusOutside: (veto) => ctx.emitFocusOutside(veto),
+                    emitInteractOutside: (veto) => ctx.emitInteractOutside(veto),
+                },
+            });
+            return;
+        }
+        const positioner = ctx.position() === 'item-aligned'
+            ? {
+                kind: 'item-aligned',
+                reference: ctx.anchor,
+                open: ctx.open,
+                selectedOption: ctx.selectedOptionEl,
+                collisionPadding: ctx.collisionPadding,
+            }
+            : {
+                kind: 'floating',
+                reference: ctx.anchor,
+                open: ctx.open,
+                side: ctx.side,
+                align: ctx.align,
+                sideOffset: ctx.sideOffset,
+                alignOffset: ctx.alignOffset,
+                avoidCollisions: ctx.avoidCollisions,
+                collisionPadding: ctx.collisionPadding,
+                arrowPadding: ctx.arrowPadding,
+                sticky: ctx.sticky,
+                hideWhenDetached: ctx.hideWhenDetached,
+                clipUntilPositioned: ctx.clipUntilPositioned,
+            };
+        injectOverlayShell({
+            positioner,
+            dismiss: {
+                dismissible: ctx.dismissible,
+                // Mirror the modal path's touched-on-dismiss behaviour.
+                requestClose: (reason) => {
+                    ctx.markTouched();
+                    ctx.closeMenu(reason);
+                },
+                emitEscapeKeyDown: (event) => ctx.emitEscapeKeyDown(event),
+                emitPointerDownOutside: (veto) => ctx.emitPointerDownOutside(veto),
+                emitFocusOutside: (veto) => ctx.emitFocusOutside(veto),
+                emitInteractOutside: (veto) => ctx.emitInteractOutside(veto),
+                // Trigger button is exempt — its own click handler toggles open/close;
+                // without exemption pointer-down-outside would race and double-close.
+                exemptElements: () => {
+                    const t = ctx.trigger();
+                    return t ? [t] : [];
+                },
+            },
+            initialFocus: {
+                move: focusInitial,
+                veto: () => ctx.emitAutoFocusOnOpen(),
+            },
+            returnFocus: {
+                enabled: ctx.returnFocus,
+                target: () => ctx.trigger(),
+                // `(autoFocusOnClose)` lets the consumer veto the return-focus.
+                veto: () => ctx.emitAutoFocusOnClose(),
+                // Skip on `'tab'` closes — Tab already moved focus to the trigger
+                // and let the browser advance from there; re-focusing would steal
+                // it back.
+                skip: () => ctx.lastCloseReason() === 'tab',
+            },
+        });
+    }
+    onKeyDown(event) {
+        if (this.ctx.totalCount() !== undefined) {
+            this.ctx.handleVirtualizedKeydown(event);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectContent, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectContent, isStandalone: true, selector: "[forSelectContent]", host: { attributes: { "role": "listbox" }, listeners: { "keydown": "onKeyDown($event)" }, properties: { "attr.tabindex": "ctx.totalCount() !== undefined ? \"0\" : \"-1\"", "attr.aria-activedescendant": "ctx.activeDescendantId()", "id": "ctx.contentId()", "attr.aria-labelledby": "ctx.ariaLabel() ? null : ctx.triggerId()", "attr.aria-label": "ctx.ariaLabel()", "attr.aria-modal": "ctx.modal() ? \"true\" : null", "attr.aria-multiselectable": "ctx.multiple() ? \"true\" : null", "attr.aria-orientation": "ctx.orientation()", "attr.data-state": "ctx.open() ? \"open\" : \"closed\"", "attr.data-orientation": "ctx.orientation()" } }, exportAs: ["forSelectContent"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectContent, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectContent]',
+                    exportAs: 'forSelectContent',
+                    host: {
+                        role: 'listbox',
+                        '[attr.tabindex]': 'ctx.totalCount() !== undefined ? "0" : "-1"',
+                        '[attr.aria-activedescendant]': 'ctx.activeDescendantId()',
+                        '[id]': 'ctx.contentId()',
+                        '[attr.aria-labelledby]': 'ctx.ariaLabel() ? null : ctx.triggerId()',
+                        '[attr.aria-label]': 'ctx.ariaLabel()',
+                        '[attr.aria-modal]': 'ctx.modal() ? "true" : null',
+                        '[attr.aria-multiselectable]': 'ctx.multiple() ? "true" : null',
+                        '[attr.aria-orientation]': 'ctx.orientation()',
+                        '[attr.data-state]': 'ctx.open() ? "open" : "closed"',
+                        '[attr.data-orientation]': 'ctx.orientation()',
+                        '(keydown)': 'onKeyDown($event)',
+                    },
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Injection key the `[forSelectIndicator]` uses to resolve its parent option,
+ * decoupled from the concrete `ForSelectOption` class. `ForSelectOption`
+ * provides itself under this token, so a design system wrapping the option by
+ * subclassing re-points it at the subclass with a single provider
+ * (`{ provide: FOR_SELECT_OPTION, useExisting: MtxSelectOption }`) and the
+ * indicator keeps resolving — see `docs/wrapping-form-primitives.md`.
+ */
+const FOR_SELECT_OPTION = new InjectionToken('FOR_SELECT_OPTION');
+/**
+ * One option inside a `[forSelectContent]`. Apply on a `<button type="button">`
+ * so Space / Enter activation come from native button behavior — printable
+ * keys fall through to the listbox for typeahead matching.
+ *
+ * Generic over the option value type `T` (default `string`). Inferred from
+ * the `[value]` binding so consumers can pass either primitive ids or full
+ * objects (`[value]="city"` infers `T = City`); the parent `[forSelect]`
+ * must be parameterized over the same `T`. The parent's
+ * `[isItemEqualToValue]` decides how options are matched against the
+ * committed selection.
+ *
+ * Click activates: in single mode the value replaces `[(value)]` and the
+ * listbox closes; in multi mode the value toggles in/out and the listbox
+ * stays open.
+ *
+ * Keyboard while focused:
+ * - **Enter / Space** — activate (via native button click).
+ * - **ArrowDown / ArrowUp / Home / End** — move focus inside the listbox.
+ * - **Tab / Shift+Tab** — commit the focused option (single mode) and let
+ *   the browser advance focus to the next / previous focusable, mirroring
+ *   the WAI-ARIA select-only combobox pattern and native `<select>`.
+ * - **Escape** — close the listbox.
+ * - **Typeahead** — printable keys match by text content.
+ */
+class ForSelectOption {
+    #ctx = injectSelectContext('ForSelectOption');
+    #host = inject(ElementRef);
+    /**
+     * Stable identifier serialized into `[(value)]` and the hidden input.
+     * Defaults to `string` for back-compat; bind an object to specialize the
+     * parent `[forSelect]` over a richer `T`. The parent's
+     * `[isItemEqualToValue]` decides how options are matched against the
+     * committed selection.
+     */
+    value = input.required(/* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
+    disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Zero-based absolute position of this option in the full source data.
+     * Required in the virtualized path — drives `aria-posinset` and the parent's
+     * position snapshot. Leave unset (default `null`) outside it.
+     */
+    posInSet = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "posInSet" }] : /* istanbul ignore next */ []));
+    id = hostId('for-select-option');
+    selected = computed(() => this.#ctx.isSelected(this.value()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "selected" }] : /* istanbul ignore next */ []));
+    effectiveDisabled = computed(() => this.disabled() || this.#ctx.effectiveDisabled(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "effectiveDisabled" }] : /* istanbul ignore next */ []));
+    ariaSetSize = computed(() => {
+        const total = this.#ctx.totalCount();
+        return total === undefined ? null : String(total);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaSetSize" }] : /* istanbul ignore next */ []));
+    ariaPosInSet = computed(() => {
+        if (this.#ctx.totalCount() === undefined) {
+            return null;
+        }
+        const pos = this.posInSet();
+        return pos === null ? null : String(pos + 1);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaPosInSet" }] : /* istanbul ignore next */ []));
+    #focused = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#focused" }] : /* istanbul ignore next */ []));
+    /**
+     * True when this option is the active candidate — DOM-focused in the
+     * default path, or `aria-activedescendant` in the virtualized path.
+     * Reflected as `data-highlighted`.
+     */
+    highlighted = computed(() => {
+        const activeId = this.#ctx.activeDescendantId();
+        if (activeId !== null) {
+            return activeId === this.id();
+        }
+        return this.#focused();
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "highlighted" }] : /* istanbul ignore next */ []));
+    /**
+     * Reactive effective label exposed on the handle — the trimmed `textContent`
+     * of the host. Mirrors `ForComboboxOption`'s `#effectiveLabel` so the root
+     * can fold a per-option `Signal<string>` into its persisted snapshot instead
+     * of reading `textContent` from inside a `computed`. `textContent` is not a
+     * signal, so this still does not self-heal on a text-only change with no
+     * value change — supply `[forSelect][itemToLabel]` for a pure signal
+     * derivation when the label can change without the value.
+     */
+    #effectiveLabel = computed(() => (this.#host.nativeElement.textContent ?? '').trim(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#effectiveLabel" }] : /* istanbul ignore next */ []));
+    constructor() {
+        const handle = {
+            host: this.#host.nativeElement,
+            value: this.value,
+            label: this.#effectiveLabel,
+            disabled: this.effectiveDisabled,
+            id: this.id,
+            posInSet: this.posInSet,
+        };
+        registerHandle(handle, (h) => this.#ctx.registerOption(h), (h) => this.#ctx.unregisterOption(h));
+    }
+    onClick() {
+        if (this.effectiveDisabled() || this.#ctx.readonly()) {
+            return;
+        }
+        this.#ctx.activate(this.value());
+        this.#ctx.notifyOptionClick(this.id());
+    }
+    onFocus() {
+        this.#focused.set(true);
+    }
+    onBlur() {
+        this.#focused.set(false);
+    }
+    onKeyDown(event) {
+        if (this.effectiveDisabled()) {
+            return;
+        }
+        if (event.key === 'Tab') {
+            // In modal mode the focus trap owns Tab (it cycles focus inside the
+            // surface in the capture phase); committing + closing here would defeat
+            // the trap. Bail and let the trap's `preventDefault` keep focus inside.
+            if (this.#ctx.modal()) {
+                return;
+            }
+            // APG (combobox-select-only): Tab commits the focused option and lets
+            // the browser advance focus to the next / previous focusable. Do NOT
+            // preventDefault — the browser's Tab default uses the focus we just
+            // moved to the trigger as the starting point.
+            this.#ctx.commitOnTab(this.value());
+            return;
+        }
+        const action = resolveListNavigation(event, {
+            orientation: this.#ctx.orientation(),
+            dir: this.#ctx.dir(),
+            pageKeys: true,
+        });
+        if (action) {
+            event.preventDefault();
+            this.#ctx.navigate(this.#host.nativeElement, action);
+            return;
+        }
+        this.#ctx.handleTypeahead(event);
+    }
+    onPointerDown(event) {
+        if (this.#ctx.totalCount() === undefined) {
+            return;
+        }
+        event.preventDefault();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectOption, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForSelectOption, isStandalone: true, selector: "[forSelectOption]", inputs: { value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: true, 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", "type": "button", "tabindex": "-1" }, listeners: { "click": "onClick()", "keydown": "onKeyDown($event)", "focus": "onFocus()", "blur": "onBlur()", "pointerdown": "onPointerDown($event)" }, properties: { "id": "id()", "attr.aria-selected": "selected() ? \"true\" : \"false\"", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.data-state": "selected() ? \"checked\" : \"unchecked\"", "attr.data-disabled": "effectiveDisabled() ? \"\" : null", "attr.aria-setsize": "ariaSetSize()", "attr.aria-posinset": "ariaPosInSet()", "attr.data-highlighted": "highlighted() ? \"\" : null" } }, providers: [{ provide: FOR_SELECT_OPTION, useExisting: ForSelectOption }], exportAs: ["forSelectOption"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectOption, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectOption]',
+                    exportAs: 'forSelectOption',
+                    providers: [{ provide: FOR_SELECT_OPTION, useExisting: ForSelectOption }],
+                    host: {
+                        role: 'option',
+                        type: 'button',
+                        tabindex: '-1',
+                        '[id]': 'id()',
+                        '[attr.aria-selected]': 'selected() ? "true" : "false"',
+                        '[attr.aria-disabled]': 'effectiveDisabled() ? "true" : null',
+                        '[attr.data-state]': 'selected() ? "checked" : "unchecked"',
+                        '[attr.data-disabled]': 'effectiveDisabled() ? "" : null',
+                        '[attr.aria-setsize]': 'ariaSetSize()',
+                        '[attr.aria-posinset]': 'ariaPosInSet()',
+                        '[attr.data-highlighted]': 'highlighted() ? "" : null',
+                        '(click)': 'onClick()',
+                        '(keydown)': 'onKeyDown($event)',
+                        '(focus)': 'onFocus()',
+                        '(blur)': 'onBlur()',
+                        '(pointerdown)': 'onPointerDown($event)',
+                    },
+                }]
+        }], ctorParameters: () => [], propDecorators: { value: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: true }] }], 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 `[forSelectOption]`. The directive flips a
+ * `[hidden]` host binding so the consumer can keep the checkmark / icon
+ * inline without extra `@if` glue:
+ *
+ * ```html
+ * <button forSelectOption value="apple">
+ *   <span forSelectIndicator>✓</span>
+ *   Apple
+ * </button>
+ * ```
+ *
+ * Reflects the parent option's `data-state` (`"checked" | "unchecked"`) so
+ * the consumer can also style it from CSS. Visibility while unselected is
+ * enforced with an inline `display: none` (which beats any author `display`
+ * rule a consumer applies via a class) in addition to the `hidden` attribute
+ * that removes it from the a11y tree.
+ */
+class ForSelectIndicator {
+    option = injectParentOption();
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectIndicator, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectIndicator, isStandalone: true, selector: "[forSelectIndicator]", host: { attributes: { "aria-hidden": "true" }, properties: { "attr.data-state": "option.selected() ? \"checked\" : \"unchecked\"", "hidden": "!option.selected()", "style.display": "option.selected() ? null : \"none\"" } }, exportAs: ["forSelectIndicator"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectIndicator, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectIndicator]',
+                    exportAs: 'forSelectIndicator',
+                    host: {
+                        'aria-hidden': 'true',
+                        '[attr.data-state]': 'option.selected() ? "checked" : "unchecked"',
+                        '[hidden]': '!option.selected()',
+                        '[style.display]': 'option.selected() ? null : "none"',
+                    },
+                }]
+        }] });
+function injectParentOption() {
+    const option = inject(FOR_SELECT_OPTION, { optional: true });
+    if (!option) {
+        throw new Error('[forty-cdk/select] ForSelectIndicator must be used inside a [forSelectOption] element.');
+    }
+    return option;
+}
+
+/**
+ * Optional grouping wrapper inside a `[forSelectContent]`. Renders
+ * `role="group"` and references the descendant `[forSelectGroupLabel]`
+ * (if any) via `aria-labelledby`. Options inside a group still register
+ * with the root listbox normally, so keyboard navigation traverses across
+ * groups in DOM order without special handling.
+ */
+class ForSelectGroup {
+    #labelId = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#labelId" }] : /* istanbul ignore next */ []));
+    /** The id of the registered group label (or `null` if none). */
+    labelId = this.#labelId.asReadonly();
+    /** Called by `ForSelectGroupLabel` on mount. */
+    registerLabel(id) {
+        this.#labelId.set(id);
+    }
+    /** Called by `ForSelectGroupLabel` on destroy. Idempotent. */
+    unregisterLabel(id) {
+        if (this.#labelId() === id) {
+            this.#labelId.set(null);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectGroup, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectGroup, isStandalone: true, selector: "[forSelectGroup]", host: { attributes: { "role": "group" }, properties: { "attr.aria-labelledby": "labelId() || null" } }, exportAs: ["forSelectGroup"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectGroup, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectGroup]',
+                    exportAs: 'forSelectGroup',
+                    host: {
+                        role: 'group',
+                        '[attr.aria-labelledby]': 'labelId() || null',
+                    },
+                }]
+        }] });
+
+/**
+ * Visible label for a `[forSelectGroup]`. Generates a stable id and
+ * registers with its parent group so the group's `aria-labelledby` points
+ * at this element. Apply on whatever heading element fits the design
+ * (often `<div>` styled as a small caption).
+ */
+class ForSelectGroupLabel {
+    /** Stable host id used by the parent group's `aria-labelledby`. */
+    id;
+    constructor() {
+        const group = inject(ForSelectGroup, { optional: true });
+        if (!group) {
+            throw new Error('[forty-cdk/select] ForSelectGroupLabel must be used inside a [forSelectGroup] element.');
+        }
+        this.id = registerA11yName(group, 'for-select-group-label');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectGroupLabel, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectGroupLabel, isStandalone: true, selector: "[forSelectGroupLabel]", host: { properties: { "id": "id()" } }, exportAs: ["forSelectGroupLabel"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectGroupLabel, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectGroupLabel]',
+                    exportAs: 'forSelectGroupLabel',
+                    host: {
+                        '[id]': 'id()',
+                    },
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Decorative separator between options or groups inside a
+ * `[forSelectContent]`. Carries `role="separator"` and is intentionally not
+ * registered with the listbox's option collection, so keyboard navigation
+ * and typeahead skip it automatically.
+ */
+class ForSelectSeparator {
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectSeparator, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForSelectSeparator, isStandalone: true, selector: "[forSelectSeparator]", host: { attributes: { "role": "separator", "aria-orientation": "horizontal" } }, exportAs: ["forSelectSeparator"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForSelectSeparator, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forSelectSeparator]',
+                    exportAs: 'forSelectSeparator',
+                    host: {
+                        role: 'separator',
+                        'aria-orientation': 'horizontal',
+                    },
+                }]
+        }] });
+
+/**
+ * Exact public names of every `ForSelect` input, its models included. Spread it into the
+ * `inputs` array of a `hostDirectives` entry so a wrapper component re-exposes the
+ * primitive's full surface — the Signal Forms members `[formField]` binds among them —
+ * without hand-maintaining the list. Always spread into an inline object literal as shown
+ * below: the literal is what keeps the entry statically analyzable for consumers compiling
+ * against the published package. An anti-drift spec fails when this list no longer matches
+ * the directive's actual API. See `docs/wrapping-form-primitives.md` for both supported
+ * wrapping patterns.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'div[mySelect]',
+ *   template: '',
+ *   hostDirectives: [
+ *     {
+ *       directive: ForSelect,
+ *       inputs: [...FOR_SELECT_HOST_DIRECTIVE_INPUTS],
+ *       outputs: [...FOR_SELECT_HOST_DIRECTIVE_OUTPUTS],
+ *     },
+ *   ],
+ * })
+ * export class MySelect {}
+ * ```
+ */
+const FOR_SELECT_HOST_DIRECTIVE_INPUTS = [
+    'value',
+    'open',
+    'align',
+    'alignOffset',
+    'ariaLabel',
+    'arrowPadding',
+    'avoidCollisions',
+    'clipUntilPositioned',
+    'collisionPadding',
+    'dir',
+    'dirty',
+    'disabled',
+    'dismissible',
+    'errors',
+    'hideWhenDetached',
+    'invalid',
+    'isItemEqualToValue',
+    'itemToFormValue',
+    'itemToLabel',
+    'loop',
+    'modal',
+    'multiple',
+    'name',
+    'orientation',
+    'pending',
+    'placeholder',
+    'position',
+    'readonly',
+    'required',
+    'returnFocus',
+    'selectionFollowsFocus',
+    'side',
+    'sideOffset',
+    'sticky',
+    'totalCount',
+    'touched',
+    'visibleRange',
+];
+/**
+ * Exact public names of every `ForSelect` output, the Signal Forms `touch` output
+ * included. Spread it into the `outputs` array of the same `hostDirectives` entry as
+ * {@link FOR_SELECT_HOST_DIRECTIVE_INPUTS}.
+ */
+const FOR_SELECT_HOST_DIRECTIVE_OUTPUTS = [
+    'valueChange',
+    'openChange',
+    'escapeKeyDown',
+    'pointerDownOutside',
+    'focusOutside',
+    'interactOutside',
+    'autoFocusOnOpen',
+    'autoFocusOnClose',
+    'scrollToIndex',
+    'touchedChange',
+    'touch',
+];
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FOR_SELECT_CONTEXT, FOR_SELECT_DEFAULTS, FOR_SELECT_HOST_DIRECTIVE_INPUTS, FOR_SELECT_HOST_DIRECTIVE_OUTPUTS, FOR_SELECT_OPTION, ForSelect, ForSelectAnchor, ForSelectContent, ForSelectGroup, ForSelectGroupLabel, ForSelectIndicator, ForSelectOption, ForSelectSeparator, ForSelectTrigger, ForSelectValue, provideForSelectDefaults };
+//# sourceMappingURL=forty-cdk-select.mjs.map