forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-combobox.d.ts

@@ -0,0 +1,1259 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, ModelSignal, Signal, Provider } from '@angular/core';
+import { ReferenceElement } from '@floating-ui/dom';
+import { FormValueControl } from '@angular/forms/signals';
+import { WritingDirection, FloatingSide, FloatingAlign, CollectionHandle, VetoableNativeEvent, FormUiControlBase, VetoableEvent } from 'forty-cdk/core';
+import * as forty_cdk_combobox from 'forty-cdk/combobox';
+
+/**
+ * Why the combobox closed. Mirrors the menu / select vocabulary so consumers
+ * can switch on the reason regardless of overlay flavor.
+ */
+type ForComboboxCloseReason = 'escape' | 'pointerDownOutside' | 'focusOutside' | 'select' | 'tab' | 'programmatic';
+/**
+ * Autocomplete mode applied to the input. Mirrors the
+ * [WAI-ARIA combobox autocomplete property](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#wai-ariaroles,states,andproperties).
+ *
+ * - `'none'`: input acts as a free-text query; no completion is performed.
+ * - `'list'`: the listbox shows filtered options; the input value reflects
+ *   the user's typed query verbatim.
+ * - `'inline'`: the rest of the first matching option is auto-completed
+ *   into the input as selected text; the listbox does not auto-open.
+ * - `'both'`: combines `'list'` and `'inline'` — listbox opens with the
+ *   filtered options *and* the first match auto-completes inline.
+ */
+type ForComboboxAutocomplete = 'none' | 'list' | 'inline' | 'both';
+/**
+ * Where the auto-highlight seed lands when the listbox opens. `'first'` / `'last'`
+ * bias to the natural extreme (e.g. ArrowDown / ArrowUp on the trigger). `'selected'`
+ * — used by the picker trigger's plain open — seeds the committed selection, falling
+ * back to the first enabled option when there is no selection or it is filtered out.
+ */
+type ForComboboxInitialFocus = 'first' | 'last' | 'selected';
+interface ForComboboxOptionHandle<T = unknown> extends CollectionHandle {
+    readonly id: Signal<string>;
+    readonly value: Signal<T>;
+    readonly label: Signal<string>;
+    readonly disabled: Signal<boolean>;
+    /**
+     * Index in the consumer's source array. Required when virtualizing so the
+     * directive can fold off-screen options into the snapshot keyed by
+     * absolute position. Optional otherwise — when absent the snapshot falls
+     * back to DOM order.
+     */
+    readonly posInSet?: Signal<number | null>;
+}
+interface ForComboboxChipHandle<T = unknown> extends CollectionHandle {
+    readonly value: Signal<T>;
+}
+/**
+ * Coordination contract owned by `[forCombobox]`. Input, content, options,
+ * groups, separators, the empty-state directive, the clear button, and the
+ * multi-mode chip pieces all inject this token to read state and delegate
+ * behavior.
+ *
+ * The value model is always an array — single mode (`multiple=false`,
+ * default) keeps 0 or 1 element, multi mode keeps any number. This mirrors
+ * `[forListbox]` / `[forSelect]` so consumers learn one selection contract
+ * across the whole library.
+ *
+ * Generic over the option value type `T` (default `string`). When a
+ * consumer binds object items the directive infers `T` from `[(value)]` and
+ * the per-piece signatures specialize accordingly. Items are compared via
+ * the consumer-provided `isItemEqualToValue` and rendered as labels via
+ * `itemToStringLabel`; the form's hidden inputs serialize via
+ * `itemToFormValue`.
+ */
+interface ForComboboxContext<T = unknown> {
+    readonly query: ModelSignal<string>;
+    readonly value: ModelSignal<readonly T[]>;
+    readonly open: ModelSignal<boolean>;
+    readonly multiple: Signal<boolean>;
+    /**
+     * The combobox's effective disabled — its own `disabled` input OR'd with a
+     * surrounding disabled `[forFieldset]`. Input, options, clear, and chip pieces
+     * read this so a disabled combobox (or fieldset) is inert and exposes
+     * `aria-disabled`.
+     */
+    readonly effectiveDisabled: Signal<boolean>;
+    readonly readonly: Signal<boolean>;
+    readonly required: Signal<boolean>;
+    readonly invalid: Signal<boolean>;
+    readonly pending: Signal<boolean>;
+    readonly dir: Signal<WritingDirection>;
+    readonly autocompleteMode: Signal<ForComboboxAutocomplete>;
+    readonly openOnFocus: Signal<boolean>;
+    readonly openOnQuery: Signal<boolean>;
+    readonly commitOnSelect: Signal<boolean>;
+    readonly clearOnQueryChange: Signal<boolean>;
+    readonly dismissible: Signal<boolean>;
+    /**
+     * Whether focus returns to the `[forComboboxTrigger]` on close (picker
+     * anatomy). Ignored in the editable anatomy, where focus never left the
+     * input. Default `true`.
+     */
+    readonly returnFocus: Signal<boolean>;
+    readonly side: Signal<FloatingSide | undefined>;
+    readonly align: Signal<FloatingAlign>;
+    readonly sideOffset: Signal<number>;
+    readonly alignOffset: Signal<number>;
+    readonly avoidCollisions: Signal<boolean>;
+    readonly collisionPadding: Signal<number>;
+    readonly arrowPadding: Signal<number>;
+    readonly sticky: Signal<'partial' | 'always' | false>;
+    readonly hideWhenDetached: Signal<boolean>;
+    readonly clipUntilPositioned: Signal<boolean>;
+    readonly loop: Signal<boolean>;
+    readonly inputId: Signal<string>;
+    readonly contentId: Signal<string>;
+    /**
+     * Id of the `[forComboboxList]` listbox surface (picker anatomy). The input's
+     * `aria-controls` points here when a list is registered; without one it falls
+     * back to {@link contentId} (the editable anatomy where content itself is the
+     * listbox).
+     */
+    readonly listId: Signal<string>;
+    /**
+     * Id of the element carrying `role="listbox"` — {@link listId} when a
+     * `[forComboboxList]` is registered, otherwise {@link contentId}. The input
+     * targets this with `aria-controls`.
+     */
+    readonly listboxId: Signal<string>;
+    readonly ariaLabel: Signal<string | null>;
+    /**
+     * Element floating-ui anchors the listbox against. Prefers an optional
+     * `[forComboboxAnchor]` when registered, otherwise falls back to the input.
+     * Decoupled from `input` so the input keeps driving `aria-controls`,
+     * `aria-activedescendant`, keyboard interaction, and its outside-pointer
+     * exemption regardless of where the listbox paints.
+     */
+    readonly anchor: Signal<ReferenceElement | null>;
+    readonly input: Signal<HTMLInputElement | null>;
+    registerInput(el: HTMLInputElement): void;
+    unregisterInput(el: HTMLInputElement): void;
+    /**
+     * Register / unregister an optional `[forComboboxAnchor]` positioning
+     * element. At most one anchor per root; a second registration throws.
+     * Reference-based unregister, so an anchor torn down inside `@if` restores
+     * the input fallback cleanly.
+     */
+    registerAnchor(el: HTMLElement): void;
+    unregisterAnchor(el: HTMLElement): void;
+    /**
+     * The optional `[forComboboxTrigger]` button (picker anatomy). When present
+     * it is the default positioning anchor (after an explicit `[forComboboxAnchor]`)
+     * and the element focus returns to on close. `null` in the editable anatomy.
+     */
+    readonly trigger: Signal<HTMLElement | null>;
+    registerTrigger(el: HTMLElement): void;
+    unregisterTrigger(el: HTMLElement): void;
+    readonly content: Signal<HTMLElement | null>;
+    registerContent(el: HTMLElement): void;
+    unregisterContent(el: HTMLElement): void;
+    /**
+     * The optional `[forComboboxList]` listbox surface (picker anatomy). When
+     * registered, `[forComboboxContent]` drops its `role="listbox"` semantics and
+     * becomes a neutral popup surface; the list carries the listbox role and owns
+     * the options. `null` in the editable anatomy.
+     */
+    readonly list: Signal<HTMLElement | null>;
+    /** True when a `[forComboboxList]` is registered (picker anatomy). */
+    readonly hasList: Signal<boolean>;
+    registerList(el: HTMLElement): void;
+    unregisterList(el: HTMLElement): void;
+    registerOption(handle: ForComboboxOptionHandle<T>): void;
+    unregisterOption(handle: ForComboboxOptionHandle<T>): void;
+    readonly options: Signal<readonly ForComboboxOptionHandle<T>[]>;
+    /** Multi-mode chip collection. Order follows DOM (= `value()` order in practice). */
+    registerChip(handle: ForComboboxChipHandle<T>): void;
+    unregisterChip(handle: ForComboboxChipHandle<T>): void;
+    readonly chips: Signal<readonly ForComboboxChipHandle<T>[]>;
+    /**
+     * Selected entries paired with their resolved label (from the option
+     * cache) — convenient for rendering chips with `@for`. Falls back to
+     * `itemToStringLabel(value)` when no matching option is registered (and
+     * to the raw string when `T` is `string`).
+     */
+    readonly selected: Signal<readonly {
+        value: T;
+        label: string;
+    }[]>;
+    /** Compare two items for equality. Defaults to `===`; overridden for object values. */
+    readonly isItemEqualToValue: Signal<(a: T, b: T) => boolean>;
+    /** Render an item as a string label. Drives chip labels and `commitOnSelect` writes into the input. */
+    readonly itemToStringLabel: Signal<(item: T) => string>;
+    /** Serialize an item for the hidden input's `value` attribute. */
+    readonly itemToFormValue: Signal<(item: T) => string>;
+    /** Id of the currently active option (drives `aria-activedescendant` on the input). */
+    readonly activeId: Signal<string | null>;
+    /** Set the activedescendant directly. Used by options on pointer-move and by the input on inline-completion seed. */
+    setActiveId(id: string | null): void;
+    /** Read-only access to the cached snapshot consumed by inline-autocomplete in the input directive. */
+    cachedOptions(): readonly {
+        id: string;
+        value: T;
+        label: string;
+    }[];
+    /**
+     * Total number of options in the consumer's source array. Used for
+     * `aria-setsize` and for navigation past the visible window when
+     * virtualizing. Falls back to `options().length` when undefined.
+     */
+    readonly totalCount: Signal<number | undefined>;
+    /** Inclusive-exclusive [start, end) range of options currently rendered when virtualizing. */
+    readonly visibleRange: Signal<readonly [number, number] | undefined>;
+    /** True when `value` includes `v` per the active equality function. */
+    isSelected(value: T): boolean;
+    /** True when `id` is the activedescendant. */
+    isActive(id: string): boolean;
+    /**
+     * Whether a pointer-suppression window is currently open. Opened whenever the
+     * directive scrolls the active option into view during keyboard navigation,
+     * so a synthetic `pointermove` fired because the scroll slid a different
+     * option under a stationary cursor does not hijack the activedescendant.
+     * Options consult this from their hover handler and skip the move while it
+     * returns `true`.
+     */
+    isPointerSuppressed(): boolean;
+    /**
+     * Activate by handle. Single mode replaces + closes + commits label. Multi
+     * mode toggles in/out + stays open + (when `commitOnSelect`) clears the
+     * query so the user can search the next item. No-op on disabled / readonly.
+     */
+    activate(handle: ForComboboxOptionHandle<T>): void;
+    /** Remove a value from `value()`. Used by chip-remove and Backspace heuristics. */
+    removeValue(value: T): void;
+    /** Move the activedescendant to the first / last / next / prev enabled option. */
+    navigate(direction: 'next' | 'prev' | 'first' | 'last'): void;
+    /** Activate the option currently marked as activedescendant (Enter from the input). */
+    activateActive(): boolean;
+    /** Set the typed query. Emits inline completion / openOnQuery side-effects via the input directive. */
+    setQueryFromInput(query: string): void;
+    /**
+     * Clear value and (optionally) query. Used by `[forComboboxClear]` and
+     * by the Backspace-on-empty-input heuristic. The query is reset only
+     * when `clearQuery` is true.
+     */
+    clear(clearQuery?: boolean): void;
+    /** Where focus should land after the listbox opens. The input directive sets this before flipping `open`. */
+    readonly initialFocus: Signal<ForComboboxInitialFocus>;
+    setInitialFocus(target: ForComboboxInitialFocus): void;
+    toggle(): void;
+    openMenu(initialFocus?: ForComboboxInitialFocus): void;
+    closeMenu(reason: ForComboboxCloseReason): void;
+    /**
+     * The reason of the most recent close (or `null` before any close / after a
+     * fresh open). `[forComboboxContent]` reads this so a `'tab'` close skips the
+     * return-focus move — Tab has already advanced focus and re-focusing the
+     * trigger would steal it back. Only meaningful in the picker anatomy.
+     */
+    readonly lastCloseReason: Signal<ForComboboxCloseReason | null>;
+    /**
+     * Fires the `(autoFocusOnOpen)` output and returns whether the consumer
+     * vetoed (called `preventDefault()`). The picker anatomy moves focus into the
+     * input on open; a veto skips that imperative move. Editable anatomy never
+     * calls this (focus never moves).
+     */
+    emitAutoFocusOnOpen(): boolean;
+    /**
+     * Fires the `(autoFocusOnClose)` output and returns whether the consumer
+     * vetoed. The picker anatomy returns focus to the trigger on close; a veto
+     * skips it.
+     */
+    emitAutoFocusOnClose(): boolean;
+    /**
+     * Escape is consumer-owned and routed through the input directive (focus
+     * stays in the input), so it is invoked directly with the raw
+     * `KeyboardEvent` rather than through the dismissable layer.
+     */
+    emitEscapeKeyDown(event: KeyboardEvent): void;
+    /**
+     * Outside-interaction emit forwarders. `injectOverlayShell` builds and
+     * reuses one `VetoableNativeEvent` across the specific and composite
+     * channels, then hands it to these forwarders to fire the matching output
+     * and calls `requestClose` when un-vetoed.
+     */
+    emitPointerDownOutside(veto: VetoableNativeEvent<PointerEvent>): void;
+    emitFocusOutside(veto: VetoableNativeEvent<FocusEvent>): void;
+    emitInteractOutside(veto: VetoableNativeEvent<PointerEvent | FocusEvent>): void;
+    /** Implicit close requested by the shell after an un-vetoed outside interaction. */
+    requestClose(reason: 'pointerDownOutside' | 'focusOutside'): void;
+    /** Flip the `touched` model. Called by input on blur-to-outside and by dismiss events. */
+    markTouched(): void;
+}
+/**
+ * `ForCombobox<T>`'s generic does NOT flow to this token: an `InjectionToken`
+ * is a single runtime instance, so it is published at `ForComboboxContext<unknown>`.
+ * `injectComboboxContext<T>()` re-applies `T` with an `as unknown as` cast, and
+ * each piece (input, option, chip) relies on consumer discipline — the
+ * `[forComboboxOption][value]` and the root `[(value)]` must be the same `T`.
+ * There is no clean fix without abandoning the token pattern; the contract is
+ * the consumer's to honor. Object identity is reconciled at runtime via
+ * `isItemEqualToValue`, which bounds the practical blast radius of a mismatch.
+ */
+declare const FOR_COMBOBOX_CONTEXT: InjectionToken<ForComboboxContext<unknown>>;
+
+/**
+ * Headless implementation of the [WAI-ARIA combobox with listbox popup pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+ * 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 per-piece signatures (`[forComboboxOption][value]`,
+ * `[forComboboxChip][value]`) specialize accordingly. Object identity is
+ * resolved by the consumer-supplied `[isItemEqualToValue]` and labels by
+ * `[itemToStringLabel]`; the hidden inputs serialize via
+ * `[itemToFormValue]` (defaults to `JSON.stringify` for non-strings).
+ *
+ * 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 in/out and the listbox stays
+ *   open. Selected entries are typically rendered as chips inside
+ *   `[forComboboxChips]` next to the input.
+ *
+ * The visible input ("query") and the form value are separate two-way
+ * bindable models — the consumer keeps them in sync via filtering /
+ * display logic, and the primitive only commits to `value` when an option
+ * is explicitly activated.
+ *
+ * Filtering is **always** the consumer's responsibility — the primitive is
+ * headless and doesn't filter the registered options. Render the filtered
+ * subset with `@for` and the registry tracks them automatically.
+ */
+declare class ForCombobox<T = string> extends FormUiControlBase implements FormValueControl<readonly T[]>, ForComboboxContext<T> {
+    #private;
+    /**
+     * Two-way bindable. Visible input text. The `model()` change emitter
+     * (`(queryChange)`) fires only on internal mutations (option activation
+     * commit, `clear()`, multi-mode select reset, picker-anatomy reset on
+     * close), never on consumer writes via `[(query)]`.
+     */
+    readonly query: _angular_core.ModelSignal<string>;
+    /**
+     * Two-way bindable. Selected option values. Single mode (`multiple=false`)
+     * keeps 0 or 1 element; multi mode keeps any number. The `model()` change
+     * emitter (`(valueChange)`) fires only on internal selection changes,
+     * never on consumer writes via `[(value)]`.
+     */
+    readonly value: _angular_core.ModelSignal<readonly T[]>;
+    /**
+     * 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 /
+     * removed entries by id (or any other stable key) instead of by
+     * reference: `[isItemEqualToValue]="(a, b) => a.id === b.id"`.
+     */
+    readonly isItemEqualToValue: _angular_core.InputSignal<(a: T, b: T) => boolean>;
+    /**
+     * Render an item as a string label. Defaults to `String(item)`, which is
+     * identity for strings. Drives the visible input text after activation
+     * (when `commitOnSelect`) and the chip label fallback in multi mode.
+     * Override when binding object items so the directive can fall back to
+     * a meaningful label without relying on the option cache being warm:
+     * `[itemToStringLabel]="(it) => it.name"`.
+     */
+    readonly itemToStringLabel: _angular_core.InputSignal<(item: T) => string>;
+    /**
+     * 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"`.
+     */
+    readonly itemToFormValue: _angular_core.InputSignal<(item: T) => string>;
+    /**
+     * Two-way bindable. Whether the listbox is currently shown. Internal
+     * transitions: input typing (when `openOnQuery`), focus (when
+     * `openOnFocus`), ArrowDown / ArrowUp, Escape, outside dismissal,
+     * single-mode option activation.
+     */
+    readonly open: _angular_core.ModelSignal<boolean>;
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Autocomplete mode applied to the input. Mirrors the
+     * [WAI-ARIA `aria-autocomplete` property](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#wai-ariaroles,states,andproperties)
+     * and drives whether the listbox auto-opens on query and whether the
+     * input gets inline-completed with the first match. Renamed from
+     * `autocomplete` so consumers don't conflate it with the native HTML
+     * `autocomplete` attribute (which the directive forces to `"off"`).
+     */
+    readonly autocompleteMode: _angular_core.InputSignal<ForComboboxAutocomplete>;
+    /** Open the listbox when the input gains focus. Off by default — opening on query / arrow keys is the standard ecosystem behavior. */
+    readonly openOnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Open the listbox when the user starts typing. On by default. Only honored when `autocompleteMode` includes a listbox (`'list'` or `'both'`). */
+    readonly openOnQuery: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * In single mode, copy the activated option's label into `query`. In
+     * multi mode, instead **clear** the query so the user can search the
+     * next item. On by default in both. Set `false` to leave `query`
+     * untouched on activation in either mode.
+     *
+     * Governs the **editable anatomy** only. In the picker anatomy (a
+     * `[forComboboxTrigger]` is registered) the in-panel input is a transient
+     * filter, not the value display: the single-mode label copy is always
+     * skipped and `query` resets to `''` on close regardless of this flag.
+     */
+    readonly commitOnSelect: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When the user edits the query, automatically clear the committed `value`. Off by default — most apps want the value preserved across query edits. Single-mode only. */
+    readonly clearOnQueryChange: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Auto-highlight the first enabled option whenever the listbox is open
+     * and no activedescendant is set (e.g. after the consumer's filter
+     * removed the previously-active option). On by default. Set `false` for
+     * "user must arrow before anything is highlighted" behavior.
+     */
+    readonly autoHighlight: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Writing direction. Drives chip-cluster keyboard navigation (ArrowLeft /
+     * ArrowRight semantics swap in RTL so they follow the visual order, not DOM
+     * order) and the default `align` of the listbox (anchors to the right edge
+     * of the input in RTL). 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
+     * and the resolved value is reflected to the host `dir` attribute.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /**
+     * Side the listbox is anchored to. Defaults to `'bottom'`. Pair with
+     * `align` for the full positioning API.
+     */
+    readonly side: _angular_core.InputSignal<FloatingSide | undefined>;
+    /**
+     * Alignment along the chosen `side`. When unset, defaults to `'start'`
+     * in LTR and `'end'` in RTL (per `dir`). Set explicitly to pin an
+     * alignment regardless of writing direction.
+     *
+     * The input is aliased to `align`; consumers bind `[align]="..."` and
+     * read the effective value via the public `align` computed below.
+     */
+    readonly _alignInput: _angular_core.InputSignal<FloatingAlign | undefined>;
+    readonly align: _angular_core.Signal<FloatingAlign>;
+    /** Gap (px) between input and listbox along the main axis. Default `4`. */
+    readonly sideOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Gap (px) along the cross axis. Default `0`. */
+    readonly alignOffset: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** When `true` (default), `flip` and `shift` keep the listbox inside the viewport. */
+    readonly avoidCollisions: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Padding (px) applied uniformly to flip / shift / size. Default `8`. */
+    readonly collisionPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Padding (px) for the `arrow` middleware. Default `0`. */
+    readonly arrowPadding: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** Stickiness behaviour for `shift`. Default `'partial'`. */
+    readonly sticky: _angular_core.InputSignal<false | "partial" | "always">;
+    /** When `true`, sets `data-detached=""` while the input is scrolled off-screen. */
+    readonly hideWhenDetached: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * 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).
+     */
+    readonly clipUntilPositioned: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly loop: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** When true (default), Escape, pointer-down outside, and focus outside close the listbox. */
+    readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * When true (default), focus returns to the `[forComboboxTrigger]` on close.
+     * Only relevant in the picker anatomy (a trigger is registered) — in the
+     * editable anatomy focus never leaves the input, so there is nothing to
+     * return.
+     */
+    readonly returnFocus: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Manual `aria-label` on the listbox (`[forComboboxList]`, or `[forComboboxContent]` in the editable anatomy) when the input isn't a meaningful name. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Total number of options in the consumer's source array. Set when wiring
+     * up a virtualized listbox (only the visible window is rendered) so the
+     * directive can reflect `aria-setsize` and walk the snapshot for
+     * navigation past the rendered range. Defaults to `undefined`, in which
+     * case the directive falls back to `options().length` (the live registry).
+     */
+    readonly totalCount: _angular_core.InputSignalWithTransform<number | undefined, unknown>;
+    /**
+     * Inclusive-exclusive `[start, end)` range of options currently rendered
+     * in the DOM. Used by `navigate()` to translate "move to absolute
+     * position N" into either an in-window highlight update or a request to
+     * the consumer to scroll N into view (`(scrollToIndex)`). When
+     * `undefined` (default), navigation assumes every option in the snapshot
+     * is rendered — appropriate for non-virtualized lists.
+     */
+    readonly visibleRange: _angular_core.InputSignal<readonly [number, number] | undefined>;
+    /**
+     * Emitted when keyboard navigation needs to land on an option whose
+     * absolute index falls outside `visibleRange()`. Wire this to the
+     * consumer's virtualizer (`scrollToIndex(idx)` on `@tanstack/virtual`,
+     * `virtua`, etc.); once the option mounts, the directive seeds
+     * `aria-activedescendant` automatically.
+     */
+    readonly scrollToIndex: _angular_core.OutputEmitterRef<number>;
+    readonly escapeKeyDown: _angular_core.OutputEmitterRef<VetoableNativeEvent<KeyboardEvent>>;
+    readonly pointerDownOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent>>;
+    readonly focusOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<FocusEvent>>;
+    readonly interactOutside: _angular_core.OutputEmitterRef<VetoableNativeEvent<PointerEvent | FocusEvent>>;
+    /**
+     * _(picker anatomy only)_ Fires just before focus moves into the input on
+     * open. Call `preventDefault()` on the emitted veto to skip the imperative
+     * focus move. Only emitted when a `[forComboboxTrigger]` is registered — the
+     * editable anatomy keeps focus in the input the whole time and has no move to
+     * veto.
+     */
+    readonly autoFocusOnOpen: _angular_core.OutputEmitterRef<VetoableEvent>;
+    /**
+     * _(picker anatomy only)_ Fires just before focus returns to the trigger on
+     * close. Call `preventDefault()` on the veto to suppress the return-focus.
+     */
+    readonly autoFocusOnClose: _angular_core.OutputEmitterRef<VetoableEvent>;
+    readonly inputId: _angular_core.WritableSignal<string>;
+    readonly contentId: _angular_core.WritableSignal<string>;
+    readonly listId: _angular_core.WritableSignal<string>;
+    readonly input: _angular_core.Signal<HTMLInputElement | null>;
+    readonly trigger: _angular_core.Signal<HTMLElement | null>;
+    /**
+     * Element floating-ui anchors the listbox against. Resolution order:
+     * explicit `[forComboboxAnchor]` → `[forComboboxTrigger]` (picker anatomy) →
+     * the input (editable anatomy fallback, so existing comboboxes keep their
+     * behavior). Decoupled from `input` so the input keeps driving
+     * `aria-controls`, `aria-activedescendant`, keyboard interaction, and its
+     * dismissal exemption regardless of where the listbox paints.
+     */
+    readonly anchor: _angular_core.Signal<ReferenceElement | null>;
+    readonly content: _angular_core.Signal<HTMLElement | null>;
+    readonly list: _angular_core.Signal<HTMLElement | null>;
+    /** True once a `[forComboboxList]` has registered (picker anatomy). */
+    readonly hasList: _angular_core.Signal<boolean>;
+    /**
+     * Id of the element carrying `role="listbox"`: the list when one is
+     * registered (picker anatomy), otherwise the content surface (editable
+     * anatomy). The input targets this with `aria-controls`.
+     */
+    readonly listboxId: _angular_core.Signal<string>;
+    readonly options: _angular_core.Signal<readonly ForComboboxOptionHandle<T>[]>;
+    readonly chips: _angular_core.Signal<readonly ForComboboxChipHandle<T>[]>;
+    readonly initialFocus: _angular_core.Signal<ForComboboxInitialFocus>;
+    readonly lastCloseReason: _angular_core.Signal<ForComboboxCloseReason | null>;
+    readonly activeId: _angular_core.Signal<string | null>;
+    readonly selected: _angular_core.Signal<readonly {
+        value: T;
+        label: string;
+    }[]>;
+    /**
+     * Read-only single-select convenience view of {@link value}. Returns the
+     * sole selected item when exactly one is selected, otherwise `null` (empty
+     * selection, or multiple selections in `multiple` mode). Lets single-select
+     * consumers read `selectedItem()` instead of unwrapping `value()[0]`. The
+     * array-backed `value` model remains the source of truth and the
+     * `FormValueControl` contract; this is a derived accessor. Distinct from
+     * {@link selected}, which pairs every selected value with its resolved
+     * label for chip rendering.
+     */
+    readonly selectedItem: _angular_core.Signal<T | null>;
+    protected fieldLabelledElement(): HTMLElement | null;
+    protected fieldLabelledElementId(): string;
+    constructor();
+    registerInput(el: HTMLInputElement): void;
+    unregisterInput(el: HTMLInputElement): void;
+    registerAnchor(el: HTMLElement): void;
+    unregisterAnchor(el: HTMLElement): void;
+    registerTrigger(el: HTMLElement): void;
+    unregisterTrigger(el: HTMLElement): void;
+    registerContent(el: HTMLElement): void;
+    unregisterContent(el: HTMLElement): void;
+    registerList(el: HTMLElement): void;
+    unregisterList(el: HTMLElement): void;
+    registerOption(handle: ForComboboxOptionHandle<T>): void;
+    unregisterOption(handle: ForComboboxOptionHandle<T>): void;
+    registerChip(handle: ForComboboxChipHandle<T>): void;
+    unregisterChip(handle: ForComboboxChipHandle<T>): void;
+    isSelected(v: T): boolean;
+    isActive(id: string): boolean;
+    isPointerSuppressed(): boolean;
+    activate(handle: ForComboboxOptionHandle<T>): void;
+    removeValue(v: T): void;
+    activateActive(): boolean;
+    navigate(direction: 'next' | 'prev' | 'first' | 'last'): void;
+    setQueryFromInput(query: string): void;
+    setActiveId(id: string | null): void;
+    cachedOptions(): readonly {
+        id: string;
+        value: T;
+        label: string;
+    }[];
+    clear(clearQuery?: boolean): void;
+    setInitialFocus(target: ForComboboxInitialFocus): void;
+    toggle(): void;
+    openMenu(initialFocus?: ForComboboxInitialFocus): void;
+    closeMenu(reason: ForComboboxCloseReason): void;
+    /** Fire `(autoFocusOnOpen)` and report whether the consumer vetoed the focus move. */
+    emitAutoFocusOnOpen(): boolean;
+    /** Fire `(autoFocusOnClose)` and report whether the consumer vetoed the return-focus. */
+    emitAutoFocusOnClose(): boolean;
+    emitEscapeKeyDown(event: KeyboardEvent): void;
+    /**
+     * 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: VetoableNativeEvent<PointerEvent>): void;
+    emitFocusOutside(veto: VetoableNativeEvent<FocusEvent>): void;
+    emitInteractOutside(veto: VetoableNativeEvent<PointerEvent | FocusEvent>): void;
+    /**
+     * Implicit close requested by the shell after an un-vetoed outside
+     * interaction. Marks the control touched and closes with the channel's
+     * reason.
+     */
+    requestClose(reason: 'pointerDownOutside' | 'focusOutside'): void;
+    markTouched(): void;
+    protected onFocusOut(event: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForCombobox<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForCombobox<any>, "[forCombobox]", ["forCombobox"], { "query": { "alias": "query"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "isItemEqualToValue": { "alias": "isItemEqualToValue"; "required": false; "isSignal": true; }; "itemToStringLabel": { "alias": "itemToStringLabel"; "required": false; "isSignal": true; }; "itemToFormValue": { "alias": "itemToFormValue"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "autocompleteMode": { "alias": "autocompleteMode"; "required": false; "isSignal": true; }; "openOnFocus": { "alias": "openOnFocus"; "required": false; "isSignal": true; }; "openOnQuery": { "alias": "openOnQuery"; "required": false; "isSignal": true; }; "commitOnSelect": { "alias": "commitOnSelect"; "required": false; "isSignal": true; }; "clearOnQueryChange": { "alias": "clearOnQueryChange"; "required": false; "isSignal": true; }; "autoHighlight": { "alias": "autoHighlight"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; "side": { "alias": "side"; "required": false; "isSignal": true; }; "_alignInput": { "alias": "align"; "required": false; "isSignal": true; }; "sideOffset": { "alias": "sideOffset"; "required": false; "isSignal": true; }; "alignOffset": { "alias": "alignOffset"; "required": false; "isSignal": true; }; "avoidCollisions": { "alias": "avoidCollisions"; "required": false; "isSignal": true; }; "collisionPadding": { "alias": "collisionPadding"; "required": false; "isSignal": true; }; "arrowPadding": { "alias": "arrowPadding"; "required": false; "isSignal": true; }; "sticky": { "alias": "sticky"; "required": false; "isSignal": true; }; "hideWhenDetached": { "alias": "hideWhenDetached"; "required": false; "isSignal": true; }; "clipUntilPositioned": { "alias": "clipUntilPositioned"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "returnFocus": { "alias": "returnFocus"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "totalCount": { "alias": "totalCount"; "required": false; "isSignal": true; }; "visibleRange": { "alias": "visibleRange"; "required": false; "isSignal": true; }; }, { "query": "queryChange"; "value": "valueChange"; "open": "openChange"; "scrollToIndex": "scrollToIndex"; "escapeKeyDown": "escapeKeyDown"; "pointerDownOutside": "pointerDownOutside"; "focusOutside": "focusOutside"; "interactOutside": "interactOutside"; "autoFocusOnOpen": "autoFocusOnOpen"; "autoFocusOnClose": "autoFocusOnClose"; }, never, never, true, never>;
+}
+
+/**
+ * Optional positioning anchor. When present, `[forComboboxContent]` is
+ * positioned against this element instead of `[forComboboxInput]` — useful
+ * when the input lives inside a decorated field box (padding, prefix icon,
+ * clear button, chip cluster) and the listbox should match the visible field
+ * rather than the inner `<input>`.
+ *
+ * Only positioning changes: the input still owns `aria-controls`,
+ * `aria-expanded`, `aria-activedescendant`, keyboard interaction, and its
+ * exemption from outside-pointer dismissal. If no anchor is registered the
+ * listbox falls back to anchoring against the input, so existing usages are
+ * unaffected.
+ *
+ * At most one `[forComboboxAnchor]` may be registered per `[forCombobox]`; a
+ * second one throws.
+ *
+ * ```html
+ * <div forCombobox [(value)]="v" [(query)]="q">
+ *   <div forComboboxAnchor class="field-box">
+ *     <icon />
+ *     <input forComboboxInput />
+ *     <button class="clear">×</button>
+ *   </div>
+ *   @if (open()) {
+ *     <div forComboboxContent>…</div>
+ *   }
+ * </div>
+ * ```
+ */
+declare class ForComboboxAnchor {
+    #private;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxAnchor, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxAnchor, "[forComboboxAnchor]", ["forComboboxAnchor"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Button that opens the listbox and keeps showing the committed selection
+ * (label + icon) while the search input lives **inside** the panel — the
+ * "combobox with trigger" / picker anatomy. Apply on
+ * a real `<button>` so Space / Enter dispatch native click events that toggle
+ * via `(click)`.
+ *
+ * Registering a trigger switches the combobox into the picker anatomy: it
+ * becomes the default positioning anchor (after an explicit
+ * `[forComboboxAnchor]`), focus moves into `[forComboboxInput]` on open and
+ * returns to the trigger on close (the standard `(autoFocusOnOpen)` /
+ * `(autoFocusOnClose)` vetoable hooks now fire), and `[forComboboxContent]`
+ * expects an inner `[forComboboxList]` to carry the listbox role.
+ *
+ * Wires `aria-haspopup="listbox"`, `aria-expanded`, and `aria-controls`
+ * (pointing to the popup surface while open). Native `disabled` reflects
+ * `effectiveDisabled` (single-purpose trigger). The trigger is exempt from the
+ * popup's dismissable layer — clicks on it route through `(click)` instead of
+ * racing an outside-pointer dismissal.
+ *
+ * The root is normally resolved via DI from the enclosing `[forCombobox]`.
+ * 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: `[forComboboxTrigger]="root"` with `#root="forCombobox"`.
+ *
+ * Keyboard:
+ * - **Click / Enter / Space** — toggle (open moves focus into the input).
+ * - **ArrowDown** — open with the first enabled option highlighted.
+ * - **ArrowUp** — open with the last enabled option highlighted.
+ */
+declare class ForComboboxTrigger<T = unknown> {
+    #private;
+    /**
+     * Optional explicit reference to the `[forCombobox]` root, named after the
+     * selector `routerLink`-style. The bare valueless attribute keeps resolving
+     * the enclosing root via DI; pass the root explicitly
+     * (`[forComboboxTrigger]="root"`, with `#root="forCombobox"`) 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.
+     */
+    readonly forComboboxTrigger: _angular_core.InputSignal<"" | ForComboboxContext<T>>;
+    protected readonly ctx: _angular_core.Signal<ForComboboxContext<T>>;
+    constructor();
+    protected onClick(): void;
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxTrigger<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxTrigger<any>, "[forComboboxTrigger]", ["forComboboxTrigger"], { "forComboboxTrigger": { "alias": "forComboboxTrigger"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * The combobox `<input role="combobox">`. Owns the visible text and all
+ * keyboard interaction. Apply on a real `<input>` so the browser's native
+ * caret / selection semantics drive inline-autocomplete and so the form
+ * still behaves like a text field for screen readers.
+ *
+ * Wires `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls`,
+ * `aria-autocomplete`, and `aria-activedescendant` (per APG combobox).
+ * Focus stays on the input — arrow keys move the listbox's *active
+ * descendant* via id reference, never moving DOM focus into the listbox.
+ *
+ * Keyboard:
+ * - **ArrowDown / ArrowUp** — open + move activedescendant.
+ * - **Home / End** (when open) — first / last enabled option.
+ * - **PageUp / PageDown** (when open) — first / last enabled option.
+ * - **Enter** (when open) — activate the activedescendant; no-op otherwise.
+ * - **Escape** (when open) — close (focus stays in input). On the
+ *   open→closed transition the input value is re-synced to `query()` even
+ *   while focused, so a consumer restoring the committed label from an
+ *   `(openChange)` handler renders without reaching for the DOM.
+ * - **Tab** (when open) — close and let Tab flow to the next focusable.
+ * - Printable keys: update `query` and (if `autocompleteMode` includes `'inline'`)
+ *   complete the rest of the first match in the input as selected text.
+ */
+declare class ForComboboxInput {
+    #private;
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    protected readonly ariaAutocomplete: _angular_core.Signal<forty_cdk_combobox.ForComboboxAutocomplete>;
+    constructor();
+    protected onCompositionStart(): void;
+    protected onCompositionEnd(): void;
+    protected onInput(event: Event): void;
+    protected onKeyDown(event: KeyboardEvent): void;
+    protected onFocus(): void;
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxInput, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxInput, "[forComboboxInput]", ["forComboboxInput"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * The floating surface, portaled to `document.body` and positioned by
+ * `@floating-ui/dom` against the anchor (explicit `[forComboboxAnchor]` →
+ * `[forComboboxTrigger]` → input).
+ *
+ * Two anatomies, picked by whether an inner `[forComboboxList]` is present:
+ *
+ * - **Editable (no list)** — content itself carries `role="listbox"`,
+ *   `tabindex="-1"`, `aria-multiselectable`, `aria-setsize`, and the labelled
+ *   role (`aria-label` / `aria-labelledby`). The input's `aria-controls` points
+ *   here. This is the original combobox; nothing about it changes.
+ * - **Picker (list present)** — content drops the listbox semantics and becomes
+ *   a neutral popup surface; `[forComboboxList]` takes over the listbox role and
+ *   owns the options, the input lives inside the panel, and the input's
+ *   `aria-controls` points to the list. Keeps `data-state` and the positioner +
+ *   dismissable layer unchanged.
+ *
+ * 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 for
+ * pointer-down outside / focus outside; the input and (picker anatomy) the
+ * trigger are exempt from outside checks.
+ *
+ * Focus:
+ * - **Editable anatomy** — focus stays in the input across the whole open
+ *   lifecycle; the directive never moves DOM focus and exposes no focus hooks.
+ *   Active-option highlighting is `aria-activedescendant`-driven.
+ * - **Picker anatomy** — on open, focus moves into the input (the search field
+ *   inside the panel); on close it returns to the trigger. Both moves are
+ *   vetoable via `(autoFocusOnOpen)` / `(autoFocusOnClose)` on `[forCombobox]`,
+ *   and the return is gated by `[returnFocus]`. Escape stays owned by the input.
+ *
+ * The lifecycle (positioner + dismissable layer, plus the picker anatomy's
+ * focus bundles) is owned by the shared `injectOverlayShell` helper.
+ */
+declare class ForComboboxContent {
+    #private;
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    /** When a `[forComboboxList]` is registered the listbox semantics live there, not here. */
+    protected readonly hasList: _angular_core.Signal<boolean>;
+    /**
+     * Reflects `aria-setsize` when the consumer wires up `[totalCount]` for
+     * virtualization (editable anatomy only — the picker anatomy's list owns it).
+     * Falls back to `null` (omitted) otherwise — leaving the default
+     * option-count semantics screen readers already infer.
+     */
+    protected readonly ariaSetSize: _angular_core.Signal<string | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxContent, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxContent, "[forComboboxContent]", ["forComboboxContent"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * The `role="listbox"` element of the picker anatomy. Nest it inside
+ * `[forComboboxContent]` next to `[forComboboxInput]` so the popup surface can
+ * hold a search field without violating `aria-required-owned-elements` (a
+ * `listbox` may only own `option` / `group` children). The list owns the
+ * options; `[forComboboxContent]` becomes a neutral popup surface.
+ *
+ * ```html
+ * <div forComboboxContent>
+ *   <input forComboboxInput />
+ *   <div forComboboxList>
+ *     @for (item of filtered(); track item.id) {
+ *       <div forComboboxOption [value]="item">{{ item.label }}</div>
+ *     }
+ *   </div>
+ * </div>
+ * ```
+ *
+ * Carries `role="listbox"`, `tabindex="-1"` (focus stays in the input,
+ * activedescendant-driven), `aria-multiselectable` in multi mode,
+ * `aria-setsize` when virtualizing, and the labelled-role `aria-label` /
+ * `aria-labelledby`. Its id is what the input's `aria-controls` references in
+ * the picker anatomy.
+ *
+ * When no `[forComboboxList]` is present, `[forComboboxContent]` itself carries
+ * the listbox semantics (the editable anatomy) — this part is additive and
+ * non-breaking.
+ */
+declare class ForComboboxList {
+    #private;
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    /**
+     * Reflects `aria-setsize` when the consumer wires up `[totalCount]` for
+     * virtualization. Falls back to `null` (omitted) otherwise.
+     */
+    protected readonly ariaSetSize: _angular_core.Signal<string | null>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxList, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxList, "[forComboboxList]", ["forComboboxList"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Injection key the `[forComboboxIndicator]` uses to resolve its parent
+ * option, decoupled from the concrete `ForComboboxOption` class.
+ * `ForComboboxOption` 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_COMBOBOX_OPTION, useExisting: MtxComboboxOption }`)
+ * and the indicator keeps resolving — see `docs/wrapping-form-primitives.md`.
+ */
+declare const FOR_COMBOBOX_OPTION: InjectionToken<ForComboboxOption<string>>;
+/**
+ * One option inside a `[forComboboxContent]`. Apply on whatever element
+ * fits the design — typically a `<div>` or `<li>`. Click activates:
+ * single mode replaces `[(value)]` and closes the listbox; multi mode
+ * toggles the value in/out and keeps the listbox open.
+ *
+ * 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
+ * `[forCombobox]` must be parameterized over the same `T`.
+ *
+ * `aria-selected` reflects different things in single vs. multi:
+ * - **Single mode**: the option that's the current activedescendant
+ *   (Enter would activate it). Matches APG select-only-combobox.
+ * - **Multi mode**: every option currently in `value()` carries
+ *   `aria-selected="true"` (multiple "selected" entries simultaneously).
+ *   Matches APG multi-select combobox.
+ *
+ * `data-state="checked" | "unchecked"` always reflects membership in
+ * `value()` regardless of mode, so consumers can paint a checkmark with
+ * pure CSS in either mode. `data-highlighted` marks the option that is
+ * the current activedescendant — shared across the
+ * library's roving / activedescendant primitives.
+ *
+ * Hovering an option also makes it the activedescendant, mirroring native
+ * menu / select behavior so mouse and keyboard intent stay synchronized.
+ */
+declare class ForComboboxOption<T = string> {
+    #private;
+    /**
+     * Stable identifier serialized into `[(value)]` and the hidden input.
+     * Defaults to `string` for back-compat; bind an object to specialize
+     * the parent `[forCombobox]` over a richer `T`. The parent's
+     * `[isItemEqualToValue]` decides how options are matched against the
+     * committed selection.
+     */
+    readonly value: _angular_core.InputSignal<T>;
+    /**
+     * Visible label used by `[forComboboxInput]` for inline autocomplete
+     * matching, by `commitOnSelect` to populate the input on selection,
+     * and by typeahead / display utilities. When omitted: for string
+     * `value` falls back to the trimmed `textContent` of the host element;
+     * for object `value` falls back to the parent's `itemToStringLabel(value)`.
+     */
+    readonly label: _angular_core.InputSignal<string | null>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Absolute index of this option in the consumer's source array. Required
+     * when wiring up a virtualized listbox so navigation past the rendered
+     * window can resolve indices to options (and emit `(scrollToIndex)` when
+     * needed). Leave `null` for non-virtualized lists — the directive then
+     * falls back to DOM order.
+     */
+    readonly posInSet: _angular_core.InputSignal<number | null>;
+    readonly id: _angular_core.Signal<string>;
+    readonly selected: _angular_core.Signal<boolean>;
+    /** True when this option is the current activedescendant. Reflected as `data-highlighted`. */
+    readonly highlighted: _angular_core.Signal<boolean>;
+    readonly effectiveDisabled: _angular_core.Signal<boolean>;
+    protected readonly ariaSelected: _angular_core.Signal<"true" | "false">;
+    /** Reflects `aria-posinset` (1-based) when virtualizing. Falls back to DOM order otherwise. */
+    protected readonly ariaPosInSet: _angular_core.Signal<string | null>;
+    /** Reflects `aria-setsize` when the consumer wires up `[totalCount]`. */
+    protected readonly ariaSetSize: _angular_core.Signal<string | null>;
+    constructor();
+    protected onClick(): void;
+    protected onPointerMove(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxOption<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxOption<any>, "[forComboboxOption]", ["forComboboxOption"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "posInSet": { "alias": "posInSet"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Visibility helper inside a `[forComboboxOption]`. The directive flips a
+ * `[hidden]` host binding so the consumer can keep the checkmark / icon
+ * inline without extra `@if` glue:
+ *
+ * ```html
+ * <div forComboboxOption value="apple">
+ *   <span forComboboxIndicator>✓</span>
+ *   Apple
+ * </div>
+ * ```
+ *
+ * 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.
+ *
+ * In multi mode the indicator follows membership in `value()`, matching the
+ * option's own `data-state` semantics (a checkmark per selected option).
+ */
+declare class ForComboboxIndicator {
+    protected readonly option: ForComboboxOption<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxIndicator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxIndicator, "[forComboboxIndicator]", ["forComboboxIndicator"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Empty-state slot, shown when the listbox has no registered options.
+ * The directive hides the message when options exist so the consumer can
+ * keep it inline in the template — no `@if` needed. 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:
+ *
+ * ```html
+ * <div forComboboxContent>
+ *   @for (option of filtered(); track option.id) {
+ *     <div forComboboxOption [value]="option.id">{{ option.label }}</div>
+ *   }
+ *   <div forComboboxEmpty>No matches.</div>
+ * </div>
+ * ```
+ *
+ * Carries `role="status"` and `aria-live="polite"` so screen readers
+ * announce the message when it appears.
+ */
+declare class ForComboboxEmpty {
+    #private;
+    protected readonly shouldShow: _angular_core.Signal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxEmpty, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxEmpty, "[forComboboxEmpty]", ["forComboboxEmpty"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Live-region slot for async-filtering feedback (loading, result count,
+ * "no matches", error messages). Apply on a `<div>` inside the listbox or
+ * next to the input. The directive sets `role="status"` and
+ * `aria-live="polite"` so messages projected as content are announced to
+ * screen readers when they change.
+ *
+ * The directive is **content-driven** — it does not pick or render a
+ * message. Project whatever the consumer wants and use the exposed
+ * `count` signal (or `forComboboxStatus` template ref) to interpolate
+ * the option count when relevant.
+ *
+ * ```html
+ * <div forCombobox [(query)]="query" [(value)]="value" [(open)]="open">
+ *   <input forComboboxInput placeholder="Search…" />
+ *   @if (open()) {
+ *     <div forComboboxContent>
+ *       <div forComboboxStatus #status="forComboboxStatus">
+ *         @if (loading()) {
+ *           Searching…
+ *         } @else if (status.count() === 0) {
+ *           No matches.
+ *         } @else {
+ *           {{ status.count() }} results.
+ *         }
+ *       </div>
+ *       @for (it of filtered(); track it.id) {
+ *         <div forComboboxOption [value]="it.id">{{ it.label }}</div>
+ *       }
+ *     </div>
+ *   }
+ * </div>
+ * ```
+ *
+ * For an empty-only slot that auto-hides when there are options, use
+ * `[forComboboxEmpty]`. `[forComboboxStatus]` stays mounted regardless
+ * so transitions like "loading → 5 results" are announced as a single
+ * change to the same live region.
+ */
+declare class ForComboboxStatus {
+    #private;
+    /**
+     * Number of currently registered options. Reflects the live size of the
+     * filtered listbox so the consumer can interpolate `{{ status.count() }}`
+     * inside the live region.
+     */
+    readonly count: _angular_core.Signal<number>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxStatus, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxStatus, "[forComboboxStatus]", ["forComboboxStatus"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Optional clear button. Apply on a `<button type="button">` so Space /
+ * Enter dispatch a native click. Clicking calls `clear()` on the root,
+ * which resets `[(value)]` and `[(query)]` and the activedescendant.
+ *
+ * The directive hides the button when there's nothing to clear (no value,
+ * empty query) so the consumer can leave it inline in the template without
+ * an extra `@if`. 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.
+ */
+declare class ForComboboxClear {
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    protected readonly hasContent: _angular_core.Signal<boolean>;
+    /** Disabled when the combobox is disabled or read-only — the clear action is unavailable. */
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    protected onClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxClear, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxClear, "[forComboboxClear]", ["forComboboxClear"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Multi-mode chips area. Wrap the chips and the `<input>` together so the
+ * combobox visually presents a single editable region:
+ *
+ * ```html
+ * <div forCombobox multiple [(value)]="tags" [(query)]="query" [(open)]="open">
+ *   <div forComboboxChips>
+ *     @for (chip of selected(); track chip.value) {
+ *       <span forComboboxChip [value]="chip.value">
+ *         {{ chip.label }}
+ *         <button forComboboxChipRemove></button>
+ *       </span>
+ *     }
+ *     <input forComboboxInput />
+ *   </div>
+ *   …
+ * </div>
+ * ```
+ *
+ * Carries `role="group"` with `aria-label="Selected items"` (override via
+ * `[ariaLabel]`) so screen readers announce the chip cluster as a single
+ * unit. The directive itself doesn't manage focus or selection — the
+ * chips and the input own that — but its presence groups them for
+ * assistive tech.
+ */
+declare class ForComboboxChips {
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    /**
+     * Accessible name for the chip cluster, exposed as `role="group"`'s
+     * `aria-label` so screen readers announce the selected chips as a single
+     * unit. Defaults to `'Selected items'`; set `[ariaLabel]` to localize or
+     * override it.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxChips, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxChips, "[forComboboxChips]", ["forComboboxChips"], { "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * One chip representing a selected value in multi mode. Apply on a
+ * `<span>` (or any inline-block element) inside `[forComboboxChips]`.
+ * The chip is **out of the Tab cycle** (`tabindex="-1"`) by design:
+ * the user reaches it via the input's Backspace heuristic (Backspace on
+ * an empty input focuses the last chip), then navigates between chips
+ * with ArrowLeft / ArrowRight or removes them with Backspace / Delete.
+ *
+ * Keyboard while the chip has focus (LTR; the ArrowLeft/Right roles swap
+ * in RTL so they always follow visual order):
+ * - **ArrowLeft** — focus the previous chip; bounces if first.
+ * - **ArrowRight** — focus the next chip; if at the last, focus the input.
+ * - **Backspace / Delete** — remove this chip + focus the previous chip,
+ *   or the next chip when there is no previous one (so removing the first
+ *   chip lands on the new first chip), falling back to the input only when
+ *   the removed chip was the last one standing.
+ * - **Escape** — return focus to the input.
+ *
+ * Click on the chip body (excluding the remove button) just focuses the
+ * chip — useful as an alternative to the Backspace path.
+ */
+declare class ForComboboxChip<T = string> {
+    #private;
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<T>;
+    /**
+     * The value this chip represents — must match an entry in
+     * `[forCombobox][(value)]` per the parent's `[isItemEqualToValue]`.
+     * Generic over `T` (default `string`); inferred from the binding
+     * (`[value]="someObject"` specializes `T`).
+     */
+    readonly value: _angular_core.InputSignal<T>;
+    /**
+     * `data-value` reflection — for string `T` this is the value verbatim
+     * (unchanged from the pre-generic behaviour); for object `T` it uses
+     * the parent's `itemToFormValue` so the attribute carries the same
+     * wire format as the hidden inputs (typically JSON or a per-item id).
+     */
+    protected readonly dataValue: _angular_core.Signal<string>;
+    /** Resolved label of the underlying option, used by `[forComboboxChipRemove]` for its `aria-label`. */
+    readonly label: _angular_core.Signal<string>;
+    constructor();
+    protected onKeyDown(event: KeyboardEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxChip<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxChip<any>, "[forComboboxChip]", ["forComboboxChip"], { "value": { "alias": "value"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Remove button inside a `[forComboboxChip]`. Apply on a
+ * `<button type="button">` so click and Space / Enter (when focused) all
+ * trigger the same removal flow. The button is out of the Tab cycle
+ * (`tabindex="-1"`) so the user navigates the chip cluster via the chip's
+ * own ArrowLeft/Right + Backspace/Delete keys; this button exists for
+ * mouse / touch users.
+ *
+ * The host carries a generated `aria-label` ("Remove `<chip label>`")
+ * derived from the parent chip's resolved option label.
+ */
+declare class ForComboboxChipRemove {
+    #private;
+    protected readonly ctx: forty_cdk_combobox.ForComboboxContext<unknown>;
+    /** Disabled when the combobox is disabled or read-only — chip removal is unavailable. */
+    protected readonly isDisabled: _angular_core.Signal<boolean>;
+    constructor();
+    protected readonly ariaLabel: _angular_core.Signal<string>;
+    protected onClick(event: MouseEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxChipRemove, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxChipRemove, "[forComboboxChipRemove]", ["forComboboxChipRemove"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Optional grouping wrapper inside a `[forComboboxContent]`. Renders
+ * `role="group"` and references the descendant `[forComboboxGroupLabel]`
+ * (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.
+ */
+declare class ForComboboxGroup {
+    #private;
+    /** The id of the registered group label (or `null` if none). */
+    readonly labelId: _angular_core.Signal<string | null>;
+    /** Called by `ForComboboxGroupLabel` on mount. */
+    registerLabel(id: string): void;
+    /** Called by `ForComboboxGroupLabel` on destroy. Idempotent. */
+    unregisterLabel(id: string): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxGroup, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxGroup, "[forComboboxGroup]", ["forComboboxGroup"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Visible label for a `[forComboboxGroup]`. Generates a stable id and
+ * registers with its parent group so the group's `aria-labelledby` points
+ * at this element.
+ */
+declare class ForComboboxGroupLabel {
+    /** Stable host id used by the parent group's `aria-labelledby`. */
+    readonly id: Signal<string>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxGroupLabel, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxGroupLabel, "[forComboboxGroupLabel]", ["forComboboxGroupLabel"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Decorative separator between options or groups inside a
+ * `[forComboboxContent]`. Carries `role="separator"` and is intentionally
+ * not registered with the listbox's option collection, so keyboard
+ * navigation skips it automatically.
+ */
+declare class ForComboboxSeparator {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForComboboxSeparator, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForComboboxSeparator, "[forComboboxSeparator]", ["forComboboxSeparator"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Defaults inherited by descendant comboboxes in the surrounding injector
+ * scope. Configure with `provideForComboboxDefaults` either at the
+ * application root or in any component's `providers` array; partial
+ * overrides merge with the parent scope.
+ */
+interface ForComboboxDefaults {
+    /**
+     * Distance (px) between the combobox input/trigger and the floating
+     * content along the resolved `side` axis, for comboboxes that don't
+     * override `sideOffset` locally.
+     */
+    sideOffset: number;
+    /**
+     * Padding (px) added to the viewport edges for collision-aware
+     * positioning, for comboboxes that don't override `collisionPadding`
+     * locally. Higher values keep the floating content further from the edge
+     * when `flip` / `shift` runs.
+     */
+    collisionPadding: number;
+}
+/** Token holding the resolved combobox defaults for the current scope. */
+declare const FOR_COMBOBOX_DEFAULTS: _angular_core.InjectionToken<ForComboboxDefaults>;
+/**
+ * Configures forty-cdk combobox defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForComboboxDefaults(defaults?: Partial<ForComboboxDefaults>): Provider[];
+
+/**
+ * Exact public names of every `ForCombobox` 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[myCombobox]',
+ *   template: '',
+ *   hostDirectives: [
+ *     {
+ *       directive: ForCombobox,
+ *       inputs: [...FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS],
+ *       outputs: [...FOR_COMBOBOX_HOST_DIRECTIVE_OUTPUTS],
+ *     },
+ *   ],
+ * })
+ * export class MyCombobox {}
+ * ```
+ */
+declare const FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS: readonly ["query", "value", "open", "align", "alignOffset", "ariaLabel", "arrowPadding", "autoHighlight", "autocompleteMode", "avoidCollisions", "clearOnQueryChange", "clipUntilPositioned", "collisionPadding", "commitOnSelect", "dir", "dirty", "disabled", "dismissible", "errors", "hideWhenDetached", "invalid", "isItemEqualToValue", "itemToFormValue", "itemToStringLabel", "loop", "multiple", "name", "openOnFocus", "openOnQuery", "pending", "readonly", "required", "returnFocus", "side", "sideOffset", "sticky", "totalCount", "visibleRange", "touched"];
+/**
+ * Exact public names of every `ForCombobox` output, the Signal Forms `touch` output
+ * included. Spread it into the `outputs` array of the same `hostDirectives` entry as
+ * {@link FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS}.
+ */
+declare const FOR_COMBOBOX_HOST_DIRECTIVE_OUTPUTS: readonly ["queryChange", "valueChange", "openChange", "scrollToIndex", "escapeKeyDown", "pointerDownOutside", "focusOutside", "interactOutside", "autoFocusOnOpen", "autoFocusOnClose", "touchedChange", "touch"];
+
+export { FOR_COMBOBOX_CONTEXT, FOR_COMBOBOX_DEFAULTS, FOR_COMBOBOX_HOST_DIRECTIVE_INPUTS, FOR_COMBOBOX_HOST_DIRECTIVE_OUTPUTS, FOR_COMBOBOX_OPTION, ForCombobox, ForComboboxAnchor, ForComboboxChip, ForComboboxChipRemove, ForComboboxChips, ForComboboxClear, ForComboboxContent, ForComboboxEmpty, ForComboboxGroup, ForComboboxGroupLabel, ForComboboxIndicator, ForComboboxInput, ForComboboxList, ForComboboxOption, ForComboboxSeparator, ForComboboxStatus, ForComboboxTrigger, provideForComboboxDefaults };
+export type { ForComboboxAutocomplete, ForComboboxChipHandle, ForComboboxCloseReason, ForComboboxContext, ForComboboxDefaults, ForComboboxInitialFocus, ForComboboxOptionHandle };