@cdevhub/ngx-tw 0.5.0 → 0.6.1

package/fesm2022/cdevhub-ngx-tw-combobox.mjs

@@ -1,11 +1,8 @@
 import * as i0 from '@angular/core';
 import { inject, ElementRef, signal, computed, ChangeDetectionStrategy, Component, TemplateRef, Directive, input, model, output, contentChild, viewChild, ViewContainerRef, Injector, DestroyRef, linkedSignal, effect, untracked, forwardRef } from '@angular/core';
-import { NgControl, NgForm, FormGroupDirective } from '@angular/forms';
-import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { merge } from 'rxjs';
-import { TW_ERROR_STATE_MATCHER, buildSelectLikePositions, resolveSelectScrollStrategy, consumeOverlayEscape } from '@cdevhub/ngx-tw/core';
+import { NgControl } from '@angular/forms';
+import { PickerOverlayCoordinator, wireErrorState, resolveSelectScrollStrategy, buildSelectLikePositions } from '@cdevhub/ngx-tw/core';
 import { Overlay } from '@angular/cdk/overlay';
-import { ComponentPortal } from '@angular/cdk/portal';
 import { Platform } from '@angular/cdk/platform';
 import { FocusMonitor, LiveAnnouncer } from '@angular/cdk/a11y';
 import { tv } from 'tailwind-variants';
@@ -340,8 +337,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         }] });
 
 // ── Constants ──
-/** Duration of leave animation (ms) — matches scale-out/fade-out in theme/_base.css. */
-const ANIMATION_DURATION = 120;
 /** Debounce window (ms) for LiveAnnouncer result announcements while typing. */
 const ANNOUNCE_DEBOUNCE = 200;
 /** Sentinel for an unresolved write-value awaiting late-arriving options. */
@@ -383,20 +378,29 @@ const comboboxVariants = tv({
         // variants below paint this ring per the `color`/`errorState` axis.
         trigger: 'flex w-full items-center gap-1.5 rounded-md border border-border bg-surface text-fg transition-colors duration-normal motion-reduce:transition-none hover:border-border-strong focus-within:outline-2 focus-within:outline-offset-2',
         input: 'flex-1 min-w-0 bg-transparent outline-none placeholder:text-fg-subtle disabled:cursor-not-allowed',
-        clearButton: 'inline-flex items-center justify-center shrink-0 size-5 rounded-md text-fg-muted hover:text-fg hover:bg-surface-muted transition-colors duration-normal motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
+        // `size-6` (24px) is the WCAG 2.2 SC 2.5.8 target-size floor and the `xs`
+        // step of the square-interactive scale. It does NOT scale with `size`:
+        // the clear sits inside the trigger, whose smallest pinned height is
+        // 24px (`xs` -> `h-6`), so any larger step would overflow the smallest
+        // trigger. The floor is what the success criterion asks for — which is
+        // also why `xs` no longer shrinks it to `size-4`.
+        clearButton: 'inline-flex items-center justify-center shrink-0 size-6 rounded-md text-fg-muted hover:text-fg hover:bg-surface-muted transition-colors duration-normal motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
         chevron: 'shrink-0 text-fg-muted transition-transform duration-normal motion-reduce:transition-none',
         spinner: 'shrink-0 text-fg-muted animate-spin',
     },
     variants: {
+        // Trigger height is PINNED (docs/vertical-rhythm.md §1-3): the box is
+        // always one line, so it declares its border-box height and carries no
+        // vertical padding. Horizontal padding and the font size are unchanged.
         size: {
             // xs density: chevron and spinner use `size-3.5` (14px) — the codified
             // half-step between size-3 and size-4 that lines up with text-xs metric
-            // inside a 28px trigger.
-            xs: { trigger: 'px-2 py-1 text-xs', chevron: 'size-3.5', clearButton: 'size-4', spinner: 'size-3.5' },
-            sm: { trigger: 'px-3 py-1.5 text-sm', chevron: 'size-4', spinner: 'size-4' },
-            md: { trigger: 'px-4 py-2 text-sm', chevron: 'size-4', spinner: 'size-4' },
-            lg: { trigger: 'px-5 py-2.5 text-base', chevron: 'size-5', spinner: 'size-5' },
-            xl: { trigger: 'px-6 py-3 text-base', chevron: 'size-5', spinner: 'size-5' },
+            // inside a 24px trigger.
+            xs: { trigger: 'px-2 text-xs h-6', chevron: 'size-3.5', spinner: 'size-3.5' },
+            sm: { trigger: 'px-3 text-sm h-8', chevron: 'size-4', spinner: 'size-4' },
+            md: { trigger: 'px-4 text-sm h-9', chevron: 'size-4', spinner: 'size-4' },
+            lg: { trigger: 'px-5 text-base h-11', chevron: 'size-5', spinner: 'size-5' },
+            xl: { trigger: 'px-6 text-base h-12', chevron: 'size-5', spinner: 'size-5' },
         },
         color: {
             primary: { trigger: 'focus-within:outline-primary-500' },
@@ -416,9 +420,14 @@ const comboboxVariants = tv({
             true: { chevron: 'rotate-180' },
             false: {},
         },
+        // `naked` = wrapped in a `tw-form-field`, which owns the box: its
+        // controlWrapper draws the border and the vertical padding. `h-auto`
+        // releases the pinned height (declared after `size`, so twMerge keeps it
+        // — the same ordering `px-0` already relies on) so the trigger
+        // contributes only its line box and the field's own rhythm governs.
         naked: {
             true: {
-                trigger: 'border-0 bg-transparent rounded-none px-0 py-0 hover:border-0 focus-within:outline-0 focus-within:outline-offset-0',
+                trigger: 'border-0 bg-transparent rounded-none px-0 py-0 h-auto hover:border-0 focus-within:outline-0 focus-within:outline-offset-0',
             },
             false: {},
         },
@@ -513,115 +522,109 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 class ComboboxComponent {
     // ── Inputs ──
-    /** Array of options to render in the popover. Accepts plain records or `TwComboboxOption<T>`. */
+    /** Array of options to render in the popover. Accepts plain records or `TwComboboxOption<T>`. Defaults to an empty array. */
     options = input([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
-    /** Accessor returning the visible label for an option. Used by the default filter and the trigger label resolver. */
+    /** Accessor returning the visible label for an option. Used by the default filter and the trigger label resolver. Defaults to reading `.label`, falling back to `String(.value)`. */
     optionLabel = input(defaultOptionLabel, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "optionLabel" }] : /* istanbul ignore next */ []));
-    /** Accessor returning the value emitted via `valueCommit` when this option is picked. */
+    /** Accessor returning the value emitted via `valueCommit` when this option is picked. Defaults to reading `.value`. */
     optionValue = input(defaultOptionValue, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "optionValue" }] : /* istanbul ignore next */ []));
-    /** Accessor returning whether an option is non-interactive. */
+    /** Accessor returning whether an option is non-interactive. Defaults to reading `.disabled`. */
     optionDisabled = input(defaultOptionDisabled, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "optionDisabled" }] : /* istanbul ignore next */ []));
-    /** Accessor returning a group label. Options sharing a group render under a labelled `role="group"` region. */
+    /** Accessor returning a group label. Options sharing a group render under a labelled `role="group"` region. Defaults to reading `.group`. */
     optionGroup = input(defaultOptionGroup, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "optionGroup" }] : /* istanbul ignore next */ []));
-    /** Accessor returning an optional secondary description rendered under the label in the default option row. */
+    /** Accessor returning an optional secondary description rendered under the label in the default option row. Defaults to reading `.description`. */
     optionDescription = input(defaultOptionDescription, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "optionDescription" }] : /* istanbul ignore next */ []));
     /** Filter function applied client-side whenever `inputValue` changes. Pass `null` to disable client filtering (async mode). Defaults to case-insensitive `startsWith` on the label. */
     filterFn = input(defaultStartsWithFilter, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "filterFn" }] : /* istanbul ignore next */ []));
-    /** When `true`, free-text commits are rejected — the input reverts to the last committed label on blur. */
+    /** When `true`, free-text commits are rejected — the input reverts to the last committed label on blur. Defaults to `false`. */
     strict = input(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "strict" }] : /* istanbul ignore next */ []));
-    /** Placeholder shown when the input is empty. */
+    /** Placeholder shown when the input is empty. Defaults to `undefined`. */
     placeholder = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
-    /** Disables the input and prevents the popover from opening. */
+    /** Disables the input and prevents the popover from opening. Defaults to `false`. Alias: `disabled`. */
     disabledInput = input(false, { ...(ngDevMode ? { debugName: "disabledInput" } : /* istanbul ignore next */ {}), alias: 'disabled' });
-    /** Sets `aria-required="true"` on the input. */
+    /** Sets `aria-required="true"` on the input and the `*` marker on a wrapping `tw-form-field`. Also inferred from `Validators.required` on a bound control, so a reactive/template-driven form does not have to state it twice. Defaults to `false`. */
     requiredInput = input(false, { ...(ngDevMode ? { debugName: "requiredInput" } : /* istanbul ignore next */ {}), alias: 'required' });
-    /** Controls trigger padding and font size per the inline padding scale. */
+    /** Controls trigger padding and font size per the inline padding scale. Defaults to `'md'`. */
     size = input('md', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "size" }] : /* istanbul ignore next */ []));
-    /** Semantic color for the focus ring. */
+    /** Semantic color for the focus ring. Defaults to `'primary'`. */
     color = input('primary', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "color" }] : /* istanbul ignore next */ []));
-    /** Whether the trailing chevron affordance is rendered. */
-    // TRUE-default: the chevron signals the dropdown affordance; without it the
-    // combobox reads as a plain input. Opt-out is for inline search inputs.
+    /** Whether the trailing chevron affordance is rendered. Defaults to `true` — the chevron signals the dropdown affordance; the special case is an inline search input that opts out. */
     showChevron = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showChevron" }] : /* istanbul ignore next */ []));
-    /** Whether the inline clear (×) button appears while `inputValue` is non-empty. */
-    // TRUE-default: the clear affordance is the expected combobox UX once a value
-    // is set; opt-out is for required-only flows.
+    /** Whether the inline clear (×) button appears while `inputValue` is non-empty. Defaults to `true` — clearing a typed value is the expected combobox gesture; the special case is a required-only flow. */
     clearable = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "clearable" }] : /* istanbul ignore next */ []));
-    /** When `true`, shows an in-popover spinner and an inline spinner in the trigger while the popover is open. */
+    /** When `true`, shows an in-popover spinner and an inline spinner in the trigger while the popover is open. Defaults to `false`. */
     loading = input(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "loading" }] : /* istanbul ignore next */ []));
-    /** Debounce window (ms) before `queryChange` emits. Local filtering is not debounced. */
+    /** Debounce window (ms) before `queryChange` emits. Local filtering is not debounced. Defaults to `150`. */
     queryDebounce = input(150, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "queryDebounce" }] : /* istanbul ignore next */ []));
-    /** Minimum query length before the popover opens automatically. `0` opens on focus. */
+    /** Minimum query length before the popover opens automatically. `0` opens on focus. Defaults to `0`. */
     minQueryLength = input(0, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "minQueryLength" }] : /* istanbul ignore next */ []));
-    /** Whether the popover opens automatically when the input receives focus. */
-    // TRUE-default: clicking into a combobox opens the dropdown — standard select-
-    // like UX. Opt-out is for command-palette-style flows triggered only by typing.
+    /** Whether the popover opens automatically when the input receives focus. Defaults to `true` — clicking into a combobox opens the dropdown, matching select-like UX; the special case is a flow that should open only once the user types. */
     openOnFocus = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "openOnFocus" }] : /* istanbul ignore next */ []));
-    /** Maximum height (px) of the popover scroll region. */
+    /** Maximum height (px) of the popover scroll region. Defaults to `256`. */
     panelMaxHeight = input(256, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "panelMaxHeight" }] : /* istanbul ignore next */ []));
-    /** Overlay width strategy. `'trigger'` matches input width; `'auto'` lets content decide; a number is applied as px; a string is passed as a CSS length. */
+    /** Overlay width strategy. `'trigger'` matches input width; `'auto'` lets content decide; a number is applied as px; a string is passed as a CSS length. Defaults to `'trigger'`. */
     panelWidth = input('trigger', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "panelWidth" }] : /* istanbul ignore next */ []));
-    /** Extra class(es) appended to the overlay panel for consumer customization. */
+    /** Extra class(es) appended to the overlay panel for consumer customization. Defaults to an empty string. */
     panelClass = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "panelClass" }] : /* istanbul ignore next */ []));
-    /** CDK overlay scroll strategy. */
+    /** CDK overlay scroll strategy. Defaults to `'reposition'`. */
     scrollStrategy = input('reposition', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "scrollStrategy" }] : /* istanbul ignore next */ []));
-    /** Pixel offset between the input and the popover. */
+    /** Pixel offset between the input and the popover. Defaults to `4`. */
     offset = input(4, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "offset" }] : /* istanbul ignore next */ []));
-    /** Fallback empty-state message when no `*twComboboxEmpty` template is projected. */
+    /** Fallback empty-state message when no `*twComboboxEmpty` template is projected. Defaults to `'No results'`. */
     emptyMessage = input('No results', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "emptyMessage" }] : /* istanbul ignore next */ []));
-    /** Equality comparator used to reconcile `value` with options during `writeValue`. */
+    /** Equality comparator used to reconcile `value` with options during `writeValue`. Defaults to `Object.is`. */
     compareWith = input(Object.is, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "compareWith" }] : /* istanbul ignore next */ []));
-    /** Accessible name for the combobox input. */
+    /** Accessible name for the combobox input. Defaults to `undefined`. Alias: `aria-label`. */
     ariaLabel = input(undefined, { ...(ngDevMode ? { debugName: "ariaLabel" } : /* istanbul ignore next */ {}), alias: 'aria-label' });
-    /** ID of an external label element. */
+    /** ID of an external label element. Defaults to `undefined`. Alias: `aria-labelledby`. */
     ariaLabelledby = input(undefined, { ...(ngDevMode ? { debugName: "ariaLabelledby" } : /* istanbul ignore next */ {}), alias: 'aria-labelledby' });
-    /** ID of an external descriptor element. */
+    /** ID of an external descriptor element. Defaults to `undefined`. Alias: `aria-describedby`. */
     ariaDescribedby = input(undefined, { ...(ngDevMode ? { debugName: "ariaDescribedby" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the combobox uses the `TW_ERROR_STATE_MATCHER` token's value. */
     errorStateMatcher = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "errorStateMatcher" }] : /* istanbul ignore next */ []));
     // ── Models ──
-    /** Two-way bound committed value. May be an option's value (`T`), a typed string (free-text mode), or `null`. */
+    /** Two-way bound committed value. May be an option's value (`T`), a typed string (free-text mode), or `null`. Defaults to `null`. */
     value = model(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
-    /** Two-way bound visible text in the input. Bound separately from `value` so async consumers can drive the query. */
+    /** Two-way bound visible text in the input. Bound separately from `value` so async consumers can drive the query. Writes back on every keystroke, on commit, and on clear. Defaults to `''`. */
     inputValue = model('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "inputValue" }] : /* istanbul ignore next */ []));
-    /** Two-way bound open state of the popover. */
+    /** Two-way bound open state of the popover. Defaults to `false`. */
     open = model(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "open" }] : /* istanbul ignore next */ []));
     // ── Outputs ──
-    /** Fires after the query text changes, debounced by `queryDebounce`. Async-mode consumers subscribe to this to fetch results. */
+    /** Fires after the query text changes, debounced by `queryDebounce`. Async-mode consumers subscribe to this to fetch results. Payload is the current input text, untrimmed. */
     queryChange = output();
-    /** Fires when the user picks an option from the list (not on free-text commit). */
+    /** Fires when the user picks an option from the list (not on free-text commit). Payload carries the raw option record plus its resolved `value` and `label`. */
     optionSelected = output();
     /** Fires whenever `value` changes, with a `source` discriminator distinguishing option / free-text / reset / programmatic origin. */
     valueCommit = output();
-    /** Fires when the popover opens or closes. */
+    /** Fires when the popover finishes opening or closing. Payload carries the new `open` state and the trigger element the overlay is anchored to. */
     openedChange = output();
     // ── Content queries ──
     /** @internal */
@@ -640,6 +643,7 @@ class ComboboxComponent {
     ...(ngDevMode ? [{ debugName: "triggerSurfaceRef" }] : /* istanbul ignore next */ []));
     // ── Injected deps ──
     overlayService = inject(Overlay);
+    coordinator = inject(PickerOverlayCoordinator);
     elementRef = inject((ElementRef));
     viewContainerRef = inject(ViewContainerRef);
     injector = inject(Injector);
@@ -649,9 +653,6 @@ class ComboboxComponent {
     platform = inject(Platform);
     formField = inject(TW_FORM_FIELD, { optional: true });
     ngControl = inject(NgControl, { optional: true, self: true });
-    parentForm = inject(NgForm, { optional: true });
-    parentFormGroup = inject(FormGroupDirective, { optional: true });
-    defaultMatcher = inject(TW_ERROR_STATE_MATCHER);
     // ── Identity ──
     uid = nextComboboxId++;
     /** @internal */
@@ -671,10 +672,12 @@ class ComboboxComponent {
     ...(ngDevMode ? [{ debugName: "focusedSignal" }] : /* istanbul ignore next */ []));
     cvaDisabled = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "cvaDisabled" }] : /* istanbul ignore next */ []));
-    _ngControlRev = signal(0, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "_ngControlRev" }] : /* istanbul ignore next */ []));
-    _formSubmitRev = signal(0, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "_formSubmitRev" }] : /* istanbul ignore next */ []));
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    errorWiring = wireErrorState({
+        ngControl: () => this.ngControl,
+        matcher: () => this.errorStateMatcher(),
+        required: () => this.requiredInput(),
+    });
     describedByIdsSignal = signal([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "describedByIdsSignal" }] : /* istanbul ignore next */ []));
     labelledByIdsSignal = signal([], /* @ts-ignore */
@@ -684,22 +687,34 @@ class ComboboxComponent {
     ...(ngDevMode ? [{ debugName: "lastCommittedLabel" }] : /* istanbul ignore next */ []));
     pendingWriteValue = signal(UNRESOLVED, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "pendingWriteValue" }] : /* istanbul ignore next */ []));
-    closingSignal = signal(false, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "closingSignal" }] : /* istanbul ignore next */ []));
     /** Re-runs the input handler once after IME composition ends. */
     composingPendingValue = null;
     onChange = () => { };
     onTouched = () => { };
-    overlayRef = null;
-    overlayInstanceSignal = signal(null, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "overlayInstanceSignal" }] : /* istanbul ignore next */ []));
-    closeTimer = null;
     queryDebounceTimer = null;
     announceTimer = null;
+    /**
+     * Watches the host for size changes so `panelWidth="trigger"` keeps tracking
+     * while the panel is up. Minted per open and disconnected on close, because
+     * the `OverlayRef` it feeds is disposed on close (see `openOverlay`).
+     */
     resizeObserver = null;
-    get overlayInstance() {
-        return this.overlayInstanceSignal();
-    }
+    // Overlay bookkeeping is deliberately held in plain fields, not signals — same
+    // shape as popover and command-palette. A signal here would be track-read by the
+    // open/close lifecycle effect that also writes it, which is the cycle shape
+    // CLAUDE.md forbids. The only reactive bit is `isAttached`, written by the
+    // lifecycle effect and read only by the state-push effect below, so the two
+    // never form a loop.
+    overlayInstance = null;
+    closing = false;
+    /**
+     * Flips true once the overlay component is attached; the sole trigger for the
+     * state-push effect. Load-bearing: the close path leaves `activeIndex` and the
+     * rest of the pushed state untouched, so on a reopen no data signal changes and
+     * nothing else would wake that effect — the fresh panel would render empty.
+     */
+    isAttached = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isAttached" }] : /* istanbul ignore next */ []));
     // ── Derived state ──
     /** @internal */
     isDisabled = computed(() => this.disabledInput() || this.cvaDisabled(), /* @ts-ignore */
@@ -817,15 +832,7 @@ class ComboboxComponent {
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "resolvedLabelledBy" }] : /* istanbul ignore next */ []));
     /** @internal Error-state per the configured `ErrorStateMatcher`. Reads the bound `NgControl.invalid` through the matcher. */
-    errorState = computed(() => {
-        this._ngControlRev();
-        this._formSubmitRev();
-        const matcher = this.errorStateMatcher() ?? this.defaultMatcher;
-        const form = this.parentFormGroup ??
-            this.parentForm;
-        return matcher.isErrorState(this.ngControl?.control ?? null, form);
-    }, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "errorState" }] : /* istanbul ignore next */ []));
+    errorState = this.errorWiring.errorState;
     // ── tv() output ──
     variantResult = computed(() => comboboxVariants({
         size: this.size(),
@@ -864,9 +871,18 @@ class ComboboxComponent {
     empty = this.isEmpty;
     /** @internal */
     disabled = this.isDisabled;
-    /** @internal */
-    required = computed(() => this.requiredInput(), /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "required" }] : /* istanbul ignore next */ []));
+    /**
+     * @internal Resolved required state: the `required` input OR'd with
+     * `Validators.required` on a bound `NgControl`. Without the validator arm the
+     * form-field `*` marker (`FormFieldComponent.isRequired`) and the input's
+     * `aria-required` silently vanish under reactive/template-driven forms, while
+     * signal forms shows them — `cvaControlCreate` writes the `required` *input*
+     * directly from the field state and never consults validators. The OR keeps
+     * both branches true at once.
+     */
+    required = this.errorWiring.required;
+    /** @internal Active validation errors map from the bound `NgControl`. Drives `[twError match="…"]` inside a wrapping `tw-form-field`; without it the form-field's key set is permanently empty and every `match`ed error stays hidden. */
+    errors = this.errorWiring.errors;
     /** @internal */
     controlType = 'combobox';
     /** @internal */
@@ -885,30 +901,33 @@ class ComboboxComponent {
             this.ngControl.valueAccessor = this;
         }
         // Mirror parent `open` model into overlay lifecycle.
+        // Only `open` and `isDisabled` are read in the tracked phase; the lifecycle
+        // calls run inside `untracked()` because they both read and write panel state
+        // (openOverlay writes activeIndex and reads visibleOptions).
         effect(() => {
             const shouldOpen = this.open();
             const disabled = this.isDisabled();
-            if (disabled && this.overlayInstance) {
-                this.closeOverlay({ silent: false });
-                return;
-            }
-            if (shouldOpen && !this.overlayInstance && !disabled && !this.closingSignal()) {
-                this.openOverlay();
-            }
-            else if (!shouldOpen && this.overlayInstance && !this.closingSignal()) {
-                this.closeOverlay({ silent: false });
-            }
+            untracked(() => {
+                if (disabled && this.overlayInstance) {
+                    this.closeOverlay({ silent: false });
+                    return;
+                }
+                if (shouldOpen && !this.overlayInstance && !disabled && !this.closing) {
+                    this.openOverlay();
+                }
+                else if (!shouldOpen && this.overlayInstance && !this.closing) {
+                    this.closeOverlay({ silent: false });
+                }
+            });
         });
         // Push state into overlay component whenever anything relevant changes.
+        // `isAttached` is the trigger — it is written by the lifecycle effect above
+        // and never written here, so the two effects cannot feed each other.
         // While the panel is animating out, freeze content updates so list mutations
         // (e.g. the input filtering down after commitOption) don't visually flicker
         // the panel during the leave animation.
         effect(() => {
-            const instance = this.overlayInstance;
-            if (!instance)
-                return;
-            if (this.closingSignal())
-                return;
+            const attached = this.isAttached();
             const renderedRows = this.renderedRows();
             const activeIndex = this.activeIndex();
             const panelMaxHeight = this.panelMaxHeight();
@@ -920,7 +939,14 @@ class ComboboxComponent {
             const emptyTemplate = this.emptyTemplateChild()?.templateRef;
             const loadingTemplate = this.loadingTemplateChild()?.templateRef;
             const customPanelClass = this.resolvePanelClass();
+            // Tracked so the selection snapshot below refreshes when either changes.
+            // The snapshot replaced a live closure — see the `isSelected` push.
+            const visibleCount = this.visibleOptions().length;
+            void this.value();
             untracked(() => {
+                const instance = this.overlayInstance;
+                if (!attached || !instance || this.closing)
+                    return;
                 instance.renderedRows.set(renderedRows);
                 instance.activeIndex.set(activeIndex);
                 instance.panelMaxHeight.set(panelMaxHeight);
@@ -935,7 +961,19 @@ class ComboboxComponent {
                 instance.listboxId.set(this.listboxId);
                 instance.optionIdFn.set(this.optionId);
                 instance.groupHeaderIdFn.set(this.groupHeaderId);
-                instance.isSelected.set((index) => this.isVisibleOptionSelected(index));
+                // A SNAPSHOT, not a live closure. `renderedRows` is frozen while the
+                // panel animates out (the guard above), and each frozen row carries its
+                // index into the visible list at freeze time. A closure reading
+                // `visibleOptions()` at call time would resolve those stale indices
+                // against the current, already-refiltered list — so committing an option
+                // marked the WRONG row `aria-selected="true"` for the ~120ms leave
+                // window. Snapshotting here binds the flags to the same generation of
+                // the list as the rows they describe.
+                const selectedFlags = new Array(visibleCount);
+                for (let i = 0; i < visibleCount; i++) {
+                    selectedFlags[i] = this.isVisibleOptionSelected(i);
+                }
+                instance.isSelected.set((index) => selectedFlags[index] ?? false);
             });
         });
         // Late-arriving options reconciler for the async writeValue race.
@@ -996,20 +1034,21 @@ class ComboboxComponent {
                 this.onTouched();
                 // Blur often flips `touched` on the bound `NgControl`; bump the
                 // revision so `errorState` recomputes.
-                this._ngControlRev.update((n) => n + 1);
+                this.errorWiring.bump();
             }
         });
+        // The overlay itself is torn down by `PickerOverlayCoordinator`, which
+        // registers its own `DestroyRef.onDestroy` during this component's field
+        // initialisation — i.e. before this hook — and disposes the `OverlayRef`,
+        // cancels the close timer and completes the per-open streams there.
         this.destroyRef.onDestroy(() => {
             monitorSub.unsubscribe();
             this.focusMonitor.stopMonitoring(this.elementRef);
-            this.clearCloseTimer();
             this.clearQueryDebounceTimer();
             this.clearAnnounceTimer();
             this.resizeObserver?.disconnect();
             this.resizeObserver = null;
-            this.overlayRef?.dispose();
-            this.overlayRef = null;
-            this.overlayInstanceSignal.set(null);
+            this.overlayInstance = null;
         });
     }
     // ── Public methods ──
@@ -1208,7 +1247,15 @@ class ComboboxComponent {
         event.preventDefault();
         event.stopPropagation();
     }
-    /** @internal */
+    /**
+     * @internal
+     *
+     * Reached by mouse and — since the button left `tabindex="-1"` — by Enter or
+     * Space from the keyboard, both of which a native `<button>` delivers here
+     * as a click. Clearing unmounts this button (`showClearButton()` goes
+     * false), so focus is handed back to the input rather than falling to
+     * `<body>` (SC 2.4.3).
+     */
     onClearClick(event) {
         event.preventDefault();
         event.stopPropagation();
@@ -1376,13 +1423,60 @@ class ComboboxComponent {
         }
     }
     // ── Overlay lifecycle ──
+    /**
+     * Builds and attaches the panel through {@link PickerOverlayCoordinator}.
+     *
+     * The coordinator disposes the `OverlayRef` on close, so every value read
+     * here — `offset`, `scrollStrategy`, `panelClass`, and the position
+     * strategy's origin — is re-read on each open rather than frozen at the
+     * first one. That replaces the previous `refreshPositionConfig()` /
+     * `applyScrollStrategy()` pair, which could only refresh the two inputs it
+     * knew about on a reused ref.
+     *
+     * `focusTrap: false` is load-bearing: this is an `aria-activedescendant`
+     * combobox, so DOM focus never leaves the `<input>` and a trap's anchor
+     * elements would inject tab stops around a panel with nothing focusable in it.
+     */
     openOverlay() {
-        this.ensureOverlay();
-        this.attachOverlayComponent();
-        this.subscribeBackdrop();
-        this.subscribeOverlayEscape();
+        const result = this.coordinator.open({
+            origin: this.triggerSurfaceRef() ?? this.elementRef,
+            portalComponent: ComboboxOverlayComponent,
+            viewContainerRef: this.viewContainerRef,
+            injector: this.injector,
+            positions: buildSelectLikePositions(this.offset()),
+            scrollStrategy: resolveSelectScrollStrategy(this.scrollStrategy(), this.overlayService),
+            panelClass: 'tw-combobox-panel',
+            focusTrap: false,
+        });
+        if (!result)
+            return;
+        const instance = result.instance;
+        instance.onOptionPick.set((index) => {
+            const visible = this.visibleOptions();
+            if (index < 0 || index >= visible.length)
+                return;
+            const opt = visible[index];
+            if (opt.disabled)
+                return;
+            this.commitOption(opt, 'option');
+        });
+        instance.onOptionHover.set((index) => {
+            const visible = this.visibleOptions();
+            if (index < 0 || index >= visible.length)
+                return;
+            if (visible[index].disabled)
+                return;
+            this.activeIndex.set(index);
+        });
+        this.overlayInstance = instance;
+        this.installResizeObserver();
+        this.updateOverlaySize();
+        this.subscribePerOpen();
         // Reset active to first enabled when opening.
         this.activeIndex.set(this.firstEnabledIndex());
+        // Set last: this is what wakes the state-push effect, and it must not fire
+        // until the instance exists and the per-open state has been reset.
+        this.isAttached.set(true);
         this.liveAnnouncer.announce(`${this.visibleOptions().length} suggestions available`, 'polite');
         this.openedChange.emit({
             open: true,
@@ -1390,47 +1484,29 @@ class ComboboxComponent {
         });
     }
     closeOverlay(_opts) {
-        if (this.closingSignal() || !this.overlayInstance)
+        if (this.closing || !this.overlayInstance)
             return;
-        this.closingSignal.set(true);
+        this.closing = true;
         this.clearAnnounceTimer();
-        this.closeTimer = setTimeout(() => {
-            this.closeTimer = null;
-            if (this.overlayRef?.hasAttached()) {
-                this.overlayRef.detach();
-            }
-            this.overlayInstanceSignal.set(null);
+        // The coordinator runs the leave animation, then detaches and disposes;
+        // this callback fires once the overlay is fully gone.
+        this.coordinator.close(() => {
+            // Safe to drop the observer: the next open mints a fresh one against the
+            // fresh OverlayRef. This used to be the SRP F-01 bug — the observer was
+            // disconnected here while the reused ref made `ensureOverlay()`
+            // early-return, so it was never re-installed. Under dispose-on-close the
+            // install is unconditional, so that shape cannot come back.
             this.resizeObserver?.disconnect();
             this.resizeObserver = null;
+            this.overlayInstance = null;
+            this.isAttached.set(false);
             untracked(() => this.open.set(false));
-            this.closingSignal.set(false);
+            this.closing = false;
             this.openedChange.emit({
                 open: false,
                 trigger: this.inputRef()?.nativeElement ?? this.elementRef.nativeElement,
             });
-        }, ANIMATION_DURATION);
-    }
-    ensureOverlay() {
-        if (this.overlayRef) {
-            this.updateOverlaySize();
-            return;
-        }
-        const positionStrategy = this.overlayService
-            .position()
-            .flexibleConnectedTo(this.triggerSurfaceRef()?.nativeElement ?? this.elementRef.nativeElement)
-            .withPositions(buildSelectLikePositions(this.offset()))
-            .withFlexibleDimensions(false)
-            .withPush(false)
-            .withViewportMargin(8);
-        this.overlayRef = this.overlayService.create({
-            positionStrategy,
-            scrollStrategy: resolveSelectScrollStrategy(this.scrollStrategy(), this.overlayService),
-            hasBackdrop: true,
-            backdropClass: 'cdk-overlay-transparent-backdrop',
-            panelClass: 'tw-combobox-panel',
         });
-        this.installResizeObserver();
-        this.updateOverlaySize();
     }
     installResizeObserver() {
         if (!this.platform.isBrowser || typeof ResizeObserver === 'undefined')
@@ -1441,85 +1517,48 @@ class ComboboxComponent {
         this.resizeObserver.observe(target);
     }
     updateOverlaySize() {
-        if (!this.overlayRef)
+        const overlayRef = this.coordinator.ref();
+        if (!overlayRef)
             return;
         const width = this.panelWidth();
         if (width === 'trigger') {
             const anchor = this.triggerSurfaceRef()?.nativeElement ?? this.elementRef.nativeElement;
             const rect = anchor.getBoundingClientRect();
-            this.overlayRef.updateSize({ width: rect.width });
+            overlayRef.updateSize({ width: rect.width });
         }
         else if (width === 'auto') {
-            this.overlayRef.updateSize({ width: undefined, minWidth: undefined });
-        }
-        else if (typeof width === 'number') {
-            this.overlayRef.updateSize({ width });
+            overlayRef.updateSize({ width: undefined, minWidth: undefined });
         }
         else {
-            this.overlayRef.updateSize({ width });
+            overlayRef.updateSize({ width });
         }
     }
-    attachOverlayComponent() {
-        if (!this.overlayRef)
-            return;
-        const portal = new ComponentPortal(ComboboxOverlayComponent, this.viewContainerRef, this.injector);
-        const ref = this.overlayRef.attach(portal);
-        const instance = ref.instance;
-        instance.onOptionPick.set((index) => {
-            const visible = this.visibleOptions();
-            if (index < 0 || index >= visible.length)
-                return;
-            const opt = visible[index];
-            if (opt.disabled)
-                return;
-            this.commitOption(opt, 'option');
-        });
-        instance.onOptionHover.set((index) => {
-            const visible = this.visibleOptions();
-            if (index < 0 || index >= visible.length)
-                return;
-            if (visible[index].disabled)
-                return;
-            this.activeIndex.set(index);
-        });
-        this.overlayInstanceSignal.set(instance);
-    }
-    subscribeBackdrop() {
-        if (!this.overlayRef)
-            return;
-        const sub = this.overlayRef.backdropClick().subscribe(() => {
-            this.closePanel();
-        });
-        this.destroyRef.onDestroy(() => sub.unsubscribe());
-    }
     /**
-     * Listens for `Escape` on the overlay's `keydownEvents()`. Mirrors
+     * Registers the backdrop-click and Escape listeners for one open.
+     *
+     * The Escape listener rides the overlay's `keydownEvents()`. Mirrors
      * `SelectComponent` so focus inside the overlay panel (e.g., if the user
      * tabs into projected loading/empty templates) still dismisses cleanly.
      * The combobox's own `<input>` keydown handler already short-circuits
      * Escape when focus is on the input; this layer is the safety net for
      * panel-internal focus.
+     *
+     * Both streams come from the coordinator, which completes them when the
+     * overlay closes — so there is no per-open `Subscription` aggregate to keep
+     * and no way for listeners to accumulate across opens.
      */
-    subscribeOverlayEscape() {
-        if (!this.overlayRef)
-            return;
-        const teardown = consumeOverlayEscape(this.overlayRef, (event) => {
+    subscribePerOpen() {
+        this.coordinator.backdropClick$().subscribe(() => this.closePanel());
+        this.coordinator.escape$().subscribe((event) => {
             event.preventDefault();
             this.inputValue.set(this.lastCommittedLabel());
             this.closePanel();
         });
-        this.destroyRef.onDestroy(() => teardown());
     }
     resolvePanelClass() {
         const raw = this.panelClass();
         return Array.isArray(raw) ? raw.join(' ') : raw;
     }
-    clearCloseTimer() {
-        if (this.closeTimer !== null) {
-            clearTimeout(this.closeTimer);
-            this.closeTimer = null;
-        }
-    }
     // ── ControlValueAccessor ──
     writeValue(value) {
         if (value === null || value === undefined) {
@@ -1588,21 +1627,7 @@ class ComboboxComponent {
         // NgControl's `control` is set by the parent FormControl* directive before
         // children's `ngOnInit`. Subscribe here so errorState reacts to status/value
         // changes on the bound control.
-        const ctrl = this.ngControl?.control;
-        if (ctrl) {
-            const streams = [ctrl.statusChanges, ctrl.valueChanges].filter((s) => !!s);
-            if (streams.length) {
-                merge(...streams)
-                    .pipe(takeUntilDestroyed(this.destroyRef))
-                    .subscribe(() => this._ngControlRev.update((n) => n + 1));
-            }
-        }
-        const submit = this.parentFormGroup?.ngSubmit ?? this.parentForm?.ngSubmit;
-        if (submit) {
-            submit
-                .pipe(takeUntilDestroyed(this.destroyRef))
-                .subscribe(() => this._formSubmitRev.update((n) => n + 1));
-        }
+        this.errorWiring.connect();
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: ComboboxComponent, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.7", type: ComboboxComponent, isStandalone: true, selector: "tw-combobox", inputs: { options: { classPropertyName: "options", publicName: "options", isSignal: true, isRequired: false, transformFunction: null }, optionLabel: { classPropertyName: "optionLabel", publicName: "optionLabel", isSignal: true, isRequired: false, transformFunction: null }, optionValue: { classPropertyName: "optionValue", publicName: "optionValue", isSignal: true, isRequired: false, transformFunction: null }, optionDisabled: { classPropertyName: "optionDisabled", publicName: "optionDisabled", isSignal: true, isRequired: false, transformFunction: null }, optionGroup: { classPropertyName: "optionGroup", publicName: "optionGroup", isSignal: true, isRequired: false, transformFunction: null }, optionDescription: { classPropertyName: "optionDescription", publicName: "optionDescription", isSignal: true, isRequired: false, transformFunction: null }, filterFn: { classPropertyName: "filterFn", publicName: "filterFn", isSignal: true, isRequired: false, transformFunction: null }, strict: { classPropertyName: "strict", publicName: "strict", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, disabledInput: { classPropertyName: "disabledInput", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, requiredInput: { classPropertyName: "requiredInput", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, color: { classPropertyName: "color", publicName: "color", isSignal: true, isRequired: false, transformFunction: null }, showChevron: { classPropertyName: "showChevron", publicName: "showChevron", isSignal: true, isRequired: false, transformFunction: null }, clearable: { classPropertyName: "clearable", publicName: "clearable", isSignal: true, isRequired: false, transformFunction: null }, loading: { classPropertyName: "loading", publicName: "loading", isSignal: true, isRequired: false, transformFunction: null }, queryDebounce: { classPropertyName: "queryDebounce", publicName: "queryDebounce", isSignal: true, isRequired: false, transformFunction: null }, minQueryLength: { classPropertyName: "minQueryLength", publicName: "minQueryLength", isSignal: true, isRequired: false, transformFunction: null }, openOnFocus: { classPropertyName: "openOnFocus", publicName: "openOnFocus", isSignal: true, isRequired: false, transformFunction: null }, panelMaxHeight: { classPropertyName: "panelMaxHeight", publicName: "panelMaxHeight", isSignal: true, isRequired: false, transformFunction: null }, panelWidth: { classPropertyName: "panelWidth", publicName: "panelWidth", isSignal: true, isRequired: false, transformFunction: null }, panelClass: { classPropertyName: "panelClass", publicName: "panelClass", isSignal: true, isRequired: false, transformFunction: null }, scrollStrategy: { classPropertyName: "scrollStrategy", publicName: "scrollStrategy", isSignal: true, isRequired: false, transformFunction: null }, offset: { classPropertyName: "offset", publicName: "offset", isSignal: true, isRequired: false, transformFunction: null }, emptyMessage: { classPropertyName: "emptyMessage", publicName: "emptyMessage", isSignal: true, isRequired: false, transformFunction: null }, compareWith: { classPropertyName: "compareWith", publicName: "compareWith", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "aria-label", isSignal: true, isRequired: false, transformFunction: null }, ariaLabelledby: { classPropertyName: "ariaLabelledby", publicName: "aria-labelledby", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, errorStateMatcher: { classPropertyName: "errorStateMatcher", publicName: "errorStateMatcher", isSignal: true, isRequired: false, transformFunction: null }, value: { classPropertyName: "value", publicName: "value", isSignal: true, isRequired: false, transformFunction: null }, inputValue: { classPropertyName: "inputValue", publicName: "inputValue", isSignal: true, isRequired: false, transformFunction: null }, open: { classPropertyName: "open", publicName: "open", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { value: "valueChange", inputValue: "inputValueChange", open: "openChange", queryChange: "queryChange", optionSelected: "optionSelected", valueCommit: "valueCommit", openedChange: "openedChange" }, host: { properties: { "class": "rootClasses()" } }, providers: [
@@ -1610,6 +1635,7 @@ class ComboboxComponent {
                 provide: TW_FORM_FIELD_CONTROL,
                 useExisting: forwardRef(() => ComboboxComponent),
             },
+            PickerOverlayCoordinator,
         ], queries: [{ propertyName: "optionTemplateChild", first: true, predicate: ComboboxOptionTemplateDirective, descendants: true, isSignal: true }, { propertyName: "emptyTemplateChild", first: true, predicate: ComboboxEmptyTemplateDirective, descendants: true, isSignal: true }, { propertyName: "loadingTemplateChild", first: true, predicate: ComboboxLoadingTemplateDirective, descendants: true, isSignal: true }], viewQueries: [{ propertyName: "inputRef", first: true, predicate: ["inputEl"], descendants: true, isSignal: true }, { propertyName: "triggerSurfaceRef", first: true, predicate: ["triggerSurface"], descendants: true, isSignal: true }], ngImport: i0, template: `
     <div #triggerSurface [class]="triggerClasses()">
       <ng-content select="[twComboboxPrefix]" />
@@ -1625,7 +1651,7 @@ class ComboboxComponent {
         [attr.aria-expanded]="open() ? 'true' : 'false'"
         [attr.aria-controls]="open() ? listboxId : null"
         [attr.aria-activedescendant]="open() ? (activeOptionId() || null) : null"
-        [attr.aria-required]="requiredInput() ? 'true' : null"
+        [attr.aria-required]="required() ? 'true' : null"
         [attr.aria-invalid]="errorState() ? 'true' : null"
         [attr.aria-label]="ariaLabel() || null"
         [attr.aria-labelledby]="resolvedLabelledBy() || null"
@@ -1664,7 +1690,6 @@ class ComboboxComponent {
       @if (showClearButton()) {
         <button
           type="button"
-          tabindex="-1"
           [class]="clearButtonClasses()"
           aria-label="Clear"
           (mousedown)="onClearMousedown($event)"
@@ -1711,6 +1736,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                             provide: TW_FORM_FIELD_CONTROL,
                             useExisting: forwardRef(() => ComboboxComponent),
                         },
+                        PickerOverlayCoordinator,
                     ],
                     template: `
     <div #triggerSurface [class]="triggerClasses()">
@@ -1727,7 +1753,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         [attr.aria-expanded]="open() ? 'true' : 'false'"
         [attr.aria-controls]="open() ? listboxId : null"
         [attr.aria-activedescendant]="open() ? (activeOptionId() || null) : null"
-        [attr.aria-required]="requiredInput() ? 'true' : null"
+        [attr.aria-required]="required() ? 'true' : null"
         [attr.aria-invalid]="errorState() ? 'true' : null"
         [attr.aria-label]="ariaLabel() || null"
         [attr.aria-labelledby]="resolvedLabelledBy() || null"
@@ -1766,7 +1792,6 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
       @if (showClearButton()) {
         <button
           type="button"
-          tabindex="-1"
           [class]="clearButtonClasses()"
           aria-label="Clear"
           (mousedown)="onClearMousedown($event)"