@lumx/core 4.16.0-alpha.4 → 4.16.0-alpha.5

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

@@ -9,7 +9,7 @@ type RenderResult = {
  */
 export interface ComboboxOptionTestSetup {
     /** Combobox compound component namespace */
-    Combobox: Pick<ComboboxNamespace, 'Provider' | 'List' | 'Option'>;
+    Combobox: Pick<ComboboxNamespace, 'Provider' | 'Input' | 'List' | 'Option'>;
     /**
      * Render a JSX template and return a result with a container.
      * The template is a zero-argument function returning a JSX element.

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

@@ -17,42 +17,6 @@ export declare function setup({ components: { Combobox, IconButton, Button }, de
             };
         };
     };
-    AutoFilterOptions: {
-        play: ({ canvasElement }: any) => Promise<void>;
-        args: {
-            value: string;
-        };
-        decorators: ((story: any, context: any) => any)[];
-        render: ({ value, onChange, onSelect, }: {
-            value: string;
-            onChange: (v: string) => void;
-            onSelect?: (option: {
-                value: string;
-            }) => void;
-        }) => import("react").JSX.Element;
-    };
-    FilterOffOpenOnFocus: {
-        play: ({ canvasElement }: any) => Promise<void>;
-        args: {
-            value: string;
-        };
-        decorators: ((story: any, context: any) => any)[];
-        render: ({ value, onChange, onSelect }: any) => import("react").JSX.Element;
-    };
-    SelectOptionUpdatesInput: {
-        play: ({ canvasElement }: any) => Promise<void>;
-        args: {
-            value: string;
-        };
-        decorators: ((story: any, context: any) => any)[];
-        render: ({ value, onChange, onSelect, }: {
-            value: string;
-            onChange: (v: string) => void;
-            onSelect?: (option: {
-                value: string;
-            }) => void;
-        }) => import("react").JSX.Element;
-    };
     MouseHoverDoesNotActivateOption: {
         play: ({ canvasElement }: any) => Promise<void>;
         args: {
@@ -140,4 +104,69 @@ export declare function setup({ components: { Combobox, IconButton, Button }, de
             onToggle?: (isOpen: boolean) => void;
         }) => import("react").JSX.Element;
     };
+    ButtonTypeaheadFromClosed: {
+        play: ({ canvasElement }: any) => Promise<void>;
+        args: {
+            value: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onSelect }: {
+            value: string;
+            onSelect: (option: {
+                value: string;
+            }) => void;
+        }) => import("react").JSX.Element;
+    };
+    ButtonTypeaheadWhileOpen: {
+        play: ({ canvasElement }: any) => Promise<void>;
+        args: {
+            value: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onSelect }: {
+            value: string;
+            onSelect: (option: {
+                value: string;
+            }) => void;
+        }) => import("react").JSX.Element;
+    };
+    ButtonEndFromClosed: {
+        play: ({ canvasElement }: any) => Promise<void>;
+        args: {
+            value: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onSelect }: {
+            value: string;
+            onSelect: (option: {
+                value: string;
+            }) => void;
+        }) => import("react").JSX.Element;
+    };
+    ButtonHomeFromClosed: {
+        play: ({ canvasElement }: any) => Promise<void>;
+        args: {
+            value: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onSelect }: {
+            value: string;
+            onSelect: (option: {
+                value: string;
+            }) => void;
+        }) => import("react").JSX.Element;
+    };
+    ButtonArrowDownFromClosed: {
+        play: ({ canvasElement }: any) => Promise<void>;
+        args: {
+            value: string;
+        };
+        decorators: ((story: any, context: any) => any)[];
+        render: ({ value, onSelect }: {
+            value: string;
+            onSelect: (option: {
+                value: string;
+            }) => void;
+        }) => import("react").JSX.Element;
+    };
 };

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

@@ -39,6 +39,7 @@ export interface ComboboxTestSetup {
         valueExtract?: (v: any) => any;
     }) => RenderResult;
 }
+export declare function getActiveOption(): HTMLElement | null;
 /**
  * Create framework-agnostic JSX templates for combobox test fixtures.
  * Exported so TestStories.tsx can reuse the same templates for browser-only tests.

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

@@ -96,6 +96,13 @@ export interface ComboboxHandle {
     setIsOpen(isOpen: boolean): void;
     /** Select an option (or null to clear), fire callback. */
     select(option: HTMLElement | null): void;
+    /**
+     * Replay the pending navigation intent stored on the focus navigation controller via
+     * its `goTo` resolver. Called by the framework wrapper after the option children
+     * commit (keyboard opens from the closed state defer navigation until then). No-op
+     * when nothing is pending.
+     */
+    flushPendingNavigation(): void;
     /**
      * Register an option DOM element for filter notifications.
      * The element's textContent is used as the searchable text.

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

@@ -1,20 +1,23 @@
-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`.
+ *
+ * This is the *selection* value , which may differ from the visible label
  */
 export declare function getOptionValue(option: HTMLElement): string;
+/**
+ * Get the visible label for a combobox option element (its trimmed `textContent`).
+ *
+ * Used for typeahead matching: the user types the characters they see, which is the
+ * option's label — not its `data-value` (which can be an unrelated id).
+ */
+export declare function getOptionLabel(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.
  *

package/js/components/SelectButton/TestStories.d.ts

@@ -34,4 +34,12 @@ export declare function setup({ components: { SelectButton }, renderWithState, }
     WithInfiniteScroll: {
         play({ canvasElement }: any): Promise<void>;
     };
+    TypeaheadWhileOpen: {
+        render: () => any;
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
+    TypeaheadFromClosed: {
+        render: () => any;
+        play: ({ canvasElement }: any) => Promise<void>;
+    };
 };

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

@@ -0,0 +1,2 @@
+/** Deepest last-child descendant of `el` (or `el` itself if it has no children). */
+export declare function lastDescendant(element: HTMLElement): HTMLElement;

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

@@ -2,6 +2,12 @@ import type { FocusNavigationCallbacks, FocusNavigationController, GridNavigatio
 /**
  * Create a focus navigation controller for a 2D grid.
  *
+ * The controller is composed of two layers:
+ * - a pure, side-effect-free **selection** layer ({@link createGridSelectors}) that only
+ *   resolves/reports rows and cells by querying the DOM, and
+ * - a **mover** layer (this function) that commits focus by updating the active-item state
+ *   (which fires {@link FocusNavigationCallbacks}) on top of the selectors.
+ *
  * Supports Up/Down between rows (with column memory) and Left/Right between cells
  * (with wrapping across rows).
  *

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

@@ -0,0 +1,25 @@
+import type { FocusNavigationSelectors, GridNavigationOptions } from './types';
+/**
+ * Create the pure selection layer for a 2D grid.
+ *
+ * Everything here is side-effect-free: it only *queries* the DOM to resolve and report
+ * rows/cells. No focus is moved and no {@link FocusNavigationCallbacks} are invoked — that
+ * is the job of the mover layer built on top of this.
+ *
+ * @param options Grid navigation options (container, rowSelector, cellSelector).
+ * @param getActive Reader for the currently active cell (owned by the mover's active-item state).
+ * @param isVisible Predicate deciding whether a row is visible (derived from `isRowVisible`).
+ * @returns The public {@link FocusNavigationSelectors} plus the internal
+ *   {@link GridSelectorHelpers} the mover layer consumes.
+ */
+export declare function createGridSelectors(options: GridNavigationOptions, getActive: () => HTMLElement | null, isVisible: (row: HTMLElement) => boolean): {
+    selectors: FocusNavigationSelectors;
+    helpers: {
+        findFirstVisibleRow: () => HTMLElement | null;
+        findLastVisibleRow: () => HTMLElement | null;
+        findAllVisibleRows: () => HTMLElement[];
+        getRowCells: (row: HTMLElement) => HTMLElement[];
+        findParentRow: (cell: HTMLElement) => HTMLElement | null;
+        findAdjacentVisibleRow: (fromRow: HTMLElement, direction: "next" | "prev") => HTMLElement | null;
+    };
+};

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

@@ -2,6 +2,12 @@ import type { FocusNavigationCallbacks, ListFocusNavigationController, ListNavig
 /**
  * Create a focus navigation controller for a 1D list.
  *
+ * The controller is composed of two layers:
+ * - a pure, side-effect-free **selection** layer ({@link createListSelectors}) that only
+ *   resolves/reports items by querying the DOM, and
+ * - a **mover** layer (this function) that commits focus by calling
+ *   {@link FocusNavigationCallbacks} on top of the selectors.
+ *
  * This controller is **stateless** — it does not maintain an internal reference to
  * the active item. Instead it reads the active item from the DOM each time via the
  * `getActiveItem` callback provided in the options. This avoids any desync between

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

@@ -0,0 +1,21 @@
+import type { ListFocusNavigationSelectors, ListNavigationOptions } from './types';
+/**
+ * Create the pure selection layer for a 1D list.
+ *
+ * Everything here is side-effect-free: it only *queries* the DOM to resolve and report
+ * items. No focus is moved and no {@link FocusNavigationCallbacks} are invoked — that is
+ * the job of the mover layer built on top of this (`createListFocusNavigation`).
+ *
+ * @param options List navigation options (container, itemSelector, itemDisabledSelector, getActiveItem).
+ * @returns The public {@link ListFocusNavigationSelectors} plus the internal
+ *   {@link ListSelectorHelpers} the mover layer consumes.
+ */
+export declare function createListSelectors(options: ListNavigationOptions): {
+    selectors: ListFocusNavigationSelectors;
+    helpers: {
+        createItemWalker: (enabledOnly?: boolean) => TreeWalker;
+        findFirstEnabled: () => HTMLElement | null;
+        findLastEnabled: () => HTMLElement | null;
+        getActiveItem: () => HTMLElement | null;
+    };
+};

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

@@ -0,0 +1,7 @@
+/** Create a pending navigation store; discards intent on abort. */
+export declare function createPendingNavigation(signal: AbortSignal): {
+    readonly hasPending: boolean;
+    defer(navigate: () => boolean): void;
+    flush(): void;
+    clear: () => void;
+};

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

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

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

@@ -1,126 +1,70 @@
-/**
- * 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;
-    /**
-     * Callback returning the currently active item from the DOM.
-     *
-     * The list navigation controller does **not** maintain an internal active-item
-     * reference; instead it delegates to this callback every time it needs the current
-     * active item (e.g. before navigating by offset).
-     *
-     * The callback is expected to read from the DOM (e.g. query `[tabindex="0"]` for
-     * roving tabindex, or read `aria-activedescendant` for combobox patterns).
-     *
-     * Default: `() => null` (no active item).
-     */
     getActiveItem?: () => HTMLElement | null;
 }
-/** 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. */
+/** Pure, side-effect-free selection layer for focus navigation. */
+export interface FocusNavigationSelectors {
     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).
-     */
+    getFirst(): HTMLElement | null;
+    getLast(): HTMLElement | null;
+    getMatching(predicate: (item: HTMLElement) => boolean): HTMLElement | null;
+}
+/**
+ * List-specific selection layer.
+ * Adds {@link findNearestEnabled} and the combined enabled-item selector string.
+ */
+export interface ListFocusNavigationSelectors extends FocusNavigationSelectors {
+    readonly enabledItemSelector: string;
+    findNearestEnabled(anchor: Node): HTMLElement | null;
+}
+/**
+ * Focus navigation controller — the mover layer. Every method commits focus via
+ * {@link FocusNavigationCallbacks}. The pure read layer lives behind {@link selectors}.
+ *
+ * To move focus to the first/last navigable item:
+ * `goTo((s) => s.getFirst())` / `goTo((s) => s.getLast())`.
+ */
+export interface FocusNavigationController<Selectors extends FocusNavigationSelectors = FocusNavigationSelectors> {
+    readonly type: 'list' | 'grid';
+    readonly selectors: Selectors;
     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;
-}
-/**
- * Extended controller for 1D list navigation.
- * Adds list-specific methods that don't apply to grid navigation.
- */
-export interface ListFocusNavigationController extends FocusNavigationController {
-    /** Combined CSS selector matching enabled (non-disabled) items. */
-    readonly enabledItemSelector: string;
     /**
-     * Find the nearest enabled item to the given anchor node.
-     * The anchor does not need to be an item or even an HTMLElement — it's used
-     * as a positional reference to find the closest enabled item in DOM order.
-     * Prefers the next item; falls back to the previous item.
-     *
-     * @returns The nearest enabled item, or null if no enabled items exist.
+     * Navigate via a resolver, deferring when the target is not yet in the DOM.
+     * ```ts
+     * nav.goTo((sel) => sel.getMatching(isSelected) ?? sel.getFirst());
+     * ```
      */
-    findNearestEnabled(anchor: Node): HTMLElement | null;
+    goTo(resolve: (selectors: Selectors) => HTMLElement | null): boolean;
+    /**
+     * Replay the pending navigation intent stored by {@link goTo}.
+     * No-op when nothing is pending.
+     */
+    flushPendingNavigation(): void;
+}
+export interface ListFocusNavigationController extends FocusNavigationController<ListFocusNavigationSelectors> {
 }

package/js/utils/iterable/first.d.ts

@@ -0,0 +1,2 @@
+/** Return the first item of an iterable, or `null` if it is empty. */
+export declare function first<T>(iterable: Iterable<T>): T | null;

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

@@ -7,6 +7,14 @@ export interface Typeahead {
      * @returns The matched item, or null.
      */
     handle(key: string, currentItem: HTMLElement | null): HTMLElement | null;
+    /**
+     * Re-run the match for the *current* accumulated search string against the
+     * live DOM, without appending a new character or resetting the timeout.
+
+     * @param currentItem The currently active item.
+     * @returns The matched item, or null.
+     */
+    rematch(currentItem: HTMLElement | null): HTMLElement | null;
     /** Reset the accumulated search string. */
     reset(): void;
 }

package/package.json

@@ -7,7 +7,7 @@
     },
     "dependencies": {
         "@floating-ui/dom": "^1.7.5",
-        "@lumx/icons": "^4.16.0-alpha.4",
+        "@lumx/icons": "^4.16.0-alpha.5",
         "classnames": "^2.3.2",
         "focus-visible": "^5.0.2",
         "lodash": "4.18.1",
@@ -69,7 +69,7 @@
         "update-version-changelog": "yarn version-changelog ../../CHANGELOG.md"
     },
     "sideEffects": false,
-    "version": "4.16.0-alpha.4",
+    "version": "4.16.0-alpha.5",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@testing-library/dom": "^10.4.1",