forty-cdk 0.2.0 → 0.3.0

package/fesm2022/forty-cdk-listbox.mjs

@@ -0,0 +1,1279 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, ElementRef, model, input, booleanAttribute, numberAttribute, output, computed, signal, effect, Directive, DOCUMENT, PLATFORM_ID, DestroyRef } from '@angular/core';
+import { createDefaults, VirtualizedNavigator, FormUiControlBase, defaultItemToFormValue, singleSelected, injectTextDirection, RovingTabindex, injectTypeahead, Collection, firstEnabledHost, injectHiddenInput, reconcileRovingActive, isInArray, toggleInArray, nextEnabledHandle, findTypeaheadMatch, resolveListNavigation, hostId, registerHandle, registerA11yName, resolveLiftedDragControl, LiveAnnouncer, createKeyboardDragMediator, createPointerDragSession, resolveDropTarget, isDragLiftKey, PreviewController } from 'forty-cdk/core';
+import { isPlatformBrowser } from '@angular/common';
+
+const FOR_LISTBOX_CONTEXT = new InjectionToken('FOR_LISTBOX_CONTEXT');
+function injectListboxContext(piece) {
+    const ctx = inject(FOR_LISTBOX_CONTEXT, { optional: true });
+    if (!ctx) {
+        throw new Error(`[forty-cdk/listbox] ${piece} must be used inside a [forListbox] element.`);
+    }
+    return ctx;
+}
+
+/**
+ * Library fallback for listbox defaults, read at the root injector when no
+ * consumer has called `provideForListboxDefaults`. Exported for the shared defaults
+ * contract spec; not re-exported from the primitive's public entry.
+ */
+const FOR_LISTBOX_FALLBACK_DEFAULTS = {
+    selectionFollowsFocus: false,
+};
+const { token, provideDefaults } = createDefaults('FOR_LISTBOX_DEFAULTS', FOR_LISTBOX_FALLBACK_DEFAULTS);
+/** Token holding the resolved listbox defaults for the current scope. */
+const FOR_LISTBOX_DEFAULTS = token;
+/**
+ * Configures forty-cdk listbox defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+function provideForListboxDefaults(defaults = {}) {
+    return provideDefaults(defaults);
+}
+
+/**
+ * Virtualization navigation engine for `ForListbox`. A thin adapter over the
+ * shared `_internal/virtualized-navigator` engine: the listbox snapshot needs
+ * only the id + disabled flag (it never reads option values), so no NG0950 read
+ * guard is required.
+ *
+ * Internal — not re-exported from `listbox/index.ts` or `public-api.ts`.
+ */
+class ListboxVirtualizedNavigator {
+    #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) => ({ id: o.id(), 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);
+    }
+}
+
+/**
+ * Headless implementation of the [WAI-ARIA Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+ * 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
+ * `[forListboxOption][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.
+ *
+ * Selection is always modeled as `readonly T[]`:
+ * - In single mode (`multiple=false`, default), the array has 0 or 1 element.
+ * - In multi mode, any number of items can be selected.
+ *
+ * Single-select consumers can read the sole value through the
+ * {@link ForListbox.selected} convenience accessor instead of unwrapping the
+ * array.
+ *
+ * Keyboard supports the full APG-recommended model: arrows + Home/End for
+ * focus movement, Space/Enter (via native `<button>` activation) to select
+ * or toggle, typeahead, plus multi-select range modifiers (Shift+Arrow,
+ * Shift+Space, Ctrl/Cmd+A, Ctrl+Shift+Home/End).
+ */
+class ForListbox extends FormUiControlBase {
+    #host = inject(ElementRef);
+    #defaults = inject(FOR_LISTBOX_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 (option activation or `selectionFollowsFocus`
+     * nav), never on consumer writes via `[(value)]` — observe transitions
+     * without binding back.
+     */
+    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 */ []));
+    /**
+     * 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);
+    multiple = input(false, { ...(ngDevMode ? { debugName: "multiple" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Manual `aria-label` for the listbox. Use this when no visible label
+     * element exists; otherwise prefer pointing `aria-labelledby` at one. A
+     * `null` (default) or empty value emits no attribute.
+     */
+    ariaLabel = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaLabel" }] : /* istanbul ignore next */ []));
+    orientation = input('vertical', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "orientation" }] : /* istanbul ignore next */ []));
+    /**
+     * When true (default), arrow navigation wraps at the ends — moving past the
+     * last option focuses the first and vice versa. Set `false` to stop at the
+     * boundaries. Mirrors the `loop` input on `ForSelect`, `ForToggleGroup` and
+     * `ForCombobox`. Range extension (Shift+Arrow) never wraps regardless of
+     * this input, per the APG.
+     */
+    loop = input(true, { ...(ngDevMode ? { debugName: "loop" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /**
+     * Total number of items in the source data. When set, enables the
+     * virtualized activedescendant focus model and populates `aria-setsize`
+     * on each rendered option. Leave unset (default `undefined`) for the
+     * standard roving-tabindex 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. The virtualizer provides this; the listbox uses it to decide
+     * whether a navigation target is in the visible window.
+     */
+    visibleRange = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "visibleRange" }] : /* istanbul ignore next */ []));
+    /**
+     * Emitted when keyboard navigation reaches an option outside the rendered
+     * window. The consumer passes this index 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 and swaps
+     * ArrowLeft / ArrowRight semantics in RTL for horizontal listboxes.
+     */
+    _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.
+     * APG calls this optional and recommends caution — leave off unless your
+     * UX truly benefits from selection following focus. Default `false`.
+     * The default is read from `provideForListboxDefaults` for the surrounding
+     * scope.
+     */
+    selectionFollowsFocus = input(this.#defaults.selectionFollowsFocus, { ...(ngDevMode ? { debugName: "selectionFollowsFocus" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    roving = new RovingTabindex();
+    #typeahead = injectTypeahead();
+    #options = new Collection();
+    /**
+     * All registered options in DOM (rendered) order. Part of the public
+     * {@link ForListboxContext} surface so container-level coordinators (e.g.
+     * `ForListboxReorder`) can read the ordered hosts without each option owning a
+     * `[forDraggable]` that would fight the listbox's roving tabindex.
+     */
+    options = this.#options.items;
+    #firstEnabledHost = computed(() => firstEnabledHost(this.#options.items()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#firstEnabledHost" }] : /* istanbul ignore next */ []));
+    #firstSelectedHost = computed(() => {
+        const selected = this.value();
+        if (selected.length === 0) {
+            return null;
+        }
+        const equals = this.isItemEqualToValue();
+        for (const option of this.#options.items()) {
+            if (!option.disabled() && selected.some((v) => equals(v, option.value()))) {
+                return option.host;
+            }
+        }
+        return null;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#firstSelectedHost" }] : /* istanbul ignore next */ []));
+    #virtualized = computed(() => this.totalCount() !== undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#virtualized" }] : /* istanbul ignore next */ []));
+    #activeId = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#activeId" }] : /* istanbul ignore next */ []));
+    /**
+     * The active option's `id` when using the activedescendant focus model,
+     * `null` in the roving-tabindex path. The host reflects this as
+     * `aria-activedescendant`; options read it to compute `data-highlighted`.
+     */
+    activeDescendantId = computed(() => this.#virtualized() ? this.#activeId() : null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "activeDescendantId" }] : /* istanbul ignore next */ []));
+    /**
+     * Tabindex for the listbox host. In the virtualized path the host is always
+     * the single tab stop. In the roving path the host carries `tabindex="0"`
+     * only when no option qualifies — an empty listbox or one whose options are
+     * all disabled — so the control is still reachable. A disabled listbox is
+     * never tabbable.
+     */
+    hostTabindex = computed(() => {
+        if (this.effectiveDisabled()) {
+            return null;
+        }
+        if (this.#virtualized()) {
+            return '0';
+        }
+        const hasRovingEntry = this.#firstSelectedHost() !== null || this.#firstEnabledHost() !== null;
+        return hasRovingEntry ? null : '0';
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hostTabindex" }] : /* istanbul ignore next */ []));
+    /**
+     * Anchor value for APG range-selection actions (Shift+Space). Stored as the
+     * option's *value* (resolved to its current index at range time via
+     * {@link isItemEqualToValue}) rather than a DOM index, so reordering or
+     * removing options before the anchor can't silently shift the range to the
+     * wrong span. Set on every unmodified activation (click / Space / Enter); not
+     * affected by Shift+Arrow, which APG defines as per-option toggle.
+     */
+    #anchorValue = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "#anchorValue" }] : /* istanbul ignore next */ []));
+    #navigator = null;
+    #requireNavigator() {
+        return (this.#navigator ??= new ListboxVirtualizedNavigator({
+            items: this.#options.items,
+            totalCount: this.totalCount,
+            visibleRange: this.visibleRange,
+            loop: this.loop,
+            getActiveId: () => this.#activeId(),
+            setActiveId: (id) => this.#activeId.set(id),
+            emitScrollToIndex: (idx) => this.scrollToIndex.emit(idx),
+        }));
+    }
+    constructor() {
+        super();
+        injectHiddenInput({
+            name: this.name,
+            values: this.value,
+            serialize: (item) => this.itemToFormValue()(item),
+            disabled: this.effectiveDisabled,
+        });
+        reconcileRovingActive(this.roving, this.#options.items);
+        effect(() => {
+            this.#options.items();
+            if (!this.#virtualized()) {
+                return;
+            }
+            const navigator = this.#requireNavigator();
+            navigator.prime();
+            navigator.tryResolvePending();
+        });
+    }
+    isSelected(v) {
+        return isInArray(this.value(), v, this.isItemEqualToValue());
+    }
+    activate(v) {
+        if (this.effectiveDisabled() || this.readonly()) {
+            return;
+        }
+        if (this.multiple()) {
+            this.value.set(toggleInArray(this.value(), v, this.isItemEqualToValue()));
+        }
+        else {
+            // Single-mode: idempotent select (no deselect on click of selected).
+            this.value.set([v]);
+        }
+        this.#anchorValue.set(v);
+    }
+    extendByArrow(currentOption, action) {
+        if (this.effectiveDisabled() || !this.multiple()) {
+            return;
+        }
+        const target = nextEnabledHandle(this.#options.items(), currentOption, action, { loop: false });
+        if (target === null) {
+            return;
+        }
+        // Focus moves regardless of readonly — same contract as `navigate()`. Readonly
+        // only blocks the selection mutation.
+        target.host.focus();
+        if (this.readonly()) {
+            return;
+        }
+        this.value.set(toggleInArray(this.value(), target.value(), this.isItemEqualToValue()));
+    }
+    selectRangeToFocused(currentOption) {
+        if (this.effectiveDisabled() || this.readonly() || !this.multiple()) {
+            return;
+        }
+        const options = this.#options.items();
+        const currentIndex = options.findIndex((o) => o.host === currentOption);
+        if (currentIndex < 0) {
+            return;
+        }
+        const anchorValue = this.#anchorValue();
+        const equals = this.isItemEqualToValue();
+        const anchorIndex = anchorValue === null ? -1 : options.findIndex((o) => equals(o.value(), anchorValue));
+        const start = anchorIndex < 0 ? currentIndex : anchorIndex;
+        const [lo, hi] = start <= currentIndex ? [start, currentIndex] : [currentIndex, start];
+        const next = [...this.value()];
+        for (let i = lo; i <= hi; i++) {
+            const opt = options[i];
+            if (!opt || opt.disabled()) {
+                continue;
+            }
+            const v = opt.value();
+            if (!next.some((x) => equals(x, v))) {
+                next.push(v);
+            }
+        }
+        this.value.set(next);
+    }
+    selectAll() {
+        if (this.effectiveDisabled() || this.readonly() || !this.multiple()) {
+            return;
+        }
+        const enabled = [];
+        for (const opt of this.#options.items()) {
+            if (opt.disabled()) {
+                continue;
+            }
+            enabled.push(opt.value());
+        }
+        if (enabled.length === 0) {
+            return;
+        }
+        const equals = this.isItemEqualToValue();
+        const current = this.value();
+        const allSelected = enabled.every((v) => current.some((x) => equals(x, v)));
+        this.value.set(allSelected ? [] : enabled);
+    }
+    selectFromCurrentToEdge(currentOption, edge) {
+        if (this.effectiveDisabled() || !this.multiple()) {
+            return;
+        }
+        const options = this.#options.items();
+        const currentIndex = options.findIndex((o) => o.host === currentOption);
+        if (currentIndex < 0) {
+            return;
+        }
+        const [lo, hi] = edge === 'first' ? [0, currentIndex] : [currentIndex, options.length - 1];
+        const equals = this.isItemEqualToValue();
+        const next = [...this.value()];
+        let firstEnabled = null;
+        let lastEnabled = null;
+        // Walk forward so the resulting array preserves DOM order (insertion order).
+        for (let i = lo; i <= hi; i++) {
+            const opt = options[i];
+            if (!opt || opt.disabled()) {
+                continue;
+            }
+            const v = opt.value();
+            if (!next.some((x) => equals(x, v))) {
+                next.push(v);
+            }
+            if (firstEnabled === null) {
+                firstEnabled = opt.host;
+            }
+            lastEnabled = opt.host;
+        }
+        const edgeFocusTarget = edge === 'first' ? firstEnabled : lastEnabled;
+        // Focus moves regardless of readonly — same contract as `navigate()`. Readonly
+        // only blocks the selection mutation.
+        edgeFocusTarget?.focus();
+        if (this.readonly()) {
+            return;
+        }
+        this.value.set(next);
+    }
+    navigate(currentOption, action) {
+        if (this.effectiveDisabled()) {
+            return;
+        }
+        const target = nextEnabledHandle(this.#options.items(), currentOption, action, {
+            loop: this.loop(),
+        });
+        if (target === null) {
+            return;
+        }
+        target.host.focus();
+        target.host.scrollIntoView?.({ block: 'nearest' });
+        if (!this.multiple() && this.selectionFollowsFocus() && !this.readonly()) {
+            this.value.set([target.value()]);
+        }
+    }
+    handleTypeahead(event) {
+        if (!this.#typeahead.handle(event)) {
+            return false;
+        }
+        const options = this.#options.items();
+        const currentIndex = options.findIndex((o) => o.host === event.target);
+        const match = findTypeaheadMatch(options, {
+            buffer: this.#typeahead.buffer(),
+            repeated: this.#typeahead.isRepeatedChar(),
+            anchorIndex: currentIndex,
+        }, (o) => o.host.textContent ?? '', (o) => o.disabled());
+        match?.host.focus();
+        return true;
+    }
+    isFirstFocusableOption(el) {
+        const firstSelected = this.#firstSelectedHost();
+        if (firstSelected) {
+            return firstSelected === el;
+        }
+        return this.#firstEnabledHost() === el;
+    }
+    isOptionHighlighted(el) {
+        return this.roving.active() === el;
+    }
+    optionTabindex(el) {
+        if (this.#virtualized()) {
+            return -1;
+        }
+        return this.roving.hasActive() ? this.roving.tabindexFor(el) : null;
+    }
+    setActiveOption(el) {
+        this.roving.setActive(el);
+    }
+    registerOption(handle) {
+        this.#options.register(handle);
+    }
+    notifyOptionClick(optionId) {
+        if (!this.#virtualized()) {
+            return;
+        }
+        this.#activeId.set(optionId);
+        this.#host.nativeElement.focus();
+    }
+    unregisterOption(handle) {
+        this.#options.unregister(handle);
+        this.roving.unregister(handle.host);
+        if (this.#virtualized() && this.#activeId() === handle.id()) {
+            this.#activeId.set(null);
+        }
+    }
+    onHostKeyDown(event) {
+        if (!this.#virtualized() || this.effectiveDisabled()) {
+            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);
+    }
+    #activateActiveDescendant() {
+        const id = this.#activeId();
+        if (id === null) {
+            return;
+        }
+        const handle = this.#options.items().find((o) => o.id() === id);
+        if (!handle || handle.disabled()) {
+            return;
+        }
+        this.activate(handle.value());
+    }
+    #typeaheadVirtualized(event) {
+        if (!this.#typeahead.handle(event)) {
+            return;
+        }
+        const options = this.#options.items();
+        const activeId = this.#activeId();
+        const anchor = activeId === null ? -1 : options.findIndex((o) => o.id() === activeId);
+        const match = findTypeaheadMatch(options, {
+            buffer: this.#typeahead.buffer(),
+            repeated: this.#typeahead.isRepeatedChar(),
+            anchorIndex: anchor,
+        }, (o) => o.host.textContent ?? '', (o) => o.disabled());
+        if (match) {
+            this.#activeId.set(match.id());
+            match.host.scrollIntoView?.({ block: 'nearest' });
+        }
+    }
+    onHostFocusIn() {
+        if (!this.#virtualized() || this.effectiveDisabled()) {
+            return;
+        }
+        if (this.#activeId() !== null) {
+            return;
+        }
+        const items = this.#options.items();
+        if (items.length === 0) {
+            return;
+        }
+        const ordered = [...items].sort((a, b) => (a.posInSet() ?? 0) - (b.posInSet() ?? 0));
+        const equals = this.isItemEqualToValue();
+        const value = this.value();
+        const selectedFirst = ordered.find((o) => !o.disabled() && value.some((v) => equals(v, o.value())));
+        const target = selectedFirst ?? ordered.find((o) => !o.disabled());
+        if (target) {
+            this.#activeId.set(target.id());
+        }
+    }
+    onFocusOut(event) {
+        const next = event.relatedTarget;
+        if (next && this.#host.nativeElement.contains(next)) {
+            return;
+        }
+        this.markTouched();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListbox, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForListbox, isStandalone: true, selector: "[forListbox]", 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 }, multiple: { classPropertyName: "multiple", publicName: "multiple", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, orientation: { classPropertyName: "orientation", publicName: "orientation", isSignal: true, isRequired: false, transformFunction: null }, loop: { classPropertyName: "loop", publicName: "loop", 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 } }, outputs: { value: "valueChange", scrollToIndex: "scrollToIndex" }, host: { attributes: { "role": "listbox" }, listeners: { "keydown": "onHostKeyDown($event)", "focusin": "onHostFocusIn()", "focusout": "onFocusOut($event)" }, properties: { "attr.aria-label": "ariaLabel() || null", "attr.aria-orientation": "orientation()", "attr.aria-multiselectable": "multiple() ? \"true\" : null", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-readonly": "readonly() ? \"true\" : null", "attr.aria-required": "required() ? \"true\" : null", "attr.aria-invalid": "invalid() ? \"true\" : null", "attr.aria-busy": "pending() ? \"true\" : null", "attr.aria-activedescendant": "activeDescendantId()", "attr.tabindex": "hostTabindex()", "attr.data-orientation": "orientation()", "attr.data-disabled": "effectiveDisabled() ? \"\" : null", "attr.dir": "dir()" } }, providers: [{ provide: FOR_LISTBOX_CONTEXT, useExisting: ForListbox }], exportAs: ["forListbox"], usesInheritance: true, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListbox, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListbox]',
+                    exportAs: 'forListbox',
+                    host: {
+                        role: 'listbox',
+                        '[attr.aria-label]': 'ariaLabel() || null',
+                        '[attr.aria-orientation]': 'orientation()',
+                        '[attr.aria-multiselectable]': 'multiple() ? "true" : null',
+                        '[attr.aria-disabled]': 'effectiveDisabled() ? "true" : null',
+                        '[attr.aria-readonly]': 'readonly() ? "true" : null',
+                        '[attr.aria-required]': 'required() ? "true" : null',
+                        '[attr.aria-invalid]': 'invalid() ? "true" : null',
+                        '[attr.aria-busy]': 'pending() ? "true" : null',
+                        '[attr.aria-activedescendant]': 'activeDescendantId()',
+                        '[attr.tabindex]': 'hostTabindex()',
+                        '[attr.data-orientation]': 'orientation()',
+                        '[attr.data-disabled]': 'effectiveDisabled() ? "" : null',
+                        '[attr.dir]': 'dir()',
+                        '(keydown)': 'onHostKeyDown($event)',
+                        '(focusin)': 'onHostFocusIn()',
+                        '(focusout)': 'onFocusOut($event)',
+                    },
+                    providers: [{ provide: FOR_LISTBOX_CONTEXT, useExisting: ForListbox }],
+                }]
+        }], 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 }] }], multiple: [{ type: i0.Input, args: [{ isSignal: true, alias: "multiple", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], orientation: [{ type: i0.Input, args: [{ isSignal: true, alias: "orientation", required: false }] }], loop: [{ type: i0.Input, args: [{ isSignal: true, alias: "loop", 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 }] }] } });
+
+/**
+ * Injection key the `[forListboxOptionIndicator]` uses to resolve its parent
+ * option, decoupled from the concrete `ForListboxOption` class.
+ * `ForListboxOption` 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_LISTBOX_OPTION, useExisting: MtxListboxOption }`)
+ * and the indicator keeps resolving — see `docs/wrapping-form-primitives.md`.
+ */
+const FOR_LISTBOX_OPTION = new InjectionToken('FOR_LISTBOX_OPTION');
+/**
+ * One option inside a `ForListbox`. Apply on a `<button type="button">` so
+ * Space / Enter activation come from native button behavior — printable keys
+ * fall through to the parent 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]="lang"` infers `T = Language`); the parent `[forListbox]`
+ * must be parameterized over the same `T`. The parent's
+ * `[isItemEqualToValue]` decides how options are matched against the
+ * committed selection.
+ */
+class ForListboxOption {
+    #group = injectListboxContext('ForListboxOption');
+    #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 `[forListbox]` 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 — the listbox uses it to build the
+     * position snapshot and to emit `aria-posinset` (which is `posInSet + 1`).
+     * Leave unset (default `null`) outside the virtualized path.
+     */
+    posInSet = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "posInSet" }] : /* istanbul ignore next */ []));
+    id = hostId('for-listbox-option');
+    selected = computed(() => this.#group.isSelected(this.value()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "selected" }] : /* istanbul ignore next */ []));
+    /**
+     * True when this option is the keyboard-focused / active candidate.
+     * In the roving-tabindex path this tracks the DOM-focused option.
+     * In the virtualized activedescendant path it tracks `aria-activedescendant`.
+     * Reflected as `data-highlighted` so consumers can style it uniformly
+     * with the other primitives.
+     */
+    highlighted = computed(() => {
+        const activeId = this.#group.activeDescendantId();
+        if (activeId !== null) {
+            return activeId === this.id();
+        }
+        return this.#group.isOptionHighlighted(this.#host.nativeElement);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "highlighted" }] : /* istanbul ignore next */ []));
+    ariaSetSize = computed(() => {
+        const total = this.#group.totalCount();
+        return total === undefined ? null : String(total);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaSetSize" }] : /* istanbul ignore next */ []));
+    ariaPosInSet = computed(() => {
+        if (this.#group.totalCount() === undefined) {
+            return null;
+        }
+        const pos = this.posInSet();
+        return pos === null ? null : String(pos + 1);
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaPosInSet" }] : /* istanbul ignore next */ []));
+    effectiveDisabled = computed(() => this.disabled() || this.#group.effectiveDisabled(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "effectiveDisabled" }] : /* istanbul ignore next */ []));
+    tabindex = computed(() => {
+        if (this.effectiveDisabled()) {
+            return -1;
+        }
+        const rovingTabindex = this.#group.optionTabindex(this.#host.nativeElement);
+        if (rovingTabindex !== null) {
+            return rovingTabindex;
+        }
+        return this.#group.isFirstFocusableOption(this.#host.nativeElement) ? 0 : -1;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "tabindex" }] : /* istanbul ignore next */ []));
+    constructor() {
+        const handle = {
+            host: this.#host.nativeElement,
+            value: this.value,
+            disabled: this.effectiveDisabled,
+            id: this.id,
+            posInSet: this.posInSet,
+        };
+        registerHandle(handle, (h) => this.#group.registerOption(h), (h) => this.#group.unregisterOption(h));
+    }
+    onClick() {
+        if (this.effectiveDisabled() || this.#group.readonly()) {
+            return;
+        }
+        this.#group.activate(this.value());
+        this.#group.notifyOptionClick(this.id());
+    }
+    onPointerDown(event) {
+        if (this.#group.totalCount() === undefined) {
+            return;
+        }
+        event.preventDefault();
+    }
+    onFocus() {
+        if (this.effectiveDisabled()) {
+            return;
+        }
+        this.#group.setActiveOption(this.#host.nativeElement);
+    }
+    onKeyDown(event) {
+        if (this.effectiveDisabled()) {
+            return;
+        }
+        // APG-recommended multi-select range modifiers. Single-mode falls through
+        // to plain navigation so Shift+Arrow / Ctrl+A behave like their unmodified
+        // counterparts (or no-op).
+        if (this.#group.multiple()) {
+            // Ctrl/Cmd+A — select all enabled (toggle if all already selected).
+            if ((event.ctrlKey || event.metaKey) && !event.shiftKey && !event.altKey) {
+                if (event.key === 'a' || event.key === 'A') {
+                    event.preventDefault();
+                    this.#group.selectAll();
+                    return;
+                }
+            }
+            // Ctrl+Shift+Home / Ctrl+Shift+End — extend selection to first/last.
+            if ((event.ctrlKey || event.metaKey) && event.shiftKey && !event.altKey) {
+                if (event.key === 'Home') {
+                    event.preventDefault();
+                    this.#group.selectFromCurrentToEdge(this.#host.nativeElement, 'first');
+                    return;
+                }
+                if (event.key === 'End') {
+                    event.preventDefault();
+                    this.#group.selectFromCurrentToEdge(this.#host.nativeElement, 'last');
+                    return;
+                }
+            }
+            // Shift+Space — contiguous range from anchor to current.
+            if (event.shiftKey && event.key === ' ') {
+                event.preventDefault();
+                this.#group.selectRangeToFocused(this.#host.nativeElement);
+                return;
+            }
+            // Shift+Arrow — move focus AND toggle the destination option.
+            if (event.shiftKey && !event.ctrlKey && !event.metaKey && !event.altKey) {
+                const action = resolveListNavigation(event, {
+                    orientation: this.#group.orientation(),
+                    dir: this.#group.dir(),
+                });
+                if (action === 'next' || action === 'prev') {
+                    event.preventDefault();
+                    this.#group.extendByArrow(this.#host.nativeElement, action);
+                    return;
+                }
+            }
+        }
+        const action = resolveListNavigation(event, {
+            orientation: this.#group.orientation(),
+            dir: this.#group.dir(),
+            pageKeys: true,
+        });
+        if (action) {
+            event.preventDefault();
+            this.#group.navigate(this.#host.nativeElement, action);
+            return;
+        }
+        this.#group.handleTypeahead(event);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxOption, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForListboxOption, isStandalone: true, selector: "[forListboxOption]", 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" }, listeners: { "click": "onClick()", "focus": "onFocus()", "keydown": "onKeyDown($event)", "pointerdown": "onPointerDown($event)" }, properties: { "id": "id()", "attr.aria-selected": "selected() ? \"true\" : \"false\"", "attr.aria-disabled": "effectiveDisabled() ? \"true\" : null", "attr.aria-setsize": "ariaSetSize()", "attr.aria-posinset": "ariaPosInSet()", "attr.tabindex": "tabindex()", "attr.data-state": "selected() ? \"checked\" : \"unchecked\"", "attr.data-highlighted": "highlighted() ? \"\" : null", "attr.data-disabled": "effectiveDisabled() ? \"\" : null" } }, providers: [{ provide: FOR_LISTBOX_OPTION, useExisting: ForListboxOption }], exportAs: ["forListboxOption"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxOption, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListboxOption]',
+                    exportAs: 'forListboxOption',
+                    providers: [{ provide: FOR_LISTBOX_OPTION, useExisting: ForListboxOption }],
+                    host: {
+                        role: 'option',
+                        type: 'button',
+                        '[id]': 'id()',
+                        '[attr.aria-selected]': 'selected() ? "true" : "false"',
+                        '[attr.aria-disabled]': 'effectiveDisabled() ? "true" : null',
+                        '[attr.aria-setsize]': 'ariaSetSize()',
+                        '[attr.aria-posinset]': 'ariaPosInSet()',
+                        '[attr.tabindex]': 'tabindex()',
+                        '[attr.data-state]': 'selected() ? "checked" : "unchecked"',
+                        '[attr.data-highlighted]': 'highlighted() ? "" : null',
+                        '[attr.data-disabled]': 'effectiveDisabled() ? "" : null',
+                        '(click)': 'onClick()',
+                        '(focus)': 'onFocus()',
+                        '(keydown)': 'onKeyDown($event)',
+                        '(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 }] }] } });
+
+/**
+ * Optional indicator slot inside a `ForListboxOption`. Apply on the
+ * element the consumer wants to show only while this option is selected
+ * (typically a check icon to the left of the label). Mirrors `data-state`
+ * and hides itself while unselected. Visibility 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 ForListboxOptionIndicator {
+    parent;
+    constructor() {
+        const parent = inject(FOR_LISTBOX_OPTION, { optional: true });
+        if (!parent) {
+            throw new Error('[forty-cdk/listbox] ForListboxOptionIndicator must be used inside a [forListboxOption] element.');
+        }
+        this.parent = parent;
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxOptionIndicator, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForListboxOptionIndicator, isStandalone: true, selector: "[forListboxOptionIndicator]", host: { properties: { "attr.data-state": "parent.selected() ? \"checked\" : \"unchecked\"", "attr.hidden": "parent.selected() ? null : \"\"", "style.display": "parent.selected() ? null : \"none\"" } }, exportAs: ["forListboxOptionIndicator"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxOptionIndicator, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListboxOptionIndicator]',
+                    exportAs: 'forListboxOptionIndicator',
+                    host: {
+                        '[attr.data-state]': 'parent.selected() ? "checked" : "unchecked"',
+                        '[attr.hidden]': 'parent.selected() ? null : ""',
+                        '[style.display]': 'parent.selected() ? null : "none"',
+                    },
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Optional grouping wrapper inside a `ForListbox`. Renders `role="group"`
+ * and references the descendant `[forListboxGroupLabel]` (if any) via
+ * `aria-labelledby`. Options inside a group still register with the
+ * listbox normally, so keyboard navigation traverses across groups in DOM
+ * order without special handling.
+ */
+class ForListboxGroup {
+    #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 `ForListboxGroupLabel` on mount. */
+    registerLabel(id) {
+        this.#labelId.set(id);
+    }
+    /** Called by `ForListboxGroupLabel` 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: ForListboxGroup, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForListboxGroup, isStandalone: true, selector: "[forListboxGroup]", host: { attributes: { "role": "group" }, properties: { "attr.aria-labelledby": "labelId() || null" } }, exportAs: ["forListboxGroup"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxGroup, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListboxGroup]',
+                    exportAs: 'forListboxGroup',
+                    host: {
+                        role: 'group',
+                        '[attr.aria-labelledby]': 'labelId() || null',
+                    },
+                }]
+        }] });
+
+/**
+ * Visible label for a `ForListboxGroup`. 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 — `<h3>`/`<h4>` if the
+ * surrounding document has a sensible heading hierarchy).
+ */
+class ForListboxGroupLabel {
+    /** Stable host id used by the parent group's `aria-labelledby`. */
+    id;
+    constructor() {
+        const group = inject(ForListboxGroup, { optional: true });
+        if (!group) {
+            throw new Error('[forty-cdk/listbox] ForListboxGroupLabel must be used inside a [forListboxGroup] element.');
+        }
+        this.id = registerA11yName(group, 'for-listbox-group-label');
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxGroupLabel, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.2", type: ForListboxGroupLabel, isStandalone: true, selector: "[forListboxGroupLabel]", host: { properties: { "id": "id()" } }, exportAs: ["forListboxGroupLabel"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxGroupLabel, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListboxGroupLabel]',
+                    exportAs: 'forListboxGroupLabel',
+                    host: {
+                        '[id]': 'id()',
+                    },
+                }]
+        }], ctorParameters: () => [] });
+
+/**
+ * Live-region phrasing for `ForListboxReorder`. Framework-free and unit-testable in isolation.
+ * Not part of the public API. Mirrors the lift / move / drop / cancel cadence the drag-drop and
+ * tree coordinators use so a consumer hears consistent reorder announcements across primitives.
+ */
+/** Announcement when an option is lifted. `index` / `total` are 1-based. */
+function announceReorderLift(label, index, total) {
+    return `${label}, lifted. ${index} of ${total}.`;
+}
+/** Announcement when the drop position changes during a drag. `index` / `total` are 1-based. */
+function announceReorderMove(label, index, total) {
+    return `${label}, moved to position ${index} of ${total}.`;
+}
+/** Announcement on a committed drop. `index` / `total` are 1-based. */
+function announceReorderDrop(label, index, total) {
+    return `${label}, dropped at position ${index} of ${total}.`;
+}
+/** Announcement when a drag is cancelled. */
+function announceReorderCancel(label) {
+    return `${label}, movement cancelled.`;
+}
+
+const POINTER_ARM_THRESHOLD_PX = 5;
+/**
+ * Resolves a lifted-drag keydown to a reorder action. `Escape` / `Tab` cancel and
+ * `Space` / `Enter` commit (shared with the tree coordinator); arrow keys step the target
+ * linearly in DOM order (both axes, so a wrapping chip grid reorders by either pair), and
+ * `Home` / `End` jump to the ends. Honors writing direction for the horizontal arrows.
+ */
+function resolveReorderAction(event, dir) {
+    const control = resolveLiftedDragControl(event);
+    if (control) {
+        return control;
+    }
+    const isRtl = dir === 'rtl';
+    switch (event.key) {
+        case 'ArrowDown':
+            return 'next';
+        case 'ArrowUp':
+            return 'prev';
+        case 'ArrowRight':
+            return isRtl ? 'prev' : 'next';
+        case 'ArrowLeft':
+            return isRtl ? 'next' : 'prev';
+        case 'Home':
+            return 'first';
+        case 'End':
+            return 'last';
+        default:
+            return null;
+    }
+}
+/**
+ * Opt-in **pointer + keyboard reordering** for `ForListbox`, composed onto the same element as
+ * `[forListbox]`.
+ *
+ * `[forDraggable]` cannot stack on a `[forListboxOption]` — both would manage the option's
+ * roving tabindex and keyboard, colliding on `tabindex`, on Space / Enter activation, and on the
+ * container `orientation` input. This coordinator is the listbox-side analogue of
+ * `ForTreeNodeDrag` / `ForTableRowReorder`: it lives on the container, **never touches the
+ * option's roving tabindex**, intercepts keys in the capture phase, and owns its own 2D drop
+ * geometry — so the listbox keeps full selection + typeahead behavior while becoming sortable.
+ *
+ * Keyboard: focus an option, press `Ctrl+Space` (or `Cmd+Space`) to lift. While lifted, the
+ * arrow keys step the target position (linearly in DOM order, so a wrapping chip grid works with
+ * either axis), `Home` / `End` jump to the ends, `Space` / `Enter` drop, `Escape` / `Tab` cancel.
+ *
+ * Pointer: drag an option past a small threshold to reorder; a short press without movement still
+ * selects (the post-drag click is suppressed). A floating preview follows the pointer; drop
+ * geometry is resolved in 2D, so vertical lists, horizontal lists, and wrapping grids all work
+ * without configuring `orientation`.
+ *
+ * It **never reorders the options itself** (BYO-data): `(optionReorder)` emits the previous / new
+ * index on every committed drop; apply `moveItemInArray(items, from, to)` to your own array.
+ * Intended for the standard roving-tabindex listbox; a virtualized listbox (`[totalCount]` set)
+ * is left untouched, since reordering a windowed subset is ill-defined.
+ *
+ * @example
+ * ```html
+ * <ul forListbox forListboxReorder multiple [(value)]="selected" (optionReorder)="reorder($event)">
+ *   @for (tag of tags(); track tag) {
+ *     <li><button type="button" forListboxOption [value]="tag">{{ tag }}</button></li>
+ *   }
+ * </ul>
+ * ```
+ */
+class ForListboxReorder {
+    #ctx = injectListboxContext('ForListboxReorder');
+    #host = inject(ElementRef).nativeElement;
+    #document = inject(DOCUMENT);
+    #isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+    #announcer = inject(LiveAnnouncer);
+    #destroyRef = inject(DestroyRef);
+    /**
+     * Disables reorder interactions while leaving selection / typeahead intact. Named distinctly
+     * from the listbox's own `disabled` so the two never share a single `[disabled]` binding on the
+     * shared host. The listbox being disabled (its own `disabled` or a surrounding `[forFieldset]`)
+     * also disables reorder.
+     */
+    reorderDisabled = input(false, { ...(ngDevMode ? { debugName: "reorderDisabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Emitted once per committed reorder gesture with the previous / new option index. */
+    optionReorder = output();
+    _dragging = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_dragging" }] : /* istanbul ignore next */ []));
+    #mode = 'idle';
+    #liftedHost = null;
+    #fromIndex = 0;
+    #targetIndex = 0;
+    #label = '';
+    #previewController = null;
+    #pointerSession = null;
+    constructor() {
+        createKeyboardDragMediator({
+            host: this.#host,
+            isBrowser: this.#isBrowser,
+            destroyRef: this.#destroyRef,
+            isLifted: () => this.#mode === 'keyboard',
+            onIdleKeydown: (event) => this.#onIdleKeydown(event),
+            onLiftedKeydown: (event) => this.#onLiftedKeydown(event),
+            onFocusOut: (event) => this.#onFocusOut(event),
+        });
+        if (this.#isBrowser) {
+            this.#pointerSession = createPointerDragSession({
+                host: this.#host,
+                document: this.#document,
+                armThreshold: POINTER_ARM_THRESHOLD_PX,
+                cancelOnEscape: true,
+                capturePointer: true,
+                canStart: (event) => this.#canStartPointer(event),
+                onLift: (event) => this.#onPointerLift(event),
+                onMove: (event) => this.#onPointerMove(event),
+                onCommit: (event) => this.#onPointerCommit(event),
+                onCancel: () => this.#onPointerCancel(),
+            });
+            this.#destroyRef.onDestroy(() => {
+                this.#pointerSession?.destroy();
+                if (this.#mode !== 'idle') {
+                    this.#clearSession();
+                }
+            });
+        }
+    }
+    #reorderable() {
+        return (!this.reorderDisabled() &&
+            !this.#ctx.effectiveDisabled() &&
+            this.#ctx.totalCount() === undefined);
+    }
+    #resolveOption(target) {
+        if (!(target instanceof Node)) {
+            return null;
+        }
+        const options = this.#ctx.options();
+        for (let i = 0; i < options.length; i++) {
+            const option = options[i];
+            if (option.host === target || option.host.contains(target)) {
+                return option.disabled() ? null : { host: option.host, index: i };
+            }
+        }
+        return null;
+    }
+    #canStartPointer(event) {
+        if (!this.#reorderable() || (event.pointerType === 'mouse' && event.button !== 0)) {
+            return false;
+        }
+        const resolved = this.#resolveOption(event.target);
+        if (!resolved) {
+            return false;
+        }
+        this.#liftedHost = resolved.host;
+        this.#fromIndex = resolved.index;
+        return true;
+    }
+    #onPointerLift(event) {
+        if (this.#liftedHost === null) {
+            return false;
+        }
+        this.#lift(this.#liftedHost, this.#fromIndex, 'pointer', {
+            x: event.clientX,
+            y: event.clientY,
+        });
+        return true;
+    }
+    #onPointerMove(event) {
+        if (this.#mode !== 'pointer') {
+            return;
+        }
+        const point = { x: event.clientX, y: event.clientY };
+        this.#previewController?.moveTo(point);
+        this.#setTarget(this.#resolvePointerTarget(point), 'polite');
+    }
+    #onPointerCommit(event) {
+        if (this.#mode !== 'pointer') {
+            return;
+        }
+        this.#targetIndex = this.#resolvePointerTarget({ x: event.clientX, y: event.clientY });
+        this.#commit();
+    }
+    #onPointerCancel() {
+        if (this.#mode !== 'pointer') {
+            return;
+        }
+        this.#cancel();
+    }
+    #resolvePointerTarget(point) {
+        const lifted = this.#liftedHost;
+        const itemRects = this.#ctx
+            .options()
+            .filter((option) => option.host !== lifted)
+            .map((option) => option.host.getBoundingClientRect());
+        const target = resolveDropTarget(point, [{ rect: this.#host.getBoundingClientRect(), itemRects }], 'mixed', this.#ctx.dir());
+        return target ? target.index : this.#targetIndex;
+    }
+    #onIdleKeydown(event) {
+        if (this.#mode !== 'idle' || !isDragLiftKey(event) || !this.#reorderable()) {
+            return;
+        }
+        const resolved = this.#resolveOption(event.target);
+        if (!resolved) {
+            return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        this.#lift(resolved.host, resolved.index, 'keyboard');
+    }
+    #onLiftedKeydown(event) {
+        const action = resolveReorderAction(event, this.#ctx.dir());
+        if (action === null) {
+            return;
+        }
+        event.preventDefault();
+        event.stopPropagation();
+        switch (action) {
+            case 'cancel':
+                this.#cancel();
+                return;
+            case 'commit':
+                this.#commit();
+                return;
+            case 'next':
+                this.#setTarget(this.#targetIndex + 1, 'polite');
+                return;
+            case 'prev':
+                this.#setTarget(this.#targetIndex - 1, 'polite');
+                return;
+            case 'first':
+                this.#setTarget(0, 'polite');
+                return;
+            case 'last':
+                this.#setTarget(this.#ctx.options().length - 1, 'polite');
+                return;
+        }
+    }
+    #onFocusOut(event) {
+        if (this.#mode !== 'keyboard') {
+            return;
+        }
+        const related = event.relatedTarget;
+        if (related && this.#host.contains(related)) {
+            return;
+        }
+        this.#cancel();
+    }
+    #lift(host, index, mode, point) {
+        this.#mode = mode;
+        this.#liftedHost = host;
+        this.#fromIndex = index;
+        this.#targetIndex = index;
+        this.#label = (host.textContent ?? '').trim();
+        host.setAttribute('data-dragging', '');
+        this._dragging.set(true);
+        if (mode === 'pointer' && point) {
+            this.#previewController = new PreviewController({
+                source: host,
+                point,
+                preview: null,
+                doc: this.#document,
+                boundary: null,
+                lockAxis: () => null,
+            });
+        }
+        this.#announcer.announce(announceReorderLift(this.#label, index + 1, this.#ctx.options().length), 'assertive');
+    }
+    #setTarget(to, politeness) {
+        const total = this.#ctx.options().length;
+        const clamped = Math.max(0, Math.min(total - 1, to));
+        if (clamped === this.#targetIndex) {
+            return;
+        }
+        this.#targetIndex = clamped;
+        this.#announcer.announce(announceReorderMove(this.#label, clamped + 1, total), politeness);
+    }
+    #commit() {
+        if (this.#mode === 'idle' || this.#liftedHost === null) {
+            return;
+        }
+        const total = this.#ctx.options().length;
+        const to = Math.max(0, Math.min(total - 1, this.#targetIndex));
+        const from = this.#fromIndex;
+        const label = this.#label;
+        this.#clearSession();
+        this.optionReorder.emit({ from, to });
+        this.#announcer.announce(announceReorderDrop(label, to + 1, total), 'assertive');
+    }
+    #cancel() {
+        if (this.#mode === 'idle') {
+            return;
+        }
+        const label = this.#label;
+        this.#clearSession();
+        this.#announcer.announce(announceReorderCancel(label), 'assertive');
+    }
+    #clearSession() {
+        this.#liftedHost?.removeAttribute('data-dragging');
+        this.#mode = 'idle';
+        this.#liftedHost = null;
+        this.#fromIndex = 0;
+        this.#targetIndex = 0;
+        this.#label = '';
+        this.#previewController?.destroy();
+        this.#previewController = null;
+        this._dragging.set(false);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxReorder, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: ForListboxReorder, isStandalone: true, selector: "[forListboxReorder]", inputs: { reorderDisabled: { classPropertyName: "reorderDisabled", publicName: "reorderDisabled", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { optionReorder: "optionReorder" }, host: { properties: { "attr.data-dragging": "_dragging() ? \"\" : null" } }, exportAs: ["forListboxReorder"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: ForListboxReorder, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[forListboxReorder]',
+                    exportAs: 'forListboxReorder',
+                    host: {
+                        '[attr.data-dragging]': '_dragging() ? "" : null',
+                    },
+                }]
+        }], ctorParameters: () => [], propDecorators: { reorderDisabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "reorderDisabled", required: false }] }], optionReorder: [{ type: i0.Output, args: ["optionReorder"] }] } });
+
+/**
+ * Exact public names of every `ForListbox` 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[myListbox]',
+ *   template: '',
+ *   hostDirectives: [
+ *     {
+ *       directive: ForListbox,
+ *       inputs: [...FOR_LISTBOX_HOST_DIRECTIVE_INPUTS],
+ *       outputs: [...FOR_LISTBOX_HOST_DIRECTIVE_OUTPUTS],
+ *     },
+ *   ],
+ * })
+ * export class MyListbox {}
+ * ```
+ */
+const FOR_LISTBOX_HOST_DIRECTIVE_INPUTS = [
+    'value',
+    'ariaLabel',
+    'dir',
+    'dirty',
+    'disabled',
+    'errors',
+    'invalid',
+    'isItemEqualToValue',
+    'itemToFormValue',
+    'loop',
+    'multiple',
+    'name',
+    'orientation',
+    'pending',
+    'readonly',
+    'required',
+    'selectionFollowsFocus',
+    'totalCount',
+    'touched',
+    'visibleRange',
+];
+/**
+ * Exact public names of every `ForListbox` output, the Signal Forms `touch` output
+ * included. Spread it into the `outputs` array of the same `hostDirectives` entry as
+ * {@link FOR_LISTBOX_HOST_DIRECTIVE_INPUTS}.
+ */
+const FOR_LISTBOX_HOST_DIRECTIVE_OUTPUTS = [
+    'scrollToIndex',
+    'touch',
+    'touchedChange',
+    'valueChange',
+];
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { FOR_LISTBOX_CONTEXT, FOR_LISTBOX_DEFAULTS, FOR_LISTBOX_HOST_DIRECTIVE_INPUTS, FOR_LISTBOX_HOST_DIRECTIVE_OUTPUTS, FOR_LISTBOX_OPTION, ForListbox, ForListboxGroup, ForListboxGroupLabel, ForListboxOption, ForListboxOptionIndicator, ForListboxReorder, provideForListboxDefaults };
+//# sourceMappingURL=forty-cdk-listbox.mjs.map