@cdevhub/ngx-tw 0.5.0 → 0.6.1

package/types/cdevhub-ngx-tw-combobox.d.ts

@@ -128,79 +128,79 @@ declare class ComboboxSuffixDirective {
  * `tw-form-field`.
  */
 declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, FormFieldControl<T | string | null>, OnInit {
-    /** 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. */
     readonly options: _angular_core.InputSignal<readonly unknown[]>;
-    /** 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)`. */
     readonly optionLabel: _angular_core.InputSignal<(option: unknown) => string>;
-    /** 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`. */
     readonly optionValue: _angular_core.InputSignal<(option: unknown) => T>;
-    /** Accessor returning whether an option is non-interactive. */
+    /** Accessor returning whether an option is non-interactive. Defaults to reading `.disabled`. */
     readonly optionDisabled: _angular_core.InputSignal<(option: unknown) => boolean>;
-    /** 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`. */
     readonly optionGroup: _angular_core.InputSignal<(option: unknown) => string | undefined>;
-    /** 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`. */
     readonly optionDescription: _angular_core.InputSignal<(option: unknown) => string | undefined>;
     /** Filter function applied client-side whenever `inputValue` changes. Pass `null` to disable client filtering (async mode). Defaults to case-insensitive `startsWith` on the label. */
-    readonly filterFn: _angular_core.InputSignal<((option: unknown, query: string) => boolean) | null>;
-    /** When `true`, free-text commits are rejected — the input reverts to the last committed label on blur. */
+    readonly filterFn: _angular_core.InputSignal<TwComboboxFilterFn | null>;
+    /** When `true`, free-text commits are rejected — the input reverts to the last committed label on blur. Defaults to `false`. */
     readonly strict: _angular_core.InputSignal<boolean>;
-    /** Placeholder shown when the input is empty. */
+    /** Placeholder shown when the input is empty. Defaults to `undefined`. */
     readonly placeholder: _angular_core.InputSignal<string | undefined>;
-    /** Disables the input and prevents the popover from opening. */
+    /** Disables the input and prevents the popover from opening. Defaults to `false`. Alias: `disabled`. */
     readonly disabledInput: _angular_core.InputSignal<boolean>;
-    /** 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`. */
     readonly requiredInput: _angular_core.InputSignal<boolean>;
-    /** 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'`. */
     readonly size: _angular_core.InputSignal<TwSize>;
-    /** Semantic color for the focus ring. */
+    /** Semantic color for the focus ring. Defaults to `'primary'`. */
     readonly color: _angular_core.InputSignal<TwColor>;
-    /** Whether the trailing chevron affordance is rendered. */
+    /** 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. */
     readonly showChevron: _angular_core.InputSignal<boolean>;
-    /** Whether the inline clear (×) button appears while `inputValue` is non-empty. */
+    /** 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. */
     readonly clearable: _angular_core.InputSignal<boolean>;
-    /** 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`. */
     readonly loading: _angular_core.InputSignal<boolean>;
-    /** 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`. */
     readonly queryDebounce: _angular_core.InputSignal<number>;
-    /** 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`. */
     readonly minQueryLength: _angular_core.InputSignal<number>;
-    /** Whether the popover opens automatically when the input receives focus. */
+    /** 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. */
     readonly openOnFocus: _angular_core.InputSignal<boolean>;
-    /** Maximum height (px) of the popover scroll region. */
+    /** Maximum height (px) of the popover scroll region. Defaults to `256`. */
     readonly panelMaxHeight: _angular_core.InputSignal<number>;
-    /** 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'`. */
     readonly panelWidth: _angular_core.InputSignal<string | number>;
-    /** 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. */
     readonly panelClass: _angular_core.InputSignal<string | readonly string[]>;
-    /** CDK overlay scroll strategy. */
+    /** CDK overlay scroll strategy. Defaults to `'reposition'`. */
     readonly scrollStrategy: _angular_core.InputSignal<"reposition" | "close" | "block">;
-    /** Pixel offset between the input and the popover. */
+    /** Pixel offset between the input and the popover. Defaults to `4`. */
     readonly offset: _angular_core.InputSignal<number>;
-    /** Fallback empty-state message when no `*twComboboxEmpty` template is projected. */
+    /** Fallback empty-state message when no `*twComboboxEmpty` template is projected. Defaults to `'No results'`. */
     readonly emptyMessage: _angular_core.InputSignal<string>;
-    /** Equality comparator used to reconcile `value` with options during `writeValue`. */
+    /** Equality comparator used to reconcile `value` with options during `writeValue`. Defaults to `Object.is`. */
     readonly compareWith: _angular_core.InputSignal<(a: T, b: T) => boolean>;
-    /** Accessible name for the combobox input. */
+    /** Accessible name for the combobox input. Defaults to `undefined`. Alias: `aria-label`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external label element. */
+    /** ID of an external label element. Defaults to `undefined`. Alias: `aria-labelledby`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external descriptor element. */
+    /** ID of an external descriptor element. Defaults to `undefined`. Alias: `aria-describedby`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the combobox uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** 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`. */
     readonly value: _angular_core.ModelSignal<string | T | null>;
-    /** 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 `''`. */
     readonly inputValue: _angular_core.ModelSignal<string>;
-    /** Two-way bound open state of the popover. */
+    /** Two-way bound open state of the popover. Defaults to `false`. */
     readonly open: _angular_core.ModelSignal<boolean>;
-    /** 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. */
     readonly queryChange: _angular_core.OutputEmitterRef<string>;
-    /** 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`. */
     readonly optionSelected: _angular_core.OutputEmitterRef<TwComboboxOptionSelectedEvent<T>>;
     /** Fires whenever `value` changes, with a `source` discriminator distinguishing option / free-text / reset / programmatic origin. */
     readonly valueCommit: _angular_core.OutputEmitterRef<TwComboboxValueCommitEvent<T>>;
-    /** 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. */
     readonly openedChange: _angular_core.OutputEmitterRef<TwComboboxOpenedEvent>;
     /** @internal */
     readonly optionTemplateChild: Signal<ComboboxOptionTemplateDirective<any, any> | undefined>;
@@ -211,6 +211,7 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     private readonly inputRef;
     private readonly triggerSurfaceRef;
     private readonly overlayService;
+    private readonly coordinator;
     private readonly elementRef;
     private readonly viewContainerRef;
     private readonly injector;
@@ -220,9 +221,6 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     private readonly platform;
     private readonly formField;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly uid;
     /** @internal */
     readonly hostId: string;
@@ -237,25 +235,34 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     /** @internal */
     readonly focusedSignal: _angular_core.WritableSignal<boolean>;
     private readonly cvaDisabled;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private readonly describedByIdsSignal;
     private readonly labelledByIdsSignal;
     /** @internal */
     readonly lastCommittedLabel: _angular_core.WritableSignal<string>;
     private readonly pendingWriteValue;
-    private readonly closingSignal;
     /** Re-runs the input handler once after IME composition ends. */
     private composingPendingValue;
     private onChange;
     private onTouched;
-    private overlayRef;
-    private readonly overlayInstanceSignal;
-    private closeTimer;
     private queryDebounceTimer;
     private announceTimer;
+    /**
+     * 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`).
+     */
     private resizeObserver;
-    private get overlayInstance();
+    private overlayInstance;
+    private closing;
+    /**
+     * 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.
+     */
+    private readonly isAttached;
     /** @internal */
     readonly isDisabled: Signal<boolean>;
     /** @internal Auto-naked when wrapped in tw-form-field. */
@@ -307,8 +314,18 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     readonly empty: Signal<boolean>;
     /** @internal */
     readonly disabled: Signal<boolean>;
-    /** @internal */
+    /**
+     * @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.
+     */
     readonly required: Signal<boolean>;
+    /** @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. */
+    readonly errors: Signal<Record<string, unknown> | null>;
     /** @internal */
     readonly controlType = "combobox";
     /** @internal */
@@ -338,7 +355,15 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     onKeydown(event: KeyboardEvent): void;
     /** @internal — preventDefault to keep DOM focus on the input. */
     onClearMousedown(event: MouseEvent): void;
-    /** @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: MouseEvent): void;
     /** Clears the input and committed value, emitting `valueCommit({ source: 'reset' })`. */
     clear(): void;
@@ -352,24 +377,40 @@ declare class ComboboxComponent<T = unknown> implements ControlValueAccessor, Fo
     private scheduleQueryEmit;
     private clearQueryDebounceTimer;
     private clearAnnounceTimer;
+    /**
+     * 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.
+     */
     private openOverlay;
     private closeOverlay;
-    private ensureOverlay;
     private installResizeObserver;
     private updateOverlaySize;
-    private attachOverlayComponent;
-    private subscribeBackdrop;
     /**
-     * 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.
      */
-    private subscribeOverlayEscape;
+    private subscribePerOpen;
     private resolvePanelClass;
-    private clearCloseTimer;
     writeValue(value: T | string | null): void;
     registerOnChange(fn: (value: T | string | null) => void): void;
     registerOnTouched(fn: () => void): void;

package/types/cdevhub-ngx-tw-command-palette-testing.d.ts

@@ -0,0 +1,136 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `CommandPaletteItemHarness.with`. */
+interface CommandPaletteItemHarnessFilters extends BaseHarnessFilters {
+    /** Match by the item's visible text, which includes its description when it has one. */
+    text?: string | RegExp;
+    /** Match the active (`aria-activedescendant`) item. */
+    active?: boolean;
+    /** Match disabled / enabled items. */
+    disabled?: boolean;
+}
+/**
+ * Harness for a single result row in an open `tw-command-palette`.
+ *
+ * These rows are `role="option"` inside an activedescendant listbox: they never
+ * receive DOM focus and have no keyboard handlers of their own. "Active" here
+ * therefore means *referenced by the input's `aria-activedescendant`*, which the
+ * component mirrors onto each row as `aria-selected`. It does **not** mean
+ * `document.activeElement`.
+ */
+declare class CommandPaletteItemHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: CommandPaletteItemHarnessFilters): HarnessPredicate<CommandPaletteItemHarness>;
+    /** The row's rendered text, trimmed. Includes the description when one is rendered. */
+    getText(): Promise<string>;
+    /** The row's DOM id, which is what `aria-activedescendant` points at. */
+    getId(): Promise<string | null>;
+    /**
+     * Whether this row is the active descendant. Read from `aria-selected`, which
+     * the component binds to the active id — not from DOM focus, which never moves
+     * off the search input.
+     */
+    isActive(): Promise<boolean>;
+    /** Whether the row reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Clicks the row, activating the command. */
+    click(): Promise<void>;
+}
+
+/** Filters accepted by `CommandPaletteHarness.with`. */
+interface CommandPaletteHarnessFilters extends BaseHarnessFilters {
+    /** Match by the palette's accessible label. */
+    label?: string | RegExp;
+}
+/**
+ * Harness for `tw-command-palette`.
+ *
+ * The palette renders into the CDK overlay container, outside the
+ * `tw-command-palette` host, so this harness resolves the panel through
+ * `documentRootLocatorFactory()`. A consumer loads it from the ordinary fixture
+ * loader and still reaches the results.
+ *
+ * The palette is an **activedescendant listbox**: DOM focus stays on the search
+ * input and the active row is identified only by `aria-activedescendant`. Every
+ * "active" method here resolves that id reference — none of them consults
+ * `document.activeElement`, which would always report the input.
+ */
+declare class CommandPaletteHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly panel;
+    private readonly input;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: CommandPaletteHarnessFilters): HarnessPredicate<CommandPaletteHarness>;
+    /** Whether the palette overlay is currently attached. */
+    isOpen(): Promise<boolean>;
+    /** The palette's accessible label, or `null` when it is closed. */
+    getLabel(): Promise<string | null>;
+    /** The current search query. Returns an empty string when the palette is closed. */
+    getQuery(): Promise<string>;
+    /**
+     * Types into the search input, replacing any existing query, then waits for
+     * the results to settle.
+     */
+    setQuery(query: string): Promise<void>;
+    /** Clears the search query. */
+    clearQuery(): Promise<void>;
+    /**
+     * Sends Escape to the search input. No-op when the palette is already closed.
+     *
+     * **The overlay is still attached when this resolves.** The component defers
+     * the detach behind a leave animation, so a caller asserting on `isOpen()`
+     * immediately afterwards will still see `true`. Wait for the animation before
+     * asserting — with a plain timer, not by polling a harness method.
+     *
+     * That caveat is deliberate rather than hidden behind a poll. An earlier
+     * version looped on `isOpen()` until the panel detached, which reads better
+     * but is unsound here: every harness call routes through
+     * `fixture.whenStable()`, and under zoneless that can wait on a re-scheduled
+     * timer and never resolve. A deadline checked *between* awaits cannot bound a
+     * single await that never returns, so the loop hung the suite instead of
+     * failing it. A harness that can hang is worse than one that makes the caller
+     * wait explicitly.
+     *
+     * **This method is not covered by a spec.** A test driving it hung at the full
+     * 15000ms budget in roughly one run in three: the harness calls it makes
+     * around a leave animation route through `whenStable()`, which can wait on a
+     * re-scheduled timer and never resolve. Escape dismissal itself is covered in
+     * `command-palette.spec.ts`, directly against the component.
+     */
+    close(): Promise<void>;
+    /** Moves the active descendant down one row. */
+    pressArrowDown(): Promise<void>;
+    /** Moves the active descendant up one row. */
+    pressArrowUp(): Promise<void>;
+    /** Activates the current active descendant with Enter. */
+    pressEnter(): Promise<void>;
+    /**
+     * Every result row currently rendered. Returns an empty array when the palette
+     * is closed.
+     */
+    getItems(filters?: CommandPaletteItemHarnessFilters): Promise<CommandPaletteItemHarness[]>;
+    /**
+     * The labels of the rendered group headings, in DOM order. Ungrouped results
+     * produce an empty array.
+     */
+    getGroupLabels(): Promise<string[]>;
+    /**
+     * The text of the active row, resolved through the input's
+     * `aria-activedescendant`, or `null` when nothing is active.
+     */
+    getActiveItemText(): Promise<string | null>;
+    /**
+     * Clicks the first row whose text matches. Throws when nothing matches, rather
+     * than failing silently.
+     */
+    selectItem(text: string | RegExp): Promise<void>;
+    /**
+     * The search input, or a named error when the palette is closed. Every typing
+     * and key method needs it, and "cannot read property of null" would not say why.
+     */
+    private requireInput;
+}
+
+export { CommandPaletteHarness, CommandPaletteItemHarness };
+export type { CommandPaletteHarnessFilters, CommandPaletteItemHarnessFilters };

package/types/cdevhub-ngx-tw-command-palette.d.ts

@@ -33,19 +33,45 @@ interface CommandPaletteRef {
     setQuery(query: string): void;
 }
 /** Injection token providing a `CommandPaletteRef` to palette overlay content. */
+declare const TW_COMMAND_PALETTE_REF: InjectionToken<CommandPaletteRef>;
+/**
+ * @deprecated Renamed to {@link TW_COMMAND_PALETTE_REF} for consistency with
+ * every other ngx-tw injection token. This is the *same token instance*, not a
+ * copy — providing under either name and injecting under the other resolves —
+ * so the rename is safe to adopt incrementally. Removed in the next major.
+ */
 declare const COMMAND_PALETTE_REF: InjectionToken<CommandPaletteRef>;
 
-/** Resolved item shape used internally — merges declarative directive refs with data entries. */
+/**
+ * One entry of the palette's resolved item list — the merge of a declarative
+ * `*twCommandPaletteItem` directive with a `commands` array entry.
+ *
+ * Public because it is the element type of {@link CommandPaletteComponent.filteredItems}
+ * and the parameter type of `selectItem()` / `setActiveItem()`. Re-exported
+ * from the entry point as `CommandPaletteResolvedItem`.
+ */
 interface ResolvedItem {
+    /** The underlying item data, whether declared inline or supplied via `commands`. */
     readonly data: CommandPaletteItem;
+    /** The declarative directive backing this item, when it came from a template. */
     readonly directive?: CommandPaletteItemDirective;
+    /** The custom row template to render instead of the default row, when one was supplied. */
     readonly template?: TemplateRef<unknown>;
+    /** The item's shortcut, normalised to a key list. Empty when the item declares none. */
     readonly shortcutKeys: readonly string[];
 }
-/** A rendered group in the filtered view. */
+/**
+ * A rendered group in the filtered view.
+ *
+ * Public because it is the element type of {@link CommandPaletteComponent.grouped}.
+ * Re-exported from the entry point as `CommandPaletteResolvedGroup`.
+ */
 interface ResolvedGroup {
+    /** Stable DOM id for the group's section element. */
     readonly id: string;
+    /** The group header text, or `undefined` for the implicit ungrouped bucket. */
     readonly label?: string;
+    /** The group's items, in filtered order. */
     readonly items: readonly ResolvedItem[];
 }
 /** Optional explicit grouping wrapper. Items placed inside inherit its label. */
@@ -110,7 +136,7 @@ declare class CommandPaletteComponent {
     readonly size: _angular_core.InputSignal<TwSize>;
     /** Placeholder text shown inside the search input. Defaults to `'Type a command or search…'`. */
     readonly placeholder: _angular_core.InputSignal<string>;
-    /** Two-way bindable search query. Reads or resets the current filter. Defaults to `''`. */
+    /** Two-way bindable search query. Writes back on every keystroke in the search input. Opening and closing the palette leave it untouched — reset it yourself if each open should start empty. Defaults to `''`. */
     readonly query: _angular_core.ModelSignal<string>;
     /** Two-way bindable open state. Setting to `true` opens the palette; closing updates it to `false`. Defaults to `false`. */
     readonly open: _angular_core.ModelSignal<boolean>;
@@ -144,6 +170,8 @@ declare class CommandPaletteComponent {
     private readonly destroyRef;
     private readonly focusTrapFactory;
     private readonly announcer;
+    private readonly document;
+    private readonly isBrowser;
     private readonly declarativeItems;
     private readonly emptyDirective;
     private readonly footerDirective;
@@ -218,5 +246,5 @@ declare class CommandPaletteComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<CommandPaletteComponent, "tw-command-palette", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "query": { "alias": "query"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; "commands": { "alias": "commands"; "required": false; "isSignal": true; }; "filterFn": { "alias": "filterFn"; "required": false; "isSignal": true; }; "closeOnSelect": { "alias": "closeOnSelect"; "required": false; "isSignal": true; }; "closeOnEscape": { "alias": "closeOnEscape"; "required": false; "isSignal": true; }; "closeOnBackdropClick": { "alias": "closeOnBackdropClick"; "required": false; "isSignal": true; }; "autoFocus": { "alias": "autoFocus"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "searchAriaLabel": { "alias": "searchAriaLabel"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; }, { "query": "queryChange"; "open": "openChange"; "itemSelected": "itemSelected"; "opened": "opened"; "closed": "closed"; }, ["declarativeItems", "emptyDirective", "footerDirective"], ["*"], true, never>;
 }
 
-export { COMMAND_PALETTE_REF, CommandPaletteComponent, CommandPaletteEmptyDirective, CommandPaletteFooterDirective, CommandPaletteGroupDirective, CommandPaletteItemDescriptionDirective, CommandPaletteItemDirective, CommandPaletteItemIconDirective };
-export type { CommandPaletteFilterFn, CommandPaletteItem, CommandPaletteRef };
+export { COMMAND_PALETTE_REF, CommandPaletteComponent, CommandPaletteEmptyDirective, CommandPaletteFooterDirective, CommandPaletteGroupDirective, CommandPaletteItemDescriptionDirective, CommandPaletteItemDirective, CommandPaletteItemIconDirective, TW_COMMAND_PALETTE_REF };
+export type { CommandPaletteFilterFn, CommandPaletteItem, CommandPaletteRef, ResolvedGroup as CommandPaletteResolvedGroup, ResolvedItem as CommandPaletteResolvedItem };