@lumx/react 4.0.1-alpha.8 → 4.1.0

package/package.json

@@ -6,8 +6,8 @@
         "url": "https://github.com/lumapps/design-system/issues"
     },
     "dependencies": {
-        "@lumx/core": "^4.0.1-alpha.8",
-        "@lumx/icons": "^4.0.1-alpha.8",
+        "@lumx/core": "^4.1.0",
+        "@lumx/icons": "^4.1.0",
         "@popperjs/core": "^2.5.4",
         "body-scroll-lock": "^3.1.5",
         "react-popper": "^2.2.4"
@@ -41,7 +41,7 @@
         "focus-visible": "^5.0.2",
         "glob": "^7.1.6",
         "jsdom": "^27.2.0",
-        "lodash": "4.17.21",
+        "lodash": "4.17.23",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "rollup": "^4.53.3",
@@ -58,7 +58,7 @@
         "vitest": "^3.0.0"
     },
     "peerDependencies": {
-        "lodash": "4.17.21",
+        "lodash": "4.17.23",
         "react": ">= 17.0.2",
         "react-dom": ">= 17.0.2"
     },
@@ -90,5 +90,5 @@
         "build:storybook": "storybook build"
     },
     "sideEffects": false,
-    "version": "4.0.1-alpha.8"
+    "version": "4.1.0"
 }

package/utils/index.d.ts

@@ -1,6 +1,7 @@
 import React__default, { RefObject } from 'react';
 import { Falsy } from '@lumx/core/js/types';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ObjectValues } from '@lumx/core/src/js/types/ObjectValues';
 
 interface ClickAwayParameters {
     /**
@@ -78,5 +79,266 @@ declare function DisabledStateProvider({ children, ...value }: DisabledStateProv
  */
 declare function useDisabledStateContext(): DisabledStateContextValue;
 
-export { ClickAwayProvider, DisabledStateProvider, Portal, PortalProvider, useDisabledStateContext };
+declare const LOOP_AROUND_TYPES: {
+    /**
+     * Will continue navigation to the next row or column and loop back to the start
+     * when the last tab stop is reached
+     */
+    readonly nextLoop: "next-loop";
+    /**
+     * Will continue navigation to the next row or column until
+     * the last tab stop is reached
+     */
+    readonly nextEnd: "next-end";
+    /**
+     * Will loop within the current row or column
+     */
+    readonly inside: "inside";
+};
+
+/**
+ * Base hook options
+ */
+type BaseHookOptions = [
+    /**
+     * The DOM element to include.
+     * This must be the same DOM element for the lifetime of the containing component.
+     */
+    ref: React.RefObject<Element>,
+    /**
+     * Whether or not the DOM element is currently enabled. This value can be updated as appropriate throughout the
+     * lifetime of the containing component.
+     */
+    disabled?: boolean,
+    /**
+     * An optional string value that must be populated if the roving tabindex is being used in a grid. In that case,
+     * set it to a unique key for all tabStops part of the same row that the given DOM element is currently part of. You can update this
+     * row key as appropriate throughout the lifetime of the containing component, for example if the shape of the
+     * grid can change dynamically.
+     */
+    rowKey?: string | number | null,
+    /** Whether the tab stop should be set as selected by default  */
+    autofocus?: boolean
+];
+type KeyDirection = 'horizontal' | 'vertical' | 'both';
+type LoopTypes = ObjectValues<typeof LOOP_AROUND_TYPES>;
+/**
+ * The behavior to set when the end of a column or row is reached
+ */
+type LoopAroundByAxis = {
+    col: LoopTypes;
+    row: LoopTypes;
+};
+/**
+ * The LoopAround behavior to have.
+ * Can be a boolean as a shortcut
+ *
+ * * true => { row: 'next-loop', col: 'next-loop' }
+ * * false => { row: 'next-end', col: 'next-end' }
+ */
+type LoopAround = LoopAroundByAxis | boolean;
+interface MovingFocusOptions {
+    /**
+     * An optional direction value that only applies when the roving tabindex is not being  used within a grid.
+     * This value specifies the arrow key behaviour.
+     * The default value is 'horizontal'.
+     * When set to 'horizontal' then only the ArrowLeft and ArrowRight keys move to the previous and next tab stop
+     * respectively.
+     * When set to 'vertical' then only the ArrowUp and ArrowDown keys move to the previous and next tab stop
+     * respectively.
+     * When set to 'both' then both the ArrowLeft and ArrowUp keys can be used to move to the previous tab stop, and
+     * both the ArrowRight and ArrowDown keys can be used to move to the next tab stop.
+     * If you do not pass an explicit value then the 'horizontal' behaviour applies.
+     */
+    direction: KeyDirection;
+    /**
+     * Direction in which initial virtual focus must be set focused on the virtual focus parent.
+     * Ex: With `firstFocusDirection: vertical`, pressing "left" and "right" arrows while virtual focus is
+     * not enabled yet will do nothing.
+     * /!\ Only used with `virtualFocus` hooks.
+     */
+    firstFocusDirection?: KeyDirection;
+    /**
+     * An optional flag that, when set to `true`, will loop the tabindex around when the user  tries to tab to the
+     * first or last elements in the roving tabindex, rather than stopping.
+     * The default value is `false` (no looping).
+     * Note that this option does not apply if the roving tabindex is being used on a grid.
+     */
+    loopAround: LoopAround;
+    /**
+     * Id of the tab stop should accept focus if selectedId is undefined.
+     */
+    defaultSelectedId: string | null;
+    /**
+     * Autofocus first or last item after the list/grid is mounted.
+     */
+    autofocus?: 'first' | 'last';
+    /**
+     * The axis on which the "skip" shortcuts (home / end) must function.
+     */
+    gridJumpToShortcutDirection?: 'vertical' | 'horizontal';
+    /**
+     * Enable default selected item focusing
+     *
+     * Note: The `allowFocusing` state property is set at "false" by default until an interaction is made.
+     * This is required to delay focusing of the selected tab stop DOM element
+     * until the user has started interacting with the roving tabindex's controls.
+     * If this delay did not occur, the selected control would be focused as soon as it was mounted, which is
+     * unlikely to be the desired behaviour for the page.
+     */
+    allowFocusing: boolean;
+    /**
+     * An optional an unique key.
+     * If this key is set, tab stops will be re-registered each time the key changes.
+     * If this key is unset, tab stops will only be registered on mount and unregistered on unmount.
+     *
+     * This can be useful to set if you have cases where your tab stops might be reordered without being unmounted.
+     */
+    listKey?: string;
+}
+type TabStopRowKey = string | number;
+type BaseTypeStop = {
+    id: string;
+    domElementRef: React.RefObject<Element>;
+    disabled: boolean;
+    rowKey: TabStopRowKey | null;
+    autofocus?: boolean;
+};
+type TabStop = Readonly<BaseTypeStop>;
+type GridMap = {
+    tabStopsByRowKey: Record<TabStopRowKey, TabStop[]>;
+    rowKeys: Array<TabStopRowKey>;
+};
+type State = Readonly<{
+    /**
+     * Id of the tab stop that can currently accept focus.
+     */
+    selectedId: string | null;
+    /** Whether the user is currently using keyboard navigation */
+    isUsingKeyboard: boolean;
+    /**
+     * Array of tab stops
+     */
+    tabStops: readonly TabStop[];
+    /**
+     * Note: The gridMap is only created if row-related navigation occurs (e.g., move to row start or end).
+     * The map gets cleared if registering, unregistering, or updating.
+     */
+    gridMap: GridMap | null;
+    /** The loop behavior to apply to the columns and rows */
+    loopAround: LoopAroundByAxis;
+} & Omit<MovingFocusOptions, 'loopAround'>>;
+type RegisterAction = {
+    type: 'REGISTER_TAB_STOP';
+    payload: TabStop;
+};
+type UnregisterAction = {
+    type: 'UNREGISTER_TAB_STOP';
+    payload: {
+        id: TabStop['id'];
+    };
+};
+type UpdateTabStopAction = {
+    type: 'UPDATE_TAB_STOP';
+    payload: Pick<TabStop, 'id' | 'rowKey' | 'disabled'>;
+};
+type KeyNavAction = {
+    type: 'KEY_NAV';
+    payload: {
+        id?: TabStop['id'];
+        key: string;
+        ctrlKey: boolean;
+    };
+};
+type SetAllowFocusingAction = {
+    type: 'SET_ALLOW_FOCUSING';
+    payload: {
+        allow: boolean;
+        isKeyboardNavigation?: boolean;
+    };
+};
+type ResetSelectedTabStopAction = {
+    type: 'RESET_SELECTED_TAB_STOP';
+};
+type SelectTabStopAction = {
+    type: 'SELECT_TAB_STOP';
+    payload: {
+        id: TabStop['id'];
+        type?: 'pointer' | 'keyboard';
+    };
+};
+type OptionsUpdatedAction = {
+    type: 'OPTIONS_UPDATED';
+    payload: MovingFocusOptions;
+};
+type Action = RegisterAction | UnregisterAction | UpdateTabStopAction | KeyNavAction | SelectTabStopAction | OptionsUpdatedAction | SetAllowFocusingAction | ResetSelectedTabStopAction;
+
+interface MovingFocusProviderProps {
+    /**
+     * The child content, which will include the DOM elements to rove between using the tab key.
+     */
+    children: React__default.ReactNode;
+    /**
+     * An optional object to customize the behaviour of the moving focus. It is fine to pass a new object every time
+     * the containing component is rendered, and the options can be updated at any time.
+     */
+    options?: Partial<MovingFocusOptions>;
+}
+/**
+ * Creates a roving tabindex context.
+ */
+declare const MovingFocusProvider: React__default.FC<MovingFocusProviderProps>;
+
+type MovingFocusContext = Readonly<{
+    state: State;
+    dispatch: React__default.Dispatch<Action>;
+}>;
+declare const MovingFocusContext: React__default.Context<Readonly<{
+    state: State;
+    dispatch: React__default.Dispatch<Action>;
+}>>;
+
+/**
+ * Hook options
+ */
+type Options = [
+    /** The DOM id of the tab stop. */
+    id: string,
+    ...baseOptions: BaseHookOptions
+];
+/**
+ * Hook to use in tab stop element of a virtual focus (ex: options of a listbox in a combobox).
+ *
+ * @returns true if the current tab stop has virtual focus
+ */
+declare const useVirtualFocus: (...args: Options) => boolean;
+
+/**
+ * Hook to use in a virtual focus parent (ex: `aria-activedescendant` on the input of a combobox).
+ * * @returns the id of the currently active tab stop (virtual focus)
+ */
+declare const useVirtualFocusParent: (ref: React__default.RefObject<HTMLElement>) => string | undefined;
+
+/**
+ * A tuple of values to be applied by the containing component for the roving tabindex to work correctly.
+ */
+type Output = [
+    /** The tabIndex value to apply to the tab stop element. */
+    tabIndex: number,
+    /** Whether focus() should be invoked on the tab stop element. */
+    focused: boolean,
+    /**
+     * The onKeyDown callback to apply to the tab stop element. If the key press is relevant to the hook then
+     * event.preventDefault() will be invoked on the event.
+     */
+    handleKeyDown: (event: React__default.KeyboardEvent) => void,
+    /** The onClick callback to apply to the tab stop element. */
+    handleClick: () => void
+];
+/**
+ * Includes the given DOM element in the current roving tabindex.
+ */
+declare const useRovingTabIndex: (...args: BaseHookOptions) => Output;
+
+export { ClickAwayProvider, DisabledStateProvider, MovingFocusContext, MovingFocusProvider, Portal, PortalProvider, useDisabledStateContext, useRovingTabIndex, useVirtualFocus, useVirtualFocusParent };
 export type { PortalInit, PortalProps, PortalProviderProps };