@nordhealth/components 4.26.2 → 5.0.0-alpha.0

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

@@ -0,0 +1,131 @@
+import type { ComboboxOption } from './ComboboxBase.js';
+import ComboboxBase from './ComboboxBase.js';
+import '../kbd/Kbd.js';
+import '../tag/Tag.js';
+import './ComboboxOption.js';
+import './ComboboxGroup.js';
+export type { ComboboxOption } from './ComboboxBase.js';
+export { ComboboxClearEvent, ComboboxCreateEvent } from './ComboboxEvents.js';
+/**
+ * Combobox lets users choose one option (or several) from a list by typing to
+ * filter, then picking with the keyboard or pointer. Use it when a [Select](/components/select/)
+ * would be unwieldy because there are many options to scan.
+ *
+ * Combobox is a control only — it has no built-in label, hint or error. Compose
+ * it inside a [Field](/components/field/) to give it a label, hint and error
+ * message, the same way you would a native input.
+ *
+ * The committed `value` is an option's `value` (or an array of them with
+ * `multiple`); the input is a filter/search field whose text is discarded on
+ * commit. For a free-text input with suggestions where the typed text is the
+ * value, use [Autocomplete](/components/autocomplete/) instead.
+ *
+ * @status draft
+ * @category form
+ * @lightDom true
+ *
+ * @slot start - Optional slot used to place an icon or prefix at the start of the control.
+ * @slot end - Optional slot used to place an icon or suffix at the end of the control.
+ *
+ * @fires {NordEvent} change - Dispatched when the committed value changes via user interaction.
+ * @fires {NordEvent} input - Dispatched as the user types into the search input.
+ * @fires {NordEvent} open - Dispatched when the listbox is opened.
+ * @fires {NordEvent} close - Dispatched when the listbox is closed.
+ * @fires {ComboboxClearEvent} clear - Dispatched when the value is cleared via the clear button or `clear()`.
+ * @fires {ComboboxCreateEvent} create - Dispatched when the user chooses the "Create" affordance in a `creatable` combobox.
+ *
+ * @localization clearLabel - Accessible label for the clear button.
+ * @localization createLabel - Label for the "Create" affordance, given the current query.
+ * @localization noResults - Message shown when no options match the query.
+ *
+ * @cssprop [--n-combobox-list-inline-size] - Controls the inline size, or width, of the dropdown list. Defaults to the width of the combobox control.
+ * @cssprop [--n-combobox-block-size] - Controls the block size, or height, of the control. The medium default is `var(--n-space-xl)`; the s and l sizes scale from it.
+ *
+ * @attr {boolean} data-invalid - Present while the control is invalid (mirrors the `invalid` property). Style hook for the whole control.
+ * @attr {boolean} data-focused - Present while the control has focus. Style hook for focus-within treatments.
+ */
+export default class Combobox extends ComboboxBase {
+    /**
+     * The value of the combobox. A single string when `multiple` is `false`,
+     * or an array of strings when `multiple` is `true`.
+     */
+    value: string | string[];
+    /**
+     * Allows selecting more than one option. Selected options are shown as
+     * removable chips and the listbox stays open after each selection.
+     */
+    multiple: boolean;
+    /**
+     * Shows a clear (✕) button while there is a value. Pressing it resets the
+     * value to `''` (or `[]` when `multiple`), then fires `clear` and `change`.
+     * Defaults to `true`.
+     *
+     * This prop only toggles the button. A single-select value can always be
+     * cleared by deleting the input text, regardless of this prop (Base UI
+     * parity).
+     */
+    clearable: boolean;
+    /**
+     * Offers a "Create" affordance when the query does not exactly match an
+     * existing option. Choosing it (click or Enter) adds the typed value as an
+     * option and selects it (in `multiple` mode it is appended as a chip), and
+     * fires a cancelable `create` event. Call `event.preventDefault()` to opt out
+     * and handle creation yourself (e.g. to map the value to a different `value`).
+     */
+    creatable: boolean;
+    /** Options contributed by declarative `<nord-combobox-option>` children. */
+    private slottedOptions;
+    /** Options the combobox created itself via the auto-add `creatable` flow. */
+    private createdOptions;
+    /** Registered declarative option elements (rebuilt into `slottedOptions`). */
+    private optionElements;
+    /** The registry the option/group children use to self-register (provide/inject). */
+    private optionRegistry;
+    private registryProvider;
+    connectedCallback(): void;
+    /** Read a registered option element into a plain `ComboboxOption`. */
+    private readOptionElement;
+    /** Rebuild `slottedOptions` from the registered elements, in DOM order. */
+    private rebuildSlottedOptions;
+    /** Cache for the merged option list so `filtered`'s identity check stays stable. */
+    private resolvedCache?;
+    /**
+     * The options to render: the `.options` property when set (dynamic/async data),
+     * otherwise the declarative `<nord-combobox-option>` children, with any
+     * auto-created options merged on top.
+     */
+    protected get resolvedOptions(): ComboboxOption[];
+    /** Whether chip/array logic applies — i.e. `multiple` selection. */
+    private get isMultiple();
+    /**
+     * In `multiple` mode the input is always a pure filter (selections live in
+     * chips). In single-select it shows the live query only once the user types;
+     * until then it keeps the selected option's label visible and editable (Base
+     * UI parity — see `ComboboxBase.showsQueryInInput`).
+     */
+    protected get showsQueryInInput(): boolean;
+    protected get inputPlaceholder(): string | undefined;
+    /** The index of the create row, or `-1` when it isn't shown. */
+    protected get createIndex(): number;
+    /** Whether the "Create" affordance should be offered for the current query. */
+    protected get canCreate(): boolean;
+    protected get showClear(): boolean;
+    protected get ariaMultiselectable(): 'true' | 'false';
+    /**
+     * Clear the current value, firing `clear` then `change`.
+     */
+    clear(): void;
+    protected selectOption(option: ComboboxOption): void;
+    protected onInput(input: HTMLInputElement): void;
+    protected emitCreate(): void;
+    protected onUnhandledKeydown(e: KeyboardEvent): void;
+    private removeValue;
+    /** Multiple mode renders selected options as removable chips before the input. */
+    protected renderLeadingControl(): unknown;
+    protected renderCreate(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'nord-combobox': Combobox;
+    }
+}

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 focusing or clicking into the input opens the listbox. Defaults to
+     * `true`. Set to `false` to only open on typing or a trigger (chevron) click.
+     */
+    openOnFocus: 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;
+    /** Suppresses focus-to-open while focus is being restored after a selection. */
+    protected suppressFocusOpen: boolean;
+    /**
+     * 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;
+    protected handleFocus(): 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.
+     * 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;
+    }
+}