@lumx/core 4.9.0-next.1 → 4.9.0-next.10

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

@@ -0,0 +1,24 @@
+import type { ComboboxCallbacks, ComboboxHandle, OnTriggerAttach } from './types';
+/** Options for configuring the shared combobox behavior. */
+interface ComboboxOptions {
+    /** When true, ArrowDown/ArrowUp wrap around in listbox mode (input pattern). Default: false. */
+    wrapNavigation?: boolean;
+}
+/**
+ * Set up combobox behavior (WAI-ARIA combobox pattern) on a trigger + listbox pair.
+ *
+ * The trigger and listbox are registered separately via the returned handle,
+ * allowing framework components to register them on mount. The behavior is
+ * fully attached once both are registered.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+ *
+ * @param callbacks Callbacks invoked on combobox events (e.g. option selection).
+ * @param options Options for configuring the shared combobox behavior.
+ * @param onTriggerAttach Optional callback invoked when the trigger is registered and the signal is ready.
+ *                        Used by mode-specific wrappers (setupComboboxInput/Button) to automatically
+ *                        attach the appropriate controller.
+ * @returns A ComboboxHandle for interacting with the combobox.
+ */
+export declare function setupCombobox(callbacks: ComboboxCallbacks, options?: ComboboxOptions, onTriggerAttach?: OnTriggerAttach): ComboboxHandle;
+export {};

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,28 @@
+import type { ComboboxCallbacks, ComboboxHandle } from './types';
+/** Options for configuring the input-mode combobox controller. */
+export interface SetupComboboxInputOptions extends ComboboxCallbacks {
+    /**
+     * 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 options Options and callbacks for configuring the input-mode controller.
+ * @returns A ComboboxHandle for interacting with the combobox.
+ */
+export declare function setupComboboxInput(input: HTMLInputElement, 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/subscribeComboboxState.d.ts

@@ -0,0 +1,23 @@
+import type { ComboboxHandle } from './types';
+/** Setters invoked by `subscribeComboboxState` when handle events fire. */
+export interface ComboboxStateSetters {
+    /** Called immediately with the current loading state, then on every `loadingChange` event. */
+    setIsLoading: (value: boolean) => void;
+    /** Called on every `loadingAnnouncement` event (debounced 500ms after skeletons mount). */
+    setShouldAnnounce: (value: boolean) => void;
+    /** Called with `true` after a short delay when the combobox opens, and `false` immediately on close. */
+    setIsOpen: (value: boolean) => void;
+}
+/**
+ * Subscribe to the combobox handle events needed by `ComboboxState`.
+ *
+ * Manages three subscriptions:
+ * - `loadingChange` → `setIsLoading` (+ synchronous initial read of `handle.isLoading`)
+ * - `loadingAnnouncement` → `setShouldAnnounce`
+ * - `open` → `setIsOpen` (deferred by {@link OPEN_ANNOUNCEMENT_DELAY}ms on open, immediate on close)
+ *
+ * @param handle  The combobox handle to subscribe to.
+ * @param setters Framework-specific state setters.
+ * @returns A cleanup function that unsubscribes all events and clears timers.
+ */
+export declare function subscribeComboboxState(handle: ComboboxHandle, setters: ComboboxStateSetters): () => void;

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). Receives the combobox handle for post-selection side effects. */
+    onSelect(option: {
+        value: string;
+    }, handle: ComboboxHandle): 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/Mosaic/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;
+    mosaic: HTMLElement;
+    thumbnails: HTMLElement[];
+    overlay: HTMLElement | null;
+    wrapper: Partial<import("../../../testing").SetupResult>;
+};
+declare const _default: (renderOptions: SetupOptions<any>) => void;
+export default _default;

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

@@ -0,0 +1,39 @@
+import { Alignment } from '../../constants';
+import { CommonRef, HasClassName, HasTheme, JSXElement } from '../../types';
+export declare enum TabListLayout {
+    clustered = "clustered",
+    fixed = "fixed"
+}
+/**
+ * Defines the props of the component.
+ */
+export interface TabListProps extends HasClassName, HasTheme {
+    /** ARIA label (purpose of the set of tabs). */
+    ['aria-label']: string;
+    /** Tab list. */
+    children: JSXElement;
+    /** Layout of the tabs in the list. */
+    layout?: TabListLayout;
+    /** Position of the tabs in the list (requires 'clustered' layout). */
+    position?: Alignment;
+    /** ref to the wrapper element */
+    ref?: CommonRef;
+}
+/**
+ * Component display name.
+ */
+export declare const COMPONENT_NAME = "TabList";
+/**
+ * Component default props.
+ */
+export declare const DEFAULT_PROPS: Partial<TabListProps>;
+/**
+ * TabList component.
+ *
+ * Implements WAI-ARIA `tablist` role {@see https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html#rps_label}
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export declare const TabList: (props: TabListProps) => import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+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;
+    tabList: HTMLElement;
+    links: HTMLElement | null;
+    wrapper: Partial<import("../../../testing").SetupResult>;
+};
+declare const _default: (renderOptions: SetupOptions<any>) => void;
+export default _default;

package/js/components/Tabs/TabPanelTests.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;
+    tabPanel: HTMLElement;
+    wrapper: Partial<import("../../../testing").SetupResult>;
+};
+declare const _default: (renderOptions: SetupOptions<any>) => void;
+export default _default;

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

@@ -0,0 +1,17 @@
+/**
+ * Test util module. Do not import in production code!
+ */
+export declare const createTabTestUtils: ({ screen, within }: {
+    screen: any;
+    within: any;
+}) => {
+    query: {
+        tabList: (name: string) => any;
+        tabs: (tabList?: any) => any;
+        tab: (name: string, tabList?: any) => any;
+        tabPanel: (name: string) => any;
+    };
+    checkTabActive: (activeTabName: string, { isLazy }?: {
+        isLazy?: boolean | undefined;
+    }) => void;
+};

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/Tabs/state.d.ts

@@ -0,0 +1,34 @@
+export type TabType = 'tab' | 'tabPanel';
+export interface State {
+    isLazy: boolean;
+    shouldActivateOnFocus: boolean;
+    activeTabIndex: number;
+    ids: Record<TabType, string[]>;
+}
+export declare const INIT_STATE: State;
+export type Action = {
+    type: 'update';
+    payload: Partial<State>;
+} | {
+    type: 'setActiveTabIndex';
+    payload: number;
+} | {
+    type: 'register';
+    payload: {
+        type: TabType;
+        id: string;
+    };
+} | {
+    type: 'unregister';
+    payload: {
+        type: TabType;
+        id: string;
+    };
+};
+export declare const reducer: (state: State, action: Action) => State;
+export type TabState = Pick<Required<State>, 'isLazy' | 'shouldActivateOnFocus'> & {
+    isActive: boolean;
+    tabId: string;
+    tabPanelId: string;
+    changeToTab(): void;
+};

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/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/index.d.ts

@@ -1,4 +1,5 @@
-export type { FocusNavigationCallbacks, FocusNavigationController, ListNavigationOptions } from './types';
+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';