chore(utils): Update keyboard movement

These changes are to help with the Tab movement.

Add a new `horizontal` state to the movement config which updates the
default keyboard config to use `ArrowRight` and `ArrowLeft` instead of
`ArrowDown` and `ArrowUp`.

Add a `nextFocusIndex` param to the `onFocusChange` handler.

Author: mlaursen

packages/utils/src/keyboardMovement/KeyboardMovementProvider.tsx

@@ -1,8 +1,11 @@
 import type { ReactElement, ReactNode } from "react";
 import { useMemo, useRef } from "react";
 
+import { useDir } from "../Dir";
 import {
   DEFAULT_KEYBOARD_MOVEMENT,
+  DEFAULT_LTR_KEYBOARD_MOVEMENT,
+  DEFAULT_RTL_KEYBOARD_MOVEMENT,
   KeyboardMovementContextProvider,
 } from "./movementContext";
 import type {
@@ -36,9 +39,9 @@ export interface KeyboardMovementProviderProps
  * }
  *
  * function CustomKeyboardFocusWidget() {
- *   const { onKeyDown } = useKeyboardFocus();
+ *   const { focusIndex: _focusIndex, ...eventHandlers } = useKeyboardFocus();
  *   return (
- *     <div onKeyDown={onKeyDown}>
+ *     <div {...eventHandlers}>
  *       <FocusableChild />
  *       <FocusableChild />
  *       <FocusableChild />
@@ -60,12 +63,28 @@ export function KeyboardMovementProvider({
   children,
   loopable = false,
   searchable = false,
+  horizontal = false,
   includeDisabled = false,
-  incrementKeys = DEFAULT_KEYBOARD_MOVEMENT.incrementKeys,
-  decrementKeys = DEFAULT_KEYBOARD_MOVEMENT.decrementKeys,
-  jumpToFirstKeys = DEFAULT_KEYBOARD_MOVEMENT.jumpToFirstKeys,
-  jumpToLastKeys = DEFAULT_KEYBOARD_MOVEMENT.jumpToLastKeys,
+  incrementKeys: propIncrementKeys,
+  decrementKeys: propDecrementKeys,
+  jumpToFirstKeys: propJumpToFirstKeys,
+  jumpToLastKeys: propJumpToLastKeys,
 }: KeyboardMovementProviderProps): ReactElement {
+  const isRTL = useDir().dir === "rtl";
+  let defaults: Readonly<Required<KeyboardMovementConfiguration>>;
+  if (horizontal) {
+    defaults = isRTL
+      ? DEFAULT_RTL_KEYBOARD_MOVEMENT
+      : DEFAULT_LTR_KEYBOARD_MOVEMENT;
+  } else {
+    defaults = DEFAULT_KEYBOARD_MOVEMENT;
+  }
+
+  const incrementKeys = propIncrementKeys || defaults.incrementKeys;
+  const decrementKeys = propDecrementKeys || defaults.decrementKeys;
+  const jumpToFirstKeys = propJumpToFirstKeys || defaults.jumpToFirstKeys;
+  const jumpToLastKeys = propJumpToLastKeys || defaults.jumpToLastKeys;
+
   const watching = useRef<KeyboardFocusElementData[]>([]);
   const configuration: KeyboardMovementConfig = {
     incrementKeys,
@@ -93,9 +112,10 @@ export function KeyboardMovementProvider({
       config,
       loopable,
       searchable,
+      horizontal,
       includeDisabled: includeDisabled,
     }),
-    [includeDisabled, loopable, searchable]
+    [horizontal, includeDisabled, loopable, searchable]
   );
 
   return (

packages/utils/src/keyboardMovement/movementContext.ts

@@ -25,6 +25,28 @@ export const DEFAULT_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
   jumpToLastKeys: ["End"],
 };
 
+/**
+ * @remarks \@since 5.1.2
+ * @internal
+ */
+export const DEFAULT_LTR_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
+  incrementKeys: ["ArrowRight"],
+  decrementKeys: ["ArrowLeft"],
+  jumpToFirstKeys: ["Home"],
+  jumpToLastKeys: ["End"],
+};
+
+/**
+ * @remarks \@since 5.1.2
+ * @internal
+ */
+export const DEFAULT_RTL_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
+  incrementKeys: ["ArrowLeft"],
+  decrementKeys: ["ArrowRight"],
+  jumpToFirstKeys: ["Home"],
+  jumpToLastKeys: ["End"],
+};
+
 /**
  * @remarks \@since 5.0.0
  * @internal
@@ -35,6 +57,7 @@ const context = createContext<KeyboardFocusContext>({
   watching: { current: [] },
   loopable: false,
   searchable: false,
+  horizontal: false,
   includeDisabled: false,
   config: { current: DEFAULT_KEYBOARD_MOVEMENT },
 });

packages/utils/src/keyboardMovement/types.ts

@@ -72,6 +72,16 @@ export interface KeyboardMovementBehavior {
    * @defaultValue `false`
    */
   includeDisabled?: boolean;
+
+  /**
+   * Boolean if the keyboard movement is horizontal instead of vertical. This
+   * updates the default keyboard config to use `ArrowRight` and `ArrowLeft`
+   * isntead of `ArrowDown` and `ArrowUp`,
+   *
+   * @remarks \@since 5.1.2
+   * @defaultValue `false`
+   */
+  horizontal?: boolean;
 }
 
 /**

packages/utils/src/keyboardMovement/useKeyboardFocus.ts

@@ -110,13 +110,13 @@ export interface KeyboardFocusHookOptions<E extends HTMLElement>
    * The default value is just to call `element.focus()`.
    *
    * @param element - The element that should gain custom focus
+   * @param nextFocusIndex - The next focus index which can be used for
+   * additional movement behavior.
    */
-  onFocusChange?(element: HTMLElement): void;
+  onFocusChange?(element: HTMLElement, nextFocusIndex: number): void;
 }
 
-/**
- * @remarks \@since 5.0.0
- */
+/** @remarks \@since 5.0.0 */
 export interface KeyboardFocusHookReturnValue<E extends HTMLElement> {
   onFocus: FocusEventHandler<E>;
   onKeyDown: KeyboardEventHandler<E>;
@@ -184,7 +184,7 @@ export function useKeyboardFocus<E extends HTMLElement>(
 
       focusIndex.current = defaultFocusIndex;
       const element = watching.current[focusIndex.current]?.element;
-      element && onFocusChange(element);
+      element && onFocusChange(element, focusIndex.current);
     },
     onKeyDown(event) {
       onKeyDown(event);
@@ -206,7 +206,7 @@ export function useKeyboardFocus<E extends HTMLElement>(
         focusIndex.current = index;
 
         const element = watching.current[index]?.element;
-        element && onFocusChange(element);
+        element && onFocusChange(element, focusIndex.current);
       };
 
       if (