@lumx/core 4.8.1 → 4.9.0-alpha.1

package/js/components/Combobox/setupComboboxButton.d.ts

@@ -0,0 +1,16 @@
+import type { ComboboxCallbacks, ComboboxHandle } from './types';
+/**
+ * Set up a combobox with a button trigger (select-only pattern).
+ *
+ * Creates a full combobox handle with the button-mode controller automatically
+ * wired in and the trigger registered. The consumer only needs to call
+ * `handle.registerListbox(listbox)`.
+ *
+ * Handles: Space (select/open), Home/End (listbox navigation),
+ * printable characters (typeahead), and click (toggle).
+ *
+ * @param button    The button element to use as the combobox trigger.
+ * @param callbacks Callbacks for select and open/close events.
+ * @returns A ComboboxHandle for interacting with the combobox.
+ */
+export declare function setupComboboxButton(button: HTMLButtonElement, callbacks: ComboboxCallbacks): ComboboxHandle;

package/js/components/Combobox/setupComboboxInput.d.ts

@@ -0,0 +1,29 @@
+import type { ComboboxCallbacks, ComboboxHandle } from './types';
+/** Options for configuring the input-mode combobox controller. */
+export interface SetupComboboxInputOptions {
+    /**
+     * When true (default), the combobox automatically filters options as the user types.
+     * Each registered `Combobox.Option` receives filter state updates and hides itself
+     * when it does not match the current input value.
+     *
+     * Set to false when you want to handle filtering yourself (e.g. async search,
+     * consumer-side pre-filtering). Options will not be registered for auto-filtering.
+     */
+    autoFilter?: boolean;
+}
+/**
+ * Set up a combobox with an input trigger (autocomplete/filter pattern).
+ *
+ * Creates a full combobox handle with the input-mode controller automatically
+ * wired in and the trigger registered. The consumer only needs to call
+ * `handle.registerListbox(listbox)`.
+ *
+ * Handles: Home/End (text cursor), ArrowLeft/Right (clear active descendant),
+ * filtering (on input and on open), and focus behavior.
+ *
+ * @param input     The input element to use as the combobox trigger.
+ * @param callbacks Callbacks for select and open/close events.
+ * @param options   Options for configuring the input-mode controller.
+ * @returns A ComboboxHandle for interacting with the combobox.
+ */
+export declare function setupComboboxInput(input: HTMLInputElement, callbacks: ComboboxCallbacks, options?: SetupComboboxInputOptions): ComboboxHandle;

package/js/components/Combobox/setupListbox.d.ts

@@ -0,0 +1,21 @@
+import { type FocusNavigationController } from '../../utils/focusNavigation';
+import type { ComboboxEventMap, ComboboxHandle } from './types';
+/**
+ * Set up focus navigation and delegated event listeners on a listbox element.
+ *
+ * This merges two concerns:
+ * 1. Creating the appropriate {@link FocusNavigationController} (grid or list mode)
+ *    with callbacks that manage `aria-activedescendant` and visual focus indicators.
+ * 2. Attaching delegated `click` and `mousedown` listeners to the listbox for
+ *    option selection and blur prevention.
+ *
+ * The caller is responsible for guarding against duplicate calls (i.e., checking
+ * that a focus navigation controller does not already exist before calling)
+ * and ensuring `handle.trigger` and `handle.listbox` are non-null.
+ *
+ * @param handle The combobox handle (provides trigger, listbox, select, etc.).
+ * @param signal Abort signal used to clean up all attached listeners.
+ * @param notify Notify subscribers of combobox events.
+ * @returns The created focus navigation controller.
+ */
+export declare function setupListbox(handle: ComboboxHandle, signal: AbortSignal, notify: <K extends keyof ComboboxEventMap>(event: K, value: ComboboxEventMap[K]) => void): FocusNavigationController;

package/js/components/Combobox/types.d.ts

@@ -0,0 +1,124 @@
+import type { FocusNavigationController } from '../../utils/focusNavigation';
+/** Section visibility state tracked per registration. */
+export interface SectionState {
+    hidden: boolean;
+    'aria-hidden': boolean;
+}
+/** Registration entry for a section element. */
+export interface SectionRegistration {
+    callback: (state: SectionState) => void;
+    last: SectionState;
+}
+/** Registration entry for an option element. */
+export interface OptionRegistration {
+    callback: (isFiltered: boolean) => void;
+    lastFiltered: boolean;
+}
+/** Map of combobox event names to their payload types. */
+export interface ComboboxEventMap {
+    /** Fired when the combobox open state changes. Payload: whether the combobox is open. */
+    open: boolean;
+    /** Fired when the active descendant changes (visual focus). Payload: the option id or null. */
+    activeDescendantChange: string | null;
+    /**
+     * Fired when the visible option count transitions between empty and non-empty.
+     * Payload: whether the list is empty plus the current input value.
+     */
+    emptyChange: {
+        isEmpty?: boolean;
+        inputValue?: string;
+    } | undefined;
+    /**
+     * Fired immediately when the aggregate loading state changes (skeleton count transitions
+     * between 0 and >0). Used for empty suppression in ComboboxState and for aria-busy on the listbox.
+     */
+    loadingChange: boolean;
+    /**
+     * Fired after a 500ms debounce when loading persists, or immediately when loading ends.
+     * Used to control the loading message text in the live region (ComboboxState).
+     */
+    loadingAnnouncement: boolean;
+}
+/** Callbacks provided by the consumer (React/Vue) to react to combobox state changes. */
+export interface ComboboxCallbacks {
+    /** Called when an option is selected (click or keyboard). */
+    onSelect(option: {
+        value: string;
+    }): void;
+}
+/** Handle returned by `setupCombobox`. Used by framework wrappers and mode controllers. */
+export interface ComboboxHandle {
+    /** Register the trigger element. Returns a cleanup function. */
+    registerTrigger(trigger: HTMLInputElement | HTMLButtonElement): () => void;
+    /** Register the listbox/grid element. Returns a cleanup function. */
+    registerListbox(listbox: HTMLElement): () => void;
+    /** Tear down all listeners and state. */
+    destroy(): void;
+    /** Subscribe to a combobox event. Returns an unsubscribe function. */
+    subscribe<K extends keyof ComboboxEventMap>(event: K, callback: (value: ComboboxEventMap[K]) => void): () => void;
+    /** The current trigger element (may be null before registration). */
+    readonly trigger: HTMLInputElement | HTMLButtonElement | null;
+    /** The current listbox/grid element (may be null before registration). */
+    readonly listbox: HTMLElement | null;
+    /** The focus navigation controller. */
+    readonly focusNav: FocusNavigationController | null;
+    /** Whether the popup is open. */
+    readonly isOpen: boolean;
+    /** Whether multi-select mode. */
+    readonly isMultiSelect: boolean;
+    /** Whether any skeleton placeholders are currently registered (loading). */
+    readonly isLoading: boolean;
+    /** Set the open state, update ARIA, fire callback. */
+    setIsOpen(isOpen: boolean): void;
+    /** Select an option (or null to clear), fire callback. */
+    select(option: HTMLElement | null): void;
+    /**
+     * Register an option DOM element for filter notifications.
+     * The element's textContent is used as the searchable text.
+     * The callback is invoked immediately with the current filter state,
+     * and again whenever the filter changes.
+     * Returns a cleanup function that unregisters the option.
+     */
+    registerOption(element: HTMLElement, onFilterChange: (isFiltered: boolean) => void): () => void;
+    /**
+     * Set the current filter value and notify all registered options of their match state.
+     * Options whose text does not start with the filter value are notified with isFiltered=true.
+     * An empty filter value clears filtering (all options become visible).
+     */
+    setFilter(filterValue: string): void;
+    /**
+     * Register a section DOM element for state notifications.
+     * The callback is invoked immediately with the current state, and again whenever
+     * the state changes after a filter update or option un/registration.
+     *
+     * - `hidden`: true when all registered options are filtered out (keeps children mounted
+     *   but invisible to the user and screen readers).
+     * - `aria-hidden`: true when the section has no registered options at all (skeleton-only).
+     *   The section stays visually rendered but is hidden from assistive technology —
+     *   the live region (`ComboboxState`) handles the loading announcement instead.
+     *
+     * At most one of `hidden` / `aria-hidden` is true at a time.
+     *
+     * Returns a cleanup function that unregisters the section.
+     */
+    registerSection(element: HTMLElement, onChange: (state: {
+        hidden: boolean;
+        'aria-hidden': boolean;
+    }) => void): () => void;
+    /**
+     * Register a skeleton placeholder. Increments the internal skeleton counter.
+     * When the counter transitions from 0 to >0, fires `loadingChange` immediately
+     * and schedules `loadingAnnouncement` after 500ms. Returns a cleanup function
+     * that decrements the counter (and fires the reverse transitions when reaching 0).
+     */
+    registerSkeleton(): () => void;
+}
+/**
+ * Callback invoked when the trigger is attached and the abort controller is ready.
+ *
+ * The callback can optionally return a mode-specific keydown hook. When returned,
+ * it is called before the shared keydown handler; return `true` to indicate the
+ * event was handled (the caller will call `stopPropagation`/`preventDefault`)
+ * and skip the shared logic.
+ */
+export type OnTriggerAttach = (handle: ComboboxHandle, signal: AbortSignal) => ((event: KeyboardEvent) => boolean) | void;

package/js/components/Combobox/utils.d.ts

@@ -0,0 +1,27 @@
+import type { FocusNavigationController } from '../../utils/focusNavigation';
+import type { OptionRegistration, SectionRegistration } from './types';
+/**
+ * Get the value for a combobox option element.
+ * Uses `data-value` when set; falls back to the element's trimmed `textContent`.
+ */
+export declare function getOptionValue(option: HTMLElement): string;
+/** Returns true when an option carries aria-disabled="true". */
+export declare function isOptionDisabled(option: HTMLElement): boolean;
+/** Returns true when the cell is NOT the first gridcell in its row (i.e., it's an action cell). */
+export declare function isActionCell(cell: HTMLElement): boolean;
+/** Predicate matching an option element that carries `aria-selected="true"`. */
+export declare const isSelected: (el: Element) => boolean;
+/** Navigate to the selected option, or to the first option if none is selected. */
+export declare function goToSelectedOrFirst(nav: FocusNavigationController): void;
+/** Navigate to the selected option, or to the last option if none is selected. */
+export declare function goToSelectedOrLast(nav: FocusNavigationController): void;
+/**
+ * Compute the current state of a section and notify when it changed.
+ *
+ * Section state:
+ * - `hidden`: true when the section has registered options but all are filtered out.
+ * - `aria-hidden`: true when the section has no registered options at all (skeleton-only).
+ *
+ * At most one of `hidden` / `aria-hidden` is true at a time.
+ */
+export declare function notifySection(sectionElement: HTMLElement, sectionRegistrations: Map<HTMLElement, SectionRegistration>, optionRegistrations: Map<HTMLElement, OptionRegistration>, force?: boolean): void;

package/js/components/List/ListItem.d.ts

@@ -0,0 +1,58 @@
+import { Size } from '../../constants';
+import type { CommonRef, GenericProps, HasAriaDisabled, HasClassName, JSXElement, LumxClassName } from '../../types';
+/** ListItem size variants. */
+export type ListItemSize = Extract<Size, 'tiny' | 'regular' | 'big' | 'huge'>;
+/**
+ * Defines the props of the component.
+ */
+export interface ListItemProps extends HasClassName, HasAriaDisabled {
+    /** A component to be rendered after the content. */
+    after?: JSXElement;
+    /** A component to be rendered before the content. */
+    before?: JSXElement;
+    /** Content. */
+    children?: JSXElement;
+    /** Whether the list item should be highlighted or not. */
+    isHighlighted?: boolean;
+    /** Whether the component is selected or not. */
+    isSelected?: boolean;
+    /** Whether link/button is disabled or not. */
+    isDisabled?: boolean;
+    /** Custom component for the link (can be used to inject router Link). */
+    linkAs?: 'a' | any;
+    /** Props that will be passed on to the Link. */
+    linkProps?: GenericProps;
+    /** Reference to the link element. */
+    linkRef?: CommonRef;
+    /** Size variant. */
+    size?: ListItemSize;
+    /** ref to the root <li> element */
+    ref?: CommonRef;
+    /** On click callback. */
+    handleClick?: (event: any) => void;
+}
+export type ListItemPropsToOverride = 'after' | 'before' | 'children' | 'handleClick';
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ListItem";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Component default props.
+ */
+export declare const DEFAULT_PROPS: Partial<ListItemProps>;
+/**
+ * ListItem component.
+ *
+ * @param  props Component props.
+ * @return JSX element.
+ */
+export declare const ListItem: {
+    (props: ListItemProps): import("react").JSX.Element;
+    displayName: string;
+    className: "lumx-list-item";
+    defaultProps: Partial<ListItemProps>;
+};

package/js/components/List/ListItemAction.d.ts

@@ -0,0 +1,24 @@
+import type { HasClassName } from '../../types';
+import { ClickableElement, RawClickableProps } from '../RawClickable';
+/**
+ * ListItemAction props.
+ */
+export type ListItemActionProps<E extends ClickableElement = 'button'> = RawClickableProps<E> & HasClassName;
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "ListItemAction";
+/**
+ * Component classname (used by action area CSS pattern).
+ */
+export declare const CLASSNAME = "lumx-action-area__action";
+export declare const DEFAULT_PROPS: Partial<ListItemActionProps>;
+/**
+ * ListItemAction component.
+ *
+ * Renders a button or link with action area classes.
+ * When placed as a child of ListItem, it activates the action area pattern:
+ * the entire list item becomes visually clickable, while other interactive
+ * elements (in `before`/`after` slots) remain independently clickable.
+ */
+export declare const ListItemAction: <E extends ClickableElement = "button">(props: ListItemActionProps<E>) => import("react").JSX.Element;

package/js/components/List/index.d.ts

@@ -0,0 +1,39 @@
+import { Size } from '../../constants';
+import type { CommonRef, HasClassName, JSXElement, LumxClassName } from '../../types';
+/** List item padding size. */
+export type ListItemPadding = Extract<Size, 'big' | 'huge'>;
+/**
+ * Defines the props of the component.
+ */
+export interface ListProps extends HasClassName {
+    /** List content (should be ListItem, ListDivider, etc.). */
+    children?: JSXElement;
+    /** Item padding size. */
+    itemPadding?: ListItemPadding;
+    /** ref to the root element */
+    ref?: CommonRef;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "List";
+/**
+ * Component default class name and class prefix.
+ */
+export declare const CLASSNAME: LumxClassName<typeof COMPONENT_NAME>;
+/**
+ * Component default props.
+ */
+export declare const DEFAULT_PROPS: Partial<ListProps>;
+/**
+ * List component.
+ *
+ * @param  props Component props.
+ * @return JSX element.
+ */
+export declare const List: {
+    (props: ListProps): import("react").JSX.Element;
+    displayName: string;
+    className: "lumx-list";
+    defaultProps: Partial<ListProps>;
+};

package/js/components/Tabs/Tests.d.ts

@@ -0,0 +1,11 @@
+import { SetupOptions } from '../../../testing';
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+export declare const setup: (propsOverride: any | undefined, { render, ...options }: SetupOptions<any>) => {
+    props: any;
+    tab: HTMLElement;
+    wrapper: Partial<import("../../../testing").SetupResult>;
+};
+declare const _default: (renderOptions: SetupOptions<any>) => void;
+export default _default;

package/js/components/Tabs/constants.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Component default class name and class prefix.
+ */
+export declare const TABS_CLASSNAME = "lumx-tabs";

package/js/components/Text/index.d.ts

@@ -69,7 +69,7 @@ export declare const DEFAULT_PROPS: {};
  * @param  props Component props.
  * @return Common Props
  */
-export declare const getTextProps: (props: TextProps) => {
+export declare const getTextProps: (props: Omit<TextProps, "as">) => {
     className: string;
     style: {
         accentColor?: import("csstype").Property.AccentColor | undefined;

package/js/components/UserBlock/Tests.d.ts

@@ -0,0 +1,13 @@
+import { SetupOptions } from '../../../testing';
+/**
+ * Mounts the component and returns common DOM elements / data needed in multiple tests further down.
+ */
+export declare const setup: (propsOverride: any | undefined, { render, ...options }: SetupOptions<any>) => {
+    props: any;
+    userBlock: HTMLElement;
+    fields: HTMLElement | null;
+    div: HTMLElement;
+    wrapper: Partial<import("../../../testing").SetupResult>;
+};
+declare const _default: (renderOptions: SetupOptions<any>) => void;
+export default _default;

package/js/types/jsx/PropsToOverride.d.ts

@@ -1,2 +1,2 @@
 /** list of generic props defined on JSX that need to be redefined for each framework */
-export type PropsToOverride = 'ref' | 'handleClick' | 'handleChange' | 'handleKeyPress' | 'handleClose' | 'handleBeforeClick' | 'handleAfterClick' | 'handleKeyDown';
+export type PropsToOverride = 'ref' | 'handleClick' | 'handleChange' | 'handleKeyPress' | 'handleClose' | 'handleFocus' | 'handleBeforeClick' | 'handleAfterClick' | 'handleMouseEnter' | 'handleMouseLeave' | 'handleKeyDown';

package/js/utils/browser/createSelectorTreeWalker.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Create a TreeWalker that iterates over elements matching a CSS selector
+ * within a container.
+ *
+ * Uses `NodeFilter.SHOW_ELEMENT` and accepts nodes that match the given
+ * selector, skipping everything else. The returned walker can be used with
+ * `nextNode()` / `previousNode()` for lazy, sequential DOM traversal.
+ *
+ * @param container The root element to walk within.
+ * @param selector CSS selector that items must match.
+ * @returns A TreeWalker scoped to the container and filtered by the selector.
+ */
+export declare function createSelectorTreeWalker(container: HTMLElement, selector: string): TreeWalker;

package/js/utils/focusNavigation/createActiveItemState.d.ts

@@ -0,0 +1,26 @@
+import type { FocusNavigationCallbacks } from './types';
+/**
+ * Internal state for tracking the active (focused) item.
+ * Shared by both list and grid navigation implementations.
+ */
+export interface ActiveItemState {
+    /** Get the currently active item. */
+    readonly active: HTMLElement | null;
+    /** Set the active item (handles deactivate/activate callbacks). */
+    setActive(item: HTMLElement | null): void;
+    /** Clear the active item (deactivate + clear callbacks). */
+    clear(): void;
+}
+/**
+ * Create shared active item state with cleanup on abort.
+ *
+ * Callback invocation:
+ * - `setActive(item)`: calls `onDeactivate(previous)` then `onActivate(item)`.
+ * - `clear()`: calls `onDeactivate(current)` then `onClear()`.
+ * - On `signal.abort()`: same as `clear()`.
+ *
+ * @param callbacks Focus state change callbacks.
+ * @param signal AbortSignal for cleanup.
+ * @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
+ */
+export declare function createActiveItemState(callbacks: FocusNavigationCallbacks, signal: AbortSignal, initialItem?: HTMLElement | null): ActiveItemState;

package/js/utils/focusNavigation/createGridFocusNavigation.d.ts

@@ -0,0 +1,13 @@
+import type { FocusNavigationCallbacks, FocusNavigationController, GridNavigationOptions } from './types';
+/**
+ * Create a focus navigation controller for a 2D grid.
+ *
+ * Supports Up/Down between rows (with column memory) and Left/Right between cells
+ * (with wrapping across rows).
+ *
+ * @param options Grid navigation options (container, rowSelector, cellSelector, isRowVisible, wrap).
+ * @param callbacks Callbacks for focus state changes.
+ * @param signal AbortSignal for cleanup.
+ * @returns FocusNavigationController instance.
+ */
+export declare function createGridFocusNavigation(options: GridNavigationOptions, callbacks: FocusNavigationCallbacks, signal: AbortSignal): FocusNavigationController;

package/js/utils/focusNavigation/createListFocusNavigation.d.ts

@@ -0,0 +1,10 @@
+import type { FocusNavigationCallbacks, FocusNavigationController, ListNavigationOptions } from './types';
+/**
+ * Create a focus navigation controller for a 1D list.
+ *
+ * @param options List navigation options (container, itemSelector, direction, wrap).
+ * @param callbacks Callbacks for focus state changes.
+ * @param signal AbortSignal for cleanup.
+ * @returns FocusNavigationController instance.
+ */
+export declare function createListFocusNavigation(options: ListNavigationOptions, callbacks: FocusNavigationCallbacks, signal: AbortSignal): FocusNavigationController;

package/js/utils/focusNavigation/index.d.ts

@@ -0,0 +1,5 @@
+export type { FocusNavigationCallbacks, FocusNavigationController, GridNavigationOptions, ListNavigationOptions, NavigationOptions, } from './types';
+export type { RovingTabIndexOptions } from './setupRovingTabIndex';
+export { createListFocusNavigation } from './createListFocusNavigation';
+export { createGridFocusNavigation } from './createGridFocusNavigation';
+export { setupRovingTabIndex } from './setupRovingTabIndex';

package/js/utils/focusNavigation/setupRovingTabIndex.d.ts

@@ -0,0 +1,42 @@
+import type { FocusNavigationController } from './types';
+/**
+ * Options for the roving tabindex setup.
+ */
+export interface RovingTabIndexOptions {
+    /** The container element holding the focusable items. */
+    container: HTMLElement;
+    /** CSS selector to identify focusable items within the container. */
+    itemSelector: string;
+    /**
+     * Primary navigation axis — determines which arrow keys navigate.
+     * - `'horizontal'` (default): Left/Right navigate, Up/Down are no-ops.
+     * - `'vertical'`: Up/Down navigate, Left/Right are no-ops.
+     */
+    direction?: 'horizontal' | 'vertical';
+    /**
+     * CSS selector matching disabled items within the container.
+     * Disabled items are skipped during keyboard navigation.
+     */
+    itemDisabledSelector?: string;
+    /** Callback invoked when an item receives focus via keyboard navigation. */
+    onItemFocused?: (item: HTMLElement) => void;
+}
+/**
+ * Set up the roving tabindex pattern on a container element.
+ *
+ * Handles:
+ * - Keyboard navigation (Arrow keys, Home, End) via a keydown listener on the container
+ * - tabindex management on focus changes (`0` on active, `-1` on inactive)
+ * - Calling `.focus()` on the newly active item
+ *
+ * The consumer is responsible for setting the initial tabindex values on items
+ * (`tabindex="0"` on the active item, `tabindex="-1"` on the rest). On setup, the item
+ * with `tabindex="0"` is silently adopted as the initial active item.
+ *
+ * The setup is torn down when the provided `signal` is aborted.
+ *
+ * @param options  Roving tabindex configuration.
+ * @param signal   AbortSignal for teardown.
+ * @returns The underlying {@link FocusNavigationController} for programmatic access.
+ */
+export declare function setupRovingTabIndex(options: RovingTabIndexOptions, signal: AbortSignal): FocusNavigationController;

package/js/utils/focusNavigation/types.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Callbacks for focus state changes.
+ * The consumer decides how to manifest focus (roving tabindex, aria-activedescendant, etc.).
+ */
+export interface FocusNavigationCallbacks {
+    /** Called when an item becomes the active (focused) item. */
+    onActivate(item: HTMLElement): void;
+    /** Called when an item is no longer the active item (being replaced or cleared). */
+    onDeactivate(item: HTMLElement): void;
+    /** Called when focus is completely cleared (no active item). */
+    onClear?(): void;
+}
+/** Options for 1D list navigation. */
+export interface ListNavigationOptions {
+    type: 'list';
+    /** The container element to scan for items. */
+    container: HTMLElement;
+    /** CSS selector to identify navigable items within the container. */
+    itemSelector: string;
+    /**
+     * Primary navigation axis — determines which arrow keys navigate the list.
+     * - `'vertical'` (default): Up/Down navigate, Left/Right are no-ops.
+     * - `'horizontal'`: Left/Right navigate, Up/Down are no-ops.
+     */
+    direction?: 'vertical' | 'horizontal';
+    /** Whether navigation wraps at boundaries (last→first, first→last). Default: false. */
+    wrap?: boolean;
+    /**
+     * CSS selector matching disabled items within the container.
+     * Disabled items are skipped during navigation (goUp/goDown/goLeft/goRight/goToFirst/goToLast)
+     * but can still be navigated to directly via `goToItem`.
+     * Default: no items are disabled.
+     */
+    itemDisabledSelector?: string;
+    /**
+     * CSS selector identifying the initially active item within the container.
+     * If an item matching this selector is found on setup, it becomes the active item
+     * without triggering focus or activation callbacks (silent init from DOM state).
+     */
+    itemActiveSelector?: string;
+}
+/** Options for 2D grid navigation. */
+export interface GridNavigationOptions {
+    type: 'grid';
+    /** The container element (grid root) to scan for rows and cells. */
+    container: HTMLElement;
+    /** CSS selector to identify row elements within the container. */
+    rowSelector: string;
+    /** CSS selector to identify cell elements within each row. */
+    cellSelector: string;
+    /**
+     * Predicate to determine if a row should be included in navigation.
+     * Rows for which this returns `false` are skipped.
+     * Default: all rows are visible.
+     */
+    isRowVisible?: (row: HTMLElement) => boolean;
+    /** Whether navigation wraps at boundaries. Default: false. */
+    wrap?: boolean;
+}
+/** Union of all navigation option types. */
+export type NavigationOptions = ListNavigationOptions | GridNavigationOptions;
+/** Focus navigation controller interface — works for both 1D lists and 2D grids. */
+export interface FocusNavigationController {
+    /** The navigation structure type. */
+    readonly type: 'list' | 'grid';
+    /** The currently active item, or null if no item is active. */
+    readonly activeItem: HTMLElement | null;
+    /** Whether an item is currently active. */
+    readonly hasActiveItem: boolean;
+    /** Whether there are any navigable items in the container. */
+    readonly hasNavigableItems: boolean;
+    /** Navigate to the first navigable item. */
+    goToFirst(): boolean;
+    /** Navigate to the last navigable item. */
+    goToLast(): boolean;
+    /**
+     * Navigate to a specific item element.
+     * @returns true if navigation occurred (item is navigable).
+     */
+    goToItem(item: HTMLElement): boolean;
+    /**
+     * Navigate by offset from the current item.
+     * In list mode, moves by items. In grid mode, moves by rows.
+     * Positive offsets move forward/down, negative move backward/up.
+     */
+    goToOffset(offset: number): boolean;
+    /**
+     * Navigate to the first item matching a predicate.
+     * @returns true if a matching item was found and focused.
+     */
+    goToItemMatching(predicate: (item: HTMLElement) => boolean): boolean;
+    /** Clear the active item — no item is active after this call. */
+    clear(): void;
+    /** Navigate up (previous item in vertical list, previous row in grid). */
+    goUp(): boolean;
+    /** Navigate down (next item in vertical list, next row in grid). */
+    goDown(): boolean;
+    /** Navigate left (previous item in horizontal list, previous cell in grid). */
+    goLeft(): boolean;
+    /** Navigate right (next item in horizontal list, next cell in grid). */
+    goRight(): boolean;
+}

package/js/utils/typeahead/index.d.ts

@@ -0,0 +1,29 @@
+/** Typeahead interface. */
+export interface Typeahead {
+    /**
+     * Handle a printable character keypress.
+     * @param key The character typed.
+     * @param currentItem The currently active item.
+     * @returns The matched item, or null.
+     */
+    handle(key: string, currentItem: HTMLElement | null): HTMLElement | null;
+    /** Reset the accumulated search string. */
+    reset(): void;
+}
+/**
+ * Create a typeahead controller for keyboard navigation in list-like widgets
+ * (combobox, menu, listbox, tree, etc.).
+ *
+ * Accumulates typed characters and matches them against item labels.
+ * Supports single-char cycling (e.g. pressing "a" repeatedly cycles through
+ * items starting with "a") and multi-char prefix matching.
+ *
+ * Uses a {@link TreeWalker} for lazy DOM traversal — items are visited one
+ * at a time without materializing the full list.
+ *
+ * @param getWalker Callback returning a fresh TreeWalker over navigable items, or null if unavailable.
+ * @param getItemValue Callback extracting the text label from an item element.
+ * @param signal AbortSignal for cleanup.
+ * @returns Typeahead instance.
+ */
+export declare function createTypeahead(getWalker: () => TreeWalker | null, getItemValue: (item: HTMLElement) => string, signal: AbortSignal): Typeahead;