@lumx/core 4.12.0 → 4.12.1-alpha.0

package/js/components/Chip/SelectionChipGroupTests.d.ts

@@ -10,9 +10,14 @@ export declare const setup: (propsOverride: any | undefined, { render, ...option
 interface CoreTestOptions extends SetupOptions<any> {
     /**
      * Render a stateful SelectionChipGroup that updates its own value on change.
-     * When provided, enables roving tabindex recovery tests.
+     * Should also render a sibling `<input>` element wired via `inputRef` so the
+     * keyboard navigation tests can assert focus fallback to the input.
+     *
+     * When provided, enables roving tabindex recovery and keyboard navigation tests.
+     *
+     * @param initialValue Optional initial value (defaults to all 3 testOptions).
      */
-    renderStateful?: () => void;
+    renderStateful?: (initialValue?: any[]) => void;
 }
 declare const _default: (renderOptions: CoreTestOptions) => void;
 export default _default;

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

@@ -1,4 +1,5 @@
 import type { CommonRef, HasClassName, LumxClassName } from '../../types';
+import type { ComboboxCallbacks } from './types';
 /**
  * Label display mode for the ComboboxButton.
  * - `'show-selection'`: Show the selected value if available, otherwise the label.
@@ -9,7 +10,7 @@ export type ComboboxButtonLabelDisplayMode = 'show-selection' | 'show-label' | '
 /**
  * Defines the props for the core ComboboxButton template.
  */
-export interface ComboboxButtonProps extends HasClassName {
+export interface ComboboxButtonProps extends HasClassName, ComboboxCallbacks {
     /** The label for the button (used for ARIA and tooltip). */
     label: string;
     /** The currently selected value to display. */

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

@@ -1,8 +1,9 @@
 import type { CommonRef, HasClassName, HasTheme, LumxClassName } from '../../types';
+import type { ComboboxCallbacks, ComboboxInputOptions } from './types';
 /**
  * Defines the props for the core ComboboxInput template.
  */
-export interface ComboboxInputProps extends HasClassName, HasTheme {
+export interface ComboboxInputProps extends HasClassName, HasTheme, ComboboxCallbacks, ComboboxInputOptions {
     /** The ID of the listbox element (for aria-controls). */
     listboxId?: string;
     /** Whether the combobox is open. */
@@ -17,12 +18,14 @@ export interface ComboboxInputProps extends HasClassName, HasTheme {
     toggleButtonProps?: Record<string, any>;
     /** Toggle callback for the chevron button. */
     handleToggle?(): void;
-    /**
-     * Controls how the combobox filters options as the user types.
-     * When `'off'`, the input is rendered as `readOnly`.
-     */
-    filter?: 'auto' | 'manual' | 'off';
 }
+/**
+ * Props from the core `ComboboxInputProps` that framework wrappers (React/Vue)
+ * are expected to provide internally or re-type with framework-specific equivalents
+ * (e.g. React refs, framework-specific button props). Wrappers should omit these
+ * keys when exposing the core props to consumers.
+ */
+export type ComboboxInputPropsToOverride = 'listboxId' | 'isOpen' | 'inputRef' | 'textFieldRef' | 'toggleButtonProps' | 'handleToggle';
 /**
  * Injected framework-specific components for ComboboxInput rendering.
  */

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

@@ -1,23 +1,6 @@
-import type { ComboboxCallbacks, ComboboxHandle } from './types';
+import type { ComboboxCallbacks, ComboboxHandle, ComboboxInputOptions } from './types';
 /** Options for configuring the input-mode combobox controller. */
-export interface SetupComboboxInputOptions extends ComboboxCallbacks {
-    /**
-     * Controls how the combobox filters options as the user types.
-     *
-     * - `'auto'` (default) — Options are automatically filtered client-side.
-     * - `'manual'` — Filtering is the consumer's responsibility.
-     * - `'off'` — Like `'manual'`, and `openOnFocus` defaults to `true`.
-     *   The core template renders the input as `readOnly`.
-     */
-    filter?: 'auto' | 'manual' | 'off';
-    /**
-     * When true, the combobox opens automatically when the input receives focus.
-     * When false (default, unless `filter` is `'off'`), the combobox only opens
-     * on click, typing, or keyboard navigation.
-     *
-     * @default false (true when filter is 'off')
-     */
-    openOnFocus?: boolean;
+export interface SetupComboboxInputOptions extends ComboboxCallbacks, ComboboxInputOptions {
 }
 /**
  * Set up a combobox with an input trigger (autocomplete/filter pattern).

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

@@ -41,10 +41,34 @@ export interface ComboboxEventMap {
 }
 /** 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: {
+    /** Called when an option is selected (click or keyboard). */
+    onSelect?(option: {
         value: string;
-    }, handle: ComboboxHandle): void;
+    }): void;
+}
+/**
+ * Behavioral options for input-mode combobox (autocomplete/filter pattern).
+ * Shared between the core JSX template props (`ComboboxInputProps`) and the
+ * runtime controller options (`SetupComboboxInputOptions`).
+ */
+export interface ComboboxInputOptions {
+    /**
+     * Controls how the combobox filters options as the user types.
+     *
+     * - `'auto'` (default) — Options are automatically filtered client-side.
+     * - `'manual'` — Filtering is the consumer's responsibility.
+     * - `'off'` — Like `'manual'`, but the input is rendered as `readOnly`
+     *   and `openOnFocus` defaults to `true`.
+     */
+    filter?: 'auto' | 'manual' | 'off';
+    /**
+     * When true, the combobox opens automatically when the input receives focus.
+     * When false (default, unless `filter` is `'off'`), the combobox only opens
+     * on click, typing, or keyboard navigation.
+     *
+     * @default false (true when filter is 'off')
+     */
+    openOnFocus?: boolean;
 }
 /** Handle returned by `setupCombobox`. Used by framework wrappers and mode controllers. */
 export interface ComboboxHandle {

package/js/utils/focus/constants.d.ts

@@ -1,4 +1,10 @@
 /** CSS selector listing all tabbable elements. */
 export declare const TABBABLE_ELEMENTS_SELECTOR = "a[href], button, textarea, input:not([type=\"hidden\"]):not([hidden]), [tabindex]";
-/** CSS selector matching element that are disabled (should not receive focus). */
-export declare const DISABLED_SELECTOR = "[hidden], [tabindex=\"-1\"], [disabled]:not([disabled=\"false\"]), [aria-disabled]:not([aria-disabled=\"false\"])";
+/**
+ * CSS selector matching elements that should be excluded from focus traversal.
+ *
+ * Note: `aria-disabled` is intentionally NOT in this list — per ARIA semantics, an `aria-disabled` element
+ * remains focusable (and discoverable by assistive tech). To remove an element from the tab order, use
+ * `tabindex="-1"` instead.
+ */
+export declare const DISABLED_SELECTOR = "[hidden], [tabindex=\"-1\"], [disabled]:not([disabled=\"false\"])";

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

@@ -1,3 +1,4 @@
 export { getFirstAndLastFocusable } from './getFirstAndLastFocusable';
 export { getFocusableElements } from './getFocusableElements';
+export { setupFocusTrap, type SetupFocusTrapOptions } from './setupFocusTrap';
 export { TABBABLE_ELEMENTS_SELECTOR, DISABLED_SELECTOR } from './constants';

package/js/utils/focus/setupFocusTrap.d.ts

@@ -0,0 +1,28 @@
+export interface SetupFocusTrapOptions {
+    /** The element in which to trap the focus. */
+    focusZoneElement: HTMLElement;
+    /**
+     * The element to focus when the trap is activated.
+     * Falls back to the first focusable element inside the zone, then to the zone element itself.
+     */
+    focusElement?: HTMLElement | null;
+}
+/**
+ * Trap 'Tab' focus switch inside the `focusZoneElement`.
+ *
+ * Setup behavior:
+ * 1. Focus `focusElement` if provided and contained in the zone.
+ * 2. Otherwise focus the first focusable descendant.
+ * 3. Otherwise focus the zone element itself (falling back to setting `tabindex="-1"` if needed) so that
+ *    keyboard users (especially screen reader users) land inside the trapped region (e.g. an empty dialog).
+ *
+ * Tab key behavior:
+ * - With at least one focusable descendant: focus cycles between the first and last focusable in the zone.
+ * - With no focusable descendant: Tab is swallowed and focus is restored to the zone element itself.
+ *
+ * Multiple traps stack — only the latest one is active; previous traps re-enable when the latest is torn down.
+ *
+ * @param options Trap configuration.
+ * @param signal  AbortSignal used to tear down the trap.
+ */
+export declare function setupFocusTrap(options: SetupFocusTrapOptions, signal: AbortSignal): void;

package/package.json

@@ -7,7 +7,7 @@
     },
     "dependencies": {
         "@floating-ui/dom": "^1.7.5",
-        "@lumx/icons": "^4.12.0",
+        "@lumx/icons": "^4.12.1-alpha.0",
         "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.12.0",
+    "version": "4.12.1-alpha.0",
     "devDependencies": {
         "@rollup/plugin-typescript": "^12.3.0",
         "@testing-library/dom": "^10.4.1",
@@ -92,5 +92,6 @@
         "vite": "^7.3.2",
         "vite-tsconfig-paths": "^5.1.4",
         "vitest": "^4.0.18"
-    }
+    },
+    "stableVersion": "4.12.0"
 }