@lumx/core 4.8.1 → 4.9.0-alpha.0

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/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,4 @@
+export type { FocusNavigationCallbacks, FocusNavigationController, ListNavigationOptions } from './types';
+export type { RovingTabIndexOptions } from './setupRovingTabIndex';
+export { createListFocusNavigation } from './createListFocusNavigation';
+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,81 @@
+/**
+ * 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;
+}
+/** Focus navigation controller interface for 1D lists. */
+export interface FocusNavigationController {
+    /** The navigation structure type. */
+    readonly type: 'list';
+    /** 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.
+     * Positive offsets move forward, negative move backward.
+     */
+    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). */
+    goUp(): boolean;
+    /** Navigate down (next item in vertical list). */
+    goDown(): boolean;
+    /** Navigate left (previous item in horizontal list). */
+    goLeft(): boolean;
+    /** Navigate right (next item in horizontal list). */
+    goRight(): boolean;
+}

package/package.json

@@ -7,7 +7,7 @@
     },
     "dependencies": {
         "@floating-ui/dom": "^1.7.5",
-        "@lumx/icons": "^4.8.1",
+        "@lumx/icons": "^4.9.0-alpha.0",
         "classnames": "^2.3.2",
         "focus-visible": "^5.0.2",
         "lodash": "4.17.23",
@@ -69,7 +69,7 @@
         "update-version-changelog": "yarn version-changelog ../../CHANGELOG.md"
     },
     "sideEffects": false,
-    "version": "4.8.1",
+    "version": "4.9.0-alpha.0",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@testing-library/dom": "^10.4.1",
@@ -92,5 +92,6 @@
         "vite": "^7.3.1",
         "vite-tsconfig-paths": "^5.1.4",
         "vitest": "^4.0.18"
-    }
+    },
+    "stableVersion": "4.8.1"
 }