@nordhealth/components 4.26.2 → 5.0.0

package/lib/src/combobox/ComboboxBase.d.ts

@@ -0,0 +1,421 @@
+import type { CSSResult, PropertyValues, TemplateResult } from 'lit';
+import { LitElement, nothing } from 'lit';
+import { ActiveDescendantController } from '../common/controllers/ActiveDescendantController.js';
+import { LocalizeController } from '../localization/LocalizeController.js';
+import '../popout/Popout.js';
+import '../spinner/Spinner.js';
+/**
+ * A single option in a combobox.
+ */
+export interface ComboboxOption {
+    /** The value submitted with the form and tracked in `value`. */
+    value: string;
+    /** The human-readable text shown in the list and the input. */
+    label: string;
+    /** Optional group heading used to cluster related options together. */
+    group?: string;
+    /** When `true`, the option cannot be selected. */
+    disabled?: boolean;
+    /** Optional rich HTML rendered instead of the plain `label` text. */
+    html?: string;
+    /** Arbitrary data attached to the option, passed back to `renderOption`. */
+    [key: string]: unknown;
+}
+/**
+ * Re-prefixes an authored, tag-scoped stylesheet for another tag name so a
+ * sibling light-DOM component (e.g. `nord-autocomplete`) can reuse the exact
+ * same `.n-*` rules without duplicating them. `Combobox.css` is the single
+ * source of truth; this swaps the top-level `nord-combobox` selector token.
+ */
+export declare function retagComboboxStyles(styles: CSSResult, tag: string): CSSResult;
+declare const ComboboxBase_base: (new (...args: any[]) => import("../common/mixins/SizeMixin.js").SizeMixinInterface) & (new (...args: any[]) => import("../common/mixins/AutocompleteMixin.js").AutocompleteMixinInterface) & (new (...args: any[]) => import("../common/mixins/FieldControlMixin.js").FieldControlMixinInterface) & (new (...args: any[]) => import("../common/mixins/InputMixin.js").InputMixinInterface) & (new (...args: any[]) => import("../common/mixins/FloatingComponentMixin.js").FloatingMixinInterface) & typeof LitElement;
+/**
+ * `ComboboxBase` is the (unregistered) shared base for `nord-combobox` (pick an
+ * option, or several) and `nord-autocomplete` (free-text input with suggestions
+ * where the typed text is the value). It owns every piece of the dropdown that
+ * the two share — options, filtering, virtualization, keyboard navigation, the
+ * popout, light-dismiss, ARIA wiring and rendering — and exposes a set of
+ * protected hooks for the handful of behaviours that differ between a select and
+ * a free-text control.
+ *
+ * Base UI parity: Autocomplete is the Combobox primitive with
+ * `selectionMode="none"` + `fillInputOnItemPress`.
+ *
+ * Subclasses MUST `injectLightDomStyles(this, <their stylesheet>)` in
+ * `connectedCallback` (the base does not import a stylesheet, since the rules are
+ * tag-scoped and each tag needs its own copy — see `retagComboboxStyles`).
+ *
+ * Not a registered custom element: it has no `@customElement` decorator and no
+ * tag name, so the manifest config marks it `internal` and the React/Vue type
+ * generators skip it.
+ */
+export default abstract class ComboboxBase extends ComboboxBase_base {
+    /** Stable, unique id base for the light-DOM ARIA wiring of this instance. */
+    private comboboxId;
+    protected inputId: string;
+    protected inputRef: import("lit/directives/ref.js").Ref<HTMLInputElement>;
+    private formData;
+    /**
+     * Remembers value→label pairs seen from any option so a preselected value
+     * that has since left the loaded options still renders its label.
+     */
+    protected labelCache: Map<string, string>;
+    protected localize: LocalizeController<"nord-combobox">;
+    /** Re-renders when the host's forwarded ARIA labelling attributes change. */
+    private ariaObserver?;
+    private widthObserver?;
+    private popout?;
+    private dismiss;
+    /**
+     * Reflects the control's state to Base-UI-style `data-*` attributes
+     * (`data-invalid`, `data-focused`) so consumers can style the whole control.
+     * `trackFocus` keeps `data-focused` present while focus stays within the host
+     * — e.g. moving between the input and the clear button.
+     */
+    private stateAttributes;
+    /**
+     * The options to show in the combobox.
+     */
+    options: ComboboxOption[];
+    /**
+     * Placeholder text to display within the input.
+     */
+    placeholder?: string;
+    /**
+     * Use external filtering mode. When set to `true`, the component will not
+     * perform internal text-based filtering and expects the consumer to update
+     * the `options` in response to the `input` event.
+     */
+    externalFiltering: boolean;
+    /**
+     * Shows a spinner in the control and listbox while asynchronous results are
+     * loading. Pair with `external-filtering` for async search.
+     */
+    loading: boolean;
+    /**
+     * Highlights the first option after filtering so pressing Enter selects it.
+     */
+    autoHighlight: boolean;
+    /**
+     * Marks the control as invalid, applying error styling and setting
+     * `aria-invalid` on the input.
+     */
+    invalid: boolean;
+    protected get ownInvalid(): boolean;
+    /**
+     * Marks the control read-only: the value stays visible, focusable and
+     * submitted with the form, but the listbox can't be opened and the value can't
+     * be changed (no typing, navigation, selection or clearing). Unlike `disabled`,
+     * a read-only control still participates in form submission.
+     */
+    readonly: boolean;
+    /**
+     * Whether clicking the input opens the listbox. Defaults to `true`. Set to
+     * `false` to only open on typing or a trigger (chevron) click. Focusing the
+     * input (e.g. tabbing in) never opens the list on its own. Mirrors Base UI's
+     * `openOnInputClick`.
+     */
+    openOnInputClick: boolean;
+    /**
+     * Message shown when no options match the query. Defaults to "No items found.".
+     */
+    noResultsText?: string;
+    /**
+     * Virtualizes (windows) the option list so only the rows in view are rendered,
+     * keeping very large lists (thousands of options) fast. Rows are assumed to be a
+     * uniform height, which is measured from the first option. Virtualization is
+     * skipped for grouped lists, whose labels and separators break that assumption —
+     * grouped lists are expected to be short and curated.
+     */
+    virtualized: boolean;
+    /**
+     * Custom renderer for the content of each option. Receives the option and
+     * should return a Lit `TemplateResult` or a string. When omitted, the
+     * option's `html` (if present) or `label` is rendered.
+     */
+    renderOption?: (option: ComboboxOption) => TemplateResult | string;
+    /** The current search query in the combobox input. */
+    protected search: string;
+    /**
+     * Whether the user has actually typed into the input since it was last
+     * opened/committed. Until they do, a single-select shows the committed
+     * selection's label in the input (editable) rather than an empty filter —
+     * matching Base UI, where reopening keeps the selected label visible and the
+     * list unfiltered until the first keystroke. Set on typing; cleared on commit
+     * and on close.
+     */
+    protected queryDirty: boolean;
+    /**
+     * Tracks the active (highlighted) row of the virtual-focus listbox: the focus
+     * stays on the input while this roams the rows and surfaces as
+     * `aria-activedescendant`. Owns the wrap / skip-disabled / move math the
+     * combobox previously duplicated. The out-of-range create row (index ===
+     * `filteredOptions.length`) reports as enabled (`filteredOptions[i]` is
+     * `undefined`, so `!undefined?.disabled` is `true`) and maps to its create-row
+     * id, matching the create-row semantics.
+     */
+    protected activeDescendant: ActiveDescendantController;
+    /** The scroll container for the options; the virtualizer's scroll element. */
+    private listboxEl?;
+    /**
+     * Containers for the `start`/`end` slot content. The control renders into the
+     * light DOM, so real `<slot>` elements don't project; instead these act as
+     * landing zones and the matching host children (`slot="start"`/`slot="end"`)
+     * are relocated into them. A `ResizeController` per zone feeds the measured
+     * inline size into a custom property so the input padding can clear the slot
+     * (mirrors `nord-input`).
+     */
+    private startSlot?;
+    private endSlot?;
+    private startObserver;
+    private endObserver;
+    /** Re-renders when the host's `slot="start"`/`slot="end"` children change. */
+    private slotObserver?;
+    /** Set when a keyboard move should scroll the active option into view. */
+    protected scrollActivePending: boolean;
+    /** Row-height estimate used until the uniform row height is measured once. */
+    private static readonly VIRTUAL_ROW_ESTIMATE;
+    /** Extra rows rendered above and below the viewport to smooth scrolling. */
+    private static readonly VIRTUAL_OVERSCAN;
+    /**
+     * The measured uniform row height, sampled once from the first rendered row.
+     * Option rows are a fixed height, so a single sample feeds `estimateSize` for
+     * the whole list — far cheaper and more stable than re-measuring every row on
+     * every render, which fed a `measure → onChange → re-render → measure` loop
+     * that could peg the main thread.
+     */
+    private measuredRowSize?;
+    /**
+     * Windows the flat option list (see `virtualized`) with TanStack Virtual: only
+     * the rows in view are rendered, sized from the measured uniform row height,
+     * and the active option is kept on-screen via `scrollToIndex`. Its `onChange`
+     * re-renders the host on scroll/resize; `count` is kept in sync in `willUpdate`.
+     */
+    private virtualizer;
+    /**
+     * Whether the user has moved the active option with the keyboard since the
+     * last filter change. Used to decide if a bare Enter (no navigation) selects
+     * the highlighted option — only when `autoHighlight` is set, the first option
+     * becomes implicitly selectable.
+     */
+    protected navigated: boolean;
+    /**
+     * Whether the input currently shows the transient query rather than the
+     * committed selection's label. A single-select shows the query only once the
+     * user starts typing (`queryDirty`); until then — including right after
+     * reopening — the input keeps the selected option's label visible and
+     * editable, matching Base UI. `multiple` shows the query always (the
+     * selections live in chips, not the input).
+     */
+    protected get showsQueryInInput(): boolean;
+    /** The text shown in the input. Select: query while open, label when closed. */
+    protected get displayValue(): string;
+    /** The placeholder forwarded to the inner input. */
+    protected get inputPlaceholder(): string | undefined;
+    /** The transient search text the list is filtered against. */
+    protected get filterQuery(): string;
+    /** Whether an option is selected (drives `aria-selected` and the check icon). */
+    protected isSelected(option: ComboboxOption): boolean;
+    /** Serialises `value` for the form. */
+    protected get formValue(): string | undefined;
+    /** Whether there is any committed value (drives the clear affordance). */
+    protected get hasValue(): boolean;
+    /** The index of the create row, or `-1` when it isn't shown. Select-only. */
+    protected get createIndex(): number;
+    /** Whether the "Create" affordance should be offered for the current query. */
+    protected get canCreate(): boolean;
+    /** Leading content inside the control (e.g. chips). None by default. */
+    protected renderLeadingControl(): unknown;
+    /** The `aria-autocomplete` value for the inner input. */
+    protected get ariaAutocomplete(): string;
+    /** Commit the active option. Select: set value, close, restore focus. */
+    protected selectOption(option: ComboboxOption): void;
+    /**
+     * Hook for the Enter key when the listbox is open and the create/option
+     * branches have not handled it. Default: no-op (the base handles option
+     * selection in `handleKeydown`). Subclasses (autocomplete) return `true` to
+     * signal they fully handled Enter.
+     */
+    protected handleEnter(_e: KeyboardEvent): boolean;
+    /** Hook invoked when a key is pressed (before the switch). Autocomplete uses it. */
+    protected onKeydown(_e: KeyboardEvent): void;
+    /** Hook invoked on input blur. Autocomplete reverts inline ghosts here. */
+    protected onBlur(): void;
+    /** Hook invoked after each render (for inline-ghost selection, etc.). */
+    protected afterUpdate(): void;
+    /** Hook invoked when the pointer hovers an option (autocomplete clears ghost state). */
+    protected onOptionHover(): void;
+    /** Hook invoked when ArrowUp/ArrowDown moves the active option. */
+    protected onMove(): void;
+    /** Normalises `value` to an array regardless of single/multiple shape. */
+    protected get values(): string[];
+    /** Upper bound on the label cache so long async sessions don't grow it forever. */
+    private static labelCacheLimit;
+    /** Records value→label pairs so labels survive options leaving the result set. */
+    protected cacheLabels(options: ComboboxOption[]): void;
+    /**
+     * Memoised filter result. `filteredOptions` is read many times per render (and
+     * per keyboard/scroll event via rowCount/activeOption/isVirtual), so the O(n)
+     * filter + groupBy must not re-run on every access — that would defeat the
+     * point of virtualizing a large list. Recomputed only when the options, the
+     * query, or the filtering mode change; the group map is cached alongside.
+     */
+    private filteredCache?;
+    /**
+     * The options the control filters and renders from. The base uses the
+     * `options` property directly; `Combobox` overrides this to merge declarative
+     * `<nord-combobox-option>` children and auto-created options.
+     */
+    protected get resolvedOptions(): ComboboxOption[];
+    protected get filtered(): {
+        options: ComboboxOption[];
+        query: string;
+        external: boolean;
+        result: ComboboxOption[];
+        hasGroups: boolean;
+        groups?: Map<string | undefined, ComboboxOption[]>;
+    };
+    /** The options remaining after filtering by the current query. */
+    protected get filteredOptions(): ComboboxOption[];
+    /** Total number of keyboard-navigable rows, including the create row. */
+    protected get rowCount(): number;
+    /** The currently active option, used for `aria-activedescendant` and Enter. */
+    protected get activeOption(): ComboboxOption | undefined;
+    /**
+     * Whether the option list is currently windowed. Only flat (non-grouped) lists
+     * with at least one option are virtualized.
+     */
+    protected get isVirtual(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Relocates the host's `slot="start"`/`slot="end"` children into the matching
+     * landing zone inside the control. Only direct host children are considered,
+     * and a child already sitting in its zone is left untouched, so repeated
+     * updates are idempotent and don't disturb focus or pointer state.
+     */
+    private relocateSlots;
+    /** Mirrors the host (control) width into `--_n-combobox-anchor-inline-size`. */
+    protected syncAnchorInlineSize(): void;
+    protected createRenderRoot(): HTMLDivElement;
+    /**
+     * Show the listbox programmatically.
+     */
+    show(): void;
+    /**
+     * Hide the listbox programmatically.
+     */
+    hide(): void;
+    /**
+     * Hook for what happens to the transient query when the listbox closes.
+     * Select mode discards an abandoned filter query so the next open shows the
+     * full list and the selected option's label, not the stale search.
+     */
+    protected onHide(): void;
+    /**
+     * Focus the control's input.
+     */
+    focus(options?: FocusOptions): void;
+    protected handleOpenChange(): void;
+    /**
+     * Disabling the control while the listbox is open must close it. `show()`
+     * guards against opening when disabled, but nothing closes an already-open
+     * popout when `disabled` flips to `true` at runtime.
+     */
+    protected handleDisabledChange(): void;
+    /** Row height changes with the size variant, so re-sample it on the next render. */
+    protected resetRowSample(): void;
+    protected updated(changedProperties: PropertyValues): void;
+    /** Keeps `count` in sync with the filtered list before each render. */
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Keeps the active row visible after a keyboard move. Virtualized option rows
+     * ask the virtualizer to scroll the index into view (the row may not be in the
+     * DOM yet); the create row and plain lists defer to the browser since their
+     * element is always rendered.
+     */
+    private scrollActiveIntoView;
+    /** Keeps `open` in sync if the popout closes itself (e.g. light dismiss). */
+    private handlePopoutClose;
+    /** Swallows the popout's own `open` so the combobox emits a single `open`. */
+    private handlePopoutOpen;
+    /** Re-clamps the active index so it stays within the navigable rows. */
+    protected resetActiveIndex(): void;
+    protected handleInput(e: Event): void;
+    /** Hook after the search query updates from typing. Autocomplete commits live. */
+    protected onInput(_input: HTMLInputElement): void;
+    private handleBlur;
+    protected handleKeydown(e: KeyboardEvent): void;
+    /** Hook for keys the base switch does not handle (Backspace chips, etc.). */
+    protected onUnhandledKeydown(_e: KeyboardEvent): void;
+    /**
+     * Fires the create affordance. Default is a no-op; the select combobox
+     * overrides this to dispatch its `create` event.
+     */
+    protected emitCreate(): void;
+    private move;
+    protected commit(): void;
+    /** Resolves a value to its best-known label (current options, then cache). */
+    protected labelFor(value: string): string;
+    render(): TemplateResult<1>;
+    /** Whether the clear (✕) affordance shows. Off by default (no `clearable`). */
+    protected get showClear(): boolean;
+    /**
+     * Whether the dropdown chevron toggle (and the divider before it) renders. On
+     * by default — the combobox is a picker that opens its full list on click —
+     * but hidden while `readonly`, where the value is shown but not interactive.
+     * Autocomplete overrides this to `false`: like Base UI's autocomplete (which
+     * renders no `Trigger`), it is a search input whose list appears on typing.
+     */
+    protected get showToggle(): boolean;
+    /**
+     * Drives the listbox `aria-multiselectable`. Single-select by default;
+     * autocomplete overrides this to `undefined` so the attribute is omitted (it
+     * has no selection model).
+     */
+    protected get ariaMultiselectable(): 'true' | 'false' | undefined;
+    protected renderGroup(group: string | undefined, groupOptions: ComboboxOption[], indexByValue: Map<string, number>): TemplateResult<1>;
+    /** Resolves the content shown for a single option. */
+    protected optionContent(option: ComboboxOption): TemplateResult | unknown;
+    /**
+     * Samples the uniform row height once from the first rendered virtual row, then
+     * re-measures the virtualizer so the window is sized from the real height rather
+     * than the estimate. Runs only while the sample is missing and a laid-out row is
+     * present, so it never becomes a per-render measurement loop.
+     */
+    private sampleRowSize;
+    /**
+     * Renders only the virtual items currently in view, absolutely positioned
+     * inside a full-height sizer so the scrollbar reflects the whole list. Rows take
+     * a fixed height from the virtualizer (uniform rows), so no per-row measurement
+     * is needed. `setSize`/`posinset` give assistive tech the true total even though
+     * most rows aren't in the DOM.
+     */
+    private renderVirtualOptions;
+    protected renderListOption(option: ComboboxOption, index: number, setSize?: number): TemplateResult<1>;
+    /** The option's `aria-selected` value. Autocomplete omits it (returns nothing). */
+    protected optionAriaSelected(selected: boolean): string | typeof nothing;
+    /** Whether the selected-check icon shows. Autocomplete never shows it. */
+    protected showCheck(selected: boolean): boolean;
+    /**
+     * Whether the leading check gutter is rendered. Combobox reserves it so the
+     * selected tick sits on the left and every label lines up (matching the
+     * filter dropdown); autocomplete has no selection, so it omits the gutter to
+     * avoid indenting every suggestion.
+     */
+    protected get rendersCheck(): boolean;
+    /** The create row. Rendered only when `canCreate`; base returns nothing. */
+    protected renderCreate(): unknown;
+    protected renderEmpty(): TemplateResult<1>;
+    protected optionId(index: number): string;
+    /** The id used for the create row (so subclasses can reference it). */
+    protected get createId(): string;
+    /** Pointer hover highlights an option (without marking it as keyboard-navigated). */
+    protected handleOptionHover(index: number): void;
+    protected handleControlClick(): void;
+    protected handleClearClick(e: Event): void;
+    /** Clear the current value. Overridden by clearable variants. */
+    clear(): void;
+    protected handleToggleClick(e: Event): void;
+}
+export {};

package/lib/src/combobox/ComboboxEvents.d.ts

@@ -0,0 +1,25 @@
+import { NordEvent } from '../common/events.js';
+/**
+ * Dispatched when the user chooses the "Create" affordance in a `creatable`
+ * combobox. Carries the current search query. By default the combobox then adds
+ * the value as an option and selects it; the event is cancelable, so calling
+ * `preventDefault()` opts out and lets the consumer handle creation manually.
+ */
+export declare class ComboboxCreateEvent extends NordEvent {
+    /** The search query the user typed, offered as the new option's label. */
+    readonly value: string;
+    static eventName: string;
+    constructor(
+    /** The search query the user typed, offered as the new option's label. */
+    value: string);
+    /** Convenience accessor mirroring `CustomEvent.detail`. */
+    get detail(): string;
+}
+/**
+ * Dispatched when the value is cleared via the clear button or the `clear()`
+ * method, before the accompanying `change` event.
+ */
+export declare class ComboboxClearEvent extends NordEvent {
+    static eventName: string;
+    constructor();
+}

package/lib/src/combobox/ComboboxGroup.d.ts

@@ -0,0 +1,34 @@
+import { LitElement } from 'lit';
+/**
+ * Groups declarative `<nord-combobox-option>` children under a heading inside a
+ * [Combobox](/components/combobox/):
+ *
+ * ```html
+ * <nord-combobox>
+ *   <nord-combobox-group label="Frameworks">
+ *     <nord-combobox-option value="next">Next.js</nord-combobox-option>
+ *   </nord-combobox-group>
+ * </nord-combobox>
+ * ```
+ *
+ * Contained options inherit this `label` as their group. The element renders
+ * nothing itself and is hidden with `display: none`.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @slot - The group's `<nord-combobox-option>` children.
+ */
+export default class ComboboxGroup extends LitElement {
+    /** The group heading shown above its options. */
+    label: string;
+    private registry;
+    protected createRenderRoot(): this;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-combobox-group': ComboboxGroup;
+    }
+}

package/lib/src/combobox/ComboboxOption.d.ts

@@ -0,0 +1,47 @@
+import { LitElement } from 'lit';
+/**
+ * A declarative option for a [Combobox](/components/combobox/). Place these as
+ * children of `<nord-combobox>` instead of (or as an alternative to) setting the
+ * `.options` property:
+ *
+ * ```html
+ * <nord-combobox>
+ *   <nord-combobox-option value="bug">Bug</nord-combobox-option>
+ *   <nord-combobox-option value="feature">Feature</nord-combobox-option>
+ * </nord-combobox>
+ * ```
+ *
+ * The option's child markup becomes the rendered row, so you can author custom
+ * items (e.g. an avatar + text) without an `html` string or a render function.
+ * Set the `label` attribute when the visible markup isn't plain text, so
+ * filtering and the accessible name have something to match on.
+ *
+ * The element renders nothing itself — it is a data source the combobox reads via
+ * context and is hidden with `display: none`.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @slot - The option's label / custom content.
+ */
+export default class ComboboxOption extends LitElement {
+    /** The value submitted with the form and tracked in the combobox's `value`. */
+    value: string;
+    /** Whether the option is selectable. */
+    disabled: boolean;
+    /** Text used for filtering and the accessible name. Defaults to the text content. */
+    label?: string;
+    private registry;
+    /** Re-sync when the option's child content (custom markup) changes. */
+    private contentObserver?;
+    protected createRenderRoot(): this;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-combobox-option': ComboboxOption;
+    }
+}

package/lib/src/combobox/combobox-context.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The API a [Combobox](/components/combobox/) shares with its declarative
+ * `<nord-combobox-option>` / `<nord-combobox-group>` children so they can
+ * register themselves as options (provide/inject), instead of the combobox
+ * polling the DOM.
+ */
+export interface ComboboxRegistry {
+    /** Register an option element as a selectable option. */
+    add: (option: Element) => void;
+    /** Remove a previously-registered option element. */
+    remove: (option: Element) => void;
+    /** Re-read the registered options (after an attribute/content/group change). */
+    notify: () => void;
+}
+/** Context the combobox provides to its option/group children. */
+export declare const comboboxRegistryContext: {
+    __context__: ComboboxRegistry | undefined;
+};

package/lib/src/combobox/localization.d.ts

@@ -0,0 +1,6 @@
+declare const comboboxLocalization: {
+    clearLabel: string;
+    createLabel: (query: string) => string;
+    noResults: string;
+};
+export default comboboxLocalization;

package/lib/src/common/controllers/ActiveDescendantController.d.ts

@@ -0,0 +1,45 @@
+import type { ReactiveControllerHost } from 'lit';
+export interface ActiveDescendantOptions {
+    /** The number of navigable rows. */
+    count: () => number;
+    /** Whether the row at `index` can be activated (skip disabled rows). */
+    isEnabled: (index: number) => boolean;
+    /** Wrap at the ends. Defaults to `true`. */
+    loop?: () => boolean;
+    /** The DOM id of the row at `index`, used for `aria-activedescendant`. */
+    optionId?: (index: number) => string | undefined;
+}
+/**
+ * Tracks the active row of a virtual-focus listbox (combobox / filter dropdown):
+ * the focus stays on the input/trigger while an `activeIndex` roams the rows and
+ * is surfaced as `aria-activedescendant`. Centralises the `nextEnabledIndex` /
+ * `move` / wrap math the combobox and filter-dropdown previously duplicated.
+ */
+export declare class ActiveDescendantController {
+    private host;
+    private options;
+    private _activeIndex;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: ActiveDescendantOptions);
+    /** The active row index, or `-1` when nothing is active. */
+    get activeIndex(): number;
+    /** The active row's id for `aria-activedescendant`, or `undefined`. */
+    get activeDescendant(): string | undefined;
+    /** Set the active index, requesting a host update when it changes. */
+    setActiveIndex(index: number): void;
+    /** Clear the active row. */
+    reset(): void;
+    /**
+     * The next enabled row from `from` stepping by `dir`, wrapping (when looping)
+     * and skipping disabled rows. Returns `-1` if no row is enabled.
+     */
+    nextEnabledIndex(from: number, dir: 1 | -1): number;
+    /**
+     * Move the active row by `delta` (its sign is the direction). Starts from the
+     * matching end when nothing is active. Returns `true` if it moved.
+     */
+    move(delta: number): boolean;
+    /** Activate the first enabled row (Home). Returns `true` if one was found. */
+    first(): boolean;
+    /** Activate the last enabled row (End). Returns `true` if one was found. */
+    last(): boolean;
+}

package/lib/src/common/controllers/CollapseController.d.ts

@@ -0,0 +1,50 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+export interface CollapseOptions {
+    /** Reads the host's open state; diffed after every host update. */
+    open: () => boolean;
+    /**
+     * The CSS custom property set to the measured content height during the
+     * animation (e.g. `--n-accordion-panel-height`), for consumers to read.
+     */
+    heightVar: string;
+    /** The element to animate. Defaults to the host. */
+    target?: () => HTMLElement;
+}
+/**
+ * Animates a host's `block-size` between `0` and its measured content height as
+ * its `open` state toggles — the shared engine behind the accordion and
+ * collapsible panels. It measures the live rendered height (so rapid re-toggles
+ * continue smoothly rather than snapping), respects reduced motion, and cleans
+ * up on disconnect.
+ *
+ * It owns a {@link TransitionStatusController} (+ a {@link StateAttributesController})
+ * so the host also gains `data-open` / `data-closed` / `data-starting-style` /
+ * `data-ending-style` state hooks, driven off the same `block-size` transition.
+ */
+export declare class CollapseController implements ReactiveController {
+    private host;
+    private options;
+    private _animating;
+    private previousOpen?;
+    /** Exposes the transition status (and reflects the state attributes). */
+    private transitionStatus;
+    private stateAttributes;
+    constructor(host: ReactiveControllerHost & HTMLElement, options: CollapseOptions);
+    /** Whether a `block-size` transition is currently running. */
+    get animating(): boolean;
+    get status(): import("./TransitionStatusController.js").TransitionStatus;
+    private get target();
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    /**
+     * Measure the height to animate from. While a transition is in flight the box
+     * is mid-collapse/expand, so `scrollHeight` is clipped — use the live rendered
+     * height instead so we never snap to a stale full/zero height.
+     */
+    private currentHeight;
+    private animateOpen;
+    private animateClose;
+    private handleTransitionEnd;
+    private handleTransitionCancel;
+}