@react-md/core 6.2.1 → 6.3.1

package/dist/movement/constants.js

@@ -18,15 +18,23 @@
     ]
 };
 /**
- * @since 5.1.2
+ * @since 6.3.0
  * @internal
- */ export const DEFAULT_LTR_KEYBOARD_MOVEMENT = {
+ */ export const DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP = {
     incrementKeys: [
         "ArrowRight"
     ],
     decrementKeys: [
         "ArrowLeft"
     ],
+    jumpToFirstKeys: [],
+    jumpToLastKeys: []
+};
+/**
+ * @since 5.1.2
+ * @internal
+ */ export const DEFAULT_LTR_KEYBOARD_MOVEMENT = {
+    ...DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
     jumpToFirstKeys: [
         "Home"
     ],
@@ -35,15 +43,23 @@
     ]
 };
 /**
- * @since 5.1.2
+ * @since 6.3.0
  * @internal
- */ export const DEFAULT_RTL_KEYBOARD_MOVEMENT = {
+ */ export const DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP = {
     incrementKeys: [
         "ArrowLeft"
     ],
     decrementKeys: [
         "ArrowRight"
     ],
+    jumpToFirstKeys: [],
+    jumpToLastKeys: []
+};
+/**
+ * @since 5.1.2
+ * @internal
+ */ export const DEFAULT_RTL_KEYBOARD_MOVEMENT = {
+    ...DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
     jumpToFirstKeys: [
         "Home"
     ],

package/dist/movement/constants.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/movement/constants.ts"],"sourcesContent":["import type { KeyboardMovementConfig } from \"./types.js\";\n\n/**\n * Most custom keyboard functionality use these keys.\n *\n * @since 5.0.0\n * @internal\n */\nexport const DEFAULT_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  incrementKeys: [\"ArrowDown\"],\n  decrementKeys: [\"ArrowUp\"],\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n\n/**\n * @since 5.1.2\n * @internal\n */\nexport const DEFAULT_LTR_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  incrementKeys: [\"ArrowRight\"],\n  decrementKeys: [\"ArrowLeft\"],\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n\n/**\n * @since 5.1.2\n * @internal\n */\nexport const DEFAULT_RTL_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  incrementKeys: [\"ArrowLeft\"],\n  decrementKeys: [\"ArrowRight\"],\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n"],"names":["DEFAULT_KEYBOARD_MOVEMENT","incrementKeys","decrementKeys","jumpToFirstKeys","jumpToLastKeys","DEFAULT_LTR_KEYBOARD_MOVEMENT","DEFAULT_RTL_KEYBOARD_MOVEMENT"],"mappings":"AAEA;;;;;CAKC,GACD,OAAO,MAAMA,4BAA8D;IACzEC,eAAe;QAAC;KAAY;IAC5BC,eAAe;QAAC;KAAU;IAC1BC,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE;AAEF;;;CAGC,GACD,OAAO,MAAMC,gCAAkE;IAC7EJ,eAAe;QAAC;KAAa;IAC7BC,eAAe;QAAC;KAAY;IAC5BC,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE;AAEF;;;CAGC,GACD,OAAO,MAAME,gCAAkE;IAC7EL,eAAe;QAAC;KAAY;IAC5BC,eAAe;QAAC;KAAa;IAC7BC,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE"}
+{"version":3,"sources":["../../src/movement/constants.ts"],"sourcesContent":["import type { KeyboardMovementConfig } from \"./types.js\";\n\n/**\n * Most custom keyboard functionality use these keys.\n *\n * @since 5.0.0\n * @internal\n */\nexport const DEFAULT_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  incrementKeys: [\"ArrowDown\"],\n  decrementKeys: [\"ArrowUp\"],\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n\n/**\n * @since 6.3.0\n * @internal\n */\nexport const DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP: Readonly<KeyboardMovementConfig> =\n  {\n    incrementKeys: [\"ArrowRight\"],\n    decrementKeys: [\"ArrowLeft\"],\n    jumpToFirstKeys: [],\n    jumpToLastKeys: [],\n  };\n\n/**\n * @since 5.1.2\n * @internal\n */\nexport const DEFAULT_LTR_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  ...DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP,\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n\n/**\n * @since 6.3.0\n * @internal\n */\nexport const DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP: Readonly<KeyboardMovementConfig> =\n  {\n    incrementKeys: [\"ArrowLeft\"],\n    decrementKeys: [\"ArrowRight\"],\n    jumpToFirstKeys: [],\n    jumpToLastKeys: [],\n  };\n\n/**\n * @since 5.1.2\n * @internal\n */\nexport const DEFAULT_RTL_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {\n  ...DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP,\n  jumpToFirstKeys: [\"Home\"],\n  jumpToLastKeys: [\"End\"],\n};\n"],"names":["DEFAULT_KEYBOARD_MOVEMENT","incrementKeys","decrementKeys","jumpToFirstKeys","jumpToLastKeys","DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP","DEFAULT_LTR_KEYBOARD_MOVEMENT","DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP","DEFAULT_RTL_KEYBOARD_MOVEMENT"],"mappings":"AAEA;;;;;CAKC,GACD,OAAO,MAAMA,4BAA8D;IACzEC,eAAe;QAAC;KAAY;IAC5BC,eAAe;QAAC;KAAU;IAC1BC,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE;AAEF;;;CAGC,GACD,OAAO,MAAMC,6CACX;IACEJ,eAAe;QAAC;KAAa;IAC7BC,eAAe;QAAC;KAAY;IAC5BC,iBAAiB,EAAE;IACnBC,gBAAgB,EAAE;AACpB,EAAE;AAEJ;;;CAGC,GACD,OAAO,MAAME,gCAAkE;IAC7E,GAAGD,0CAA0C;IAC7CF,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE;AAEF;;;CAGC,GACD,OAAO,MAAMG,6CACX;IACEN,eAAe;QAAC;KAAY;IAC5BC,eAAe;QAAC;KAAa;IAC7BC,iBAAiB,EAAE;IACnBC,gBAAgB,EAAE;AACpB,EAAE;AAEJ;;;CAGC,GACD,OAAO,MAAMI,gCAAkE;IAC7E,GAAGD,0CAA0C;IAC7CJ,iBAAiB;QAAC;KAAO;IACzBC,gBAAgB;QAAC;KAAM;AACzB,EAAE"}

package/dist/movement/types.d.ts

@@ -1,5 +1,5 @@
-import type { FocusEvent, FocusEventHandler, KeyboardEvent, KeyboardEventHandler, MouseEvent, MouseEventHandler } from "react";
-import type { NonNullMutableRef, NonNullRef, UseStateSetter } from "../types.js";
+import { type HTMLAttributes, type KeyboardEvent, type Ref, type RefCallback, type RefObject } from "react";
+import { type NonNullMutableRef, type NonNullRef, type UseStateSetter } from "../types.js";
 /**
  * Set this to `"roving"` when:
  * - there are a group of focusable elements that have a `tabIndex={-1}`
@@ -109,6 +109,20 @@ export interface KeyboardMovementBehavior {
      */
     horizontal?: boolean;
 }
+/**
+ * @since 6.3.0
+ */
+export interface KeyboardFocusFromKeyOptions {
+    key: string;
+    /** @defaultValue `false` */
+    reversed?: boolean;
+    /** @defaultValue `getFocusableElementsFromRef()` */
+    focusables?: readonly HTMLElement[];
+}
+/**
+ * @since 6.3.0
+ */
+export type KeyboardFocusAction = (focusables?: readonly HTMLElement[]) => void;
 /**
  * @since 5.0.0
  * @since 6.0.0 Removed `attach`, `detach` and `watching`
@@ -124,6 +138,26 @@ export interface KeyboardMovementContext extends Required<KeyboardMovementBehavi
      * has been set to `"roving"` or `"virtual"`.
      */
     activeDescendantId: string;
+    /**
+     * @since 6.3.0
+     */
+    focusFirst: KeyboardFocusAction;
+    /**
+     * @since 6.3.0
+     */
+    focusLast: KeyboardFocusAction;
+    /**
+     * @since 6.3.0
+     */
+    focusNext: KeyboardFocusAction;
+    /**
+     * @since 6.3.0
+     */
+    focusPrevious: KeyboardFocusAction;
+    /**
+     * @since 6.3.0
+     */
+    focusFromKey: (options: KeyboardFocusFromKeyOptions) => void;
 }
 /**
  * @since 6.0.0
@@ -166,16 +200,23 @@ export interface KeyboardMovementExtensionData<E extends HTMLElement> extends Ke
     setFocusIndex: (index: number, focusables: readonly HTMLElement[]) => void;
     setActiveDescendantId: (id: string) => void;
 }
+/**
+ * @since 6.3.0
+ */
+export type KeyboardMovementEventHandlers<E extends HTMLElement> = Pick<HTMLAttributes<E>, "onClick" | "onFocus" | "onKeyDown">;
+/**
+ * @since 6.3.0
+ */
+export interface SimpleKeyboardMovementWrapperOptions<E extends HTMLElement> extends KeyboardMovementEventHandlers<E> {
+    ref?: Ref<E>;
+}
 /**
  * @since 6.0.0
  * @internal
  */
-export interface KeyboardMovementProviderOptions<E extends HTMLElement> extends KeyboardMovementBehavior, KeyboardMovementConfiguration {
+export interface KeyboardMovementProviderOptions<E extends HTMLElement> extends KeyboardMovementBehavior, SimpleKeyboardMovementWrapperOptions<E>, KeyboardMovementConfiguration {
     /** @see {@link TabIndexBehavior} */
     tabIndexBehavior?: TabIndexBehavior;
-    onClick?: (event: MouseEvent<E>) => void;
-    onFocus?: (event: FocusEvent<E>) => void;
-    onKeyDown?: (event: KeyboardEvent<E>) => void;
     /** @defaultValue `false` */
     disabled?: boolean;
     /**
@@ -210,12 +251,21 @@ export interface KeyboardMovementProviderOptions<E extends HTMLElement> extends
      * @defaultValue `false`
      */
     isNegativeOneAllowed?: boolean;
+    /**
+     * This was added to support spinbutton groups so the user can either use the
+     * ArrowLeft, ArrowRight, or Tab keys to move. Without this, switching
+     * between tab and the arrow keys would have the wrong tab index.
+     *
+     * @since 6.3.0
+     * @defaultValue `false`
+     */
+    trackTabKeys?: boolean;
 }
 /**
  * @since 6.0.0
  * @internal
  */
-export interface KeyboardMovementProps<E extends HTMLElement> {
+export interface KeyboardMovementProps<E extends HTMLElement> extends Required<KeyboardMovementEventHandlers<E>> {
     /**
      * This will only be provided if the {@link KeyboardMovementContext.tabIndexBehavior}
      * is set to `"virtual"`.
@@ -231,15 +281,14 @@ export interface KeyboardMovementProps<E extends HTMLElement> {
      *   - a child element **should** have a `tabIndex={0}` instead
      */
     tabIndex?: number;
-    onClick: MouseEventHandler<E>;
-    onFocus: FocusEventHandler<E>;
-    onKeyDown: KeyboardEventHandler<E>;
+    ref: RefCallback<E>;
 }
 /**
  * @since 6.0.0
  * @internal
  */
 export interface KeyboardMovementProviderImplementation<E extends HTMLElement> {
+    nodeRef: RefObject<E>;
     movementProps: Readonly<KeyboardMovementProps<E>>;
     movementContext: Readonly<KeyboardMovementContext>;
     currentFocusIndex: NonNullMutableRef<number>;

package/dist/movement/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/movement/types.ts"],"sourcesContent":["import type {\n  FocusEvent,\n  FocusEventHandler,\n  KeyboardEvent,\n  KeyboardEventHandler,\n  MouseEvent,\n  MouseEventHandler,\n} from \"react\";\n\nimport type {\n  NonNullMutableRef,\n  NonNullRef,\n  UseStateSetter,\n} from \"../types.js\";\n\n/**\n * Set this to `\"roving\"` when:\n * - there are a group of focusable elements that have a `tabIndex={-1}`\n * - the container element defaults to having a `tabIndex={0}`\n * - if the container is focused, it should no longer be included in the normal\n *   tab flow. Instead, the current focused element should be included instead\n *   by changing its `tabIndex` from `-1` to `0`\n *\n * Set this to `\"virtual\"` when:\n * - the container element should never lose focus\n * - the \"focused\" element only gains focus styles instead of being focused\n * - the container element specifies an `aria-activedescendant` pointing to one\n *   of the ids for the child \"focusable\" elements\n *\n * @since 6.0.0\n */\nexport type TabIndexBehavior = \"roving\" | \"virtual\";\n\n/**\n * This should be used for specific widgets that should not include all\n * focusable elements and instead only specific elements.\n *\n * @example\n * ```ts\n * const getExpansionPanelsOnly: GetFocusableElements = (container) =>\n *   [...container.querySelectorAll(\".rmd-expansion-panel__button\")];\n *\n * const getTreeItemsOnly: GetFocusableElements = (container) =>\n *   [...container.querySelectorAll(\"[role='treeitem']\")];\n * ```\n *\n * @defaultValue `getFocusableElements`\n * @see the default `getFocusableElements` function.\n */\nexport type GetFocusableElements = (\n  container: HTMLElement,\n  programmatic: boolean\n) => readonly HTMLElement[];\n\n/**\n * @since 5.0.0\n */\nexport interface KeyboardMovementConfiguration {\n  /**\n   * A list of keys that will attempt to increment the focus index by 1.\n   *\n   * @defaultValue `[\"ArrowDown\"]`\n   */\n  incrementKeys?: readonly string[];\n\n  /**\n   * A list of keys that will attempt to decrement the focus index by 1.\n   *\n   * @defaultValue `[\"ArrowUp\"]`\n   */\n  decrementKeys?: readonly string[];\n\n  /**\n   * A list of keys that will set the focus index to `0`.\n   *\n   * @defaultValue `[\"Home\"]`\n   */\n  jumpToFirstKeys?: readonly string[];\n\n  /**\n   * A list of keys that will set the focus index to the last focusable index.\n   *\n   * @defaultValue `[\"End\"]`\n   */\n  jumpToLastKeys?: readonly string[];\n}\n\n/**\n * The defined {@link KeyboardMovementConfiguration} that should be used for\n * custom keyboard focus behavior.\n *\n * @since 5.0.0\n */\nexport type KeyboardMovementConfig = Required<KeyboardMovementConfiguration>;\n\n/**\n * @since 5.0.0\n */\nexport interface KeyboardMovementBehavior {\n  /**\n   * Boolean if pressing a letter will focus the next item in the\n   * {@link KeyboardMovementProvider} that starts with the same letter.\n   *\n   * @defaultValue `false`\n   */\n  searchable?: boolean;\n\n  /**\n   * Boolean if the {@link KeyboardMovementProvider} should allow the focus behavior\n   * to loop from the first to last or last to first item instead of preventing\n   * any new focus behavior. In other words... if the last item is focused and\n   * the user presses a key that should advance the focus to the next focusable\n   * element, should the focus stay on the current element or loop back and\n   * focus the first focusable item.\n   *\n   * @defaultValue `false`\n   */\n  loopable?: boolean;\n\n  /**\n   * Boolean if elements that are `aria-disabled` or `disabled` should still be\n   * able to gain focus.\n   *\n   * @defaultValue `false`\n   */\n  includeDisabled?: boolean;\n\n  /**\n   * Boolean if the keyboard movement is horizontal instead of vertical. This\n   * updates the default keyboard config to use `ArrowRight` and `ArrowLeft`\n   * instead of `ArrowDown` and `ArrowUp`,\n   *\n   * @since 5.1.2\n   * @defaultValue `false`\n   */\n  horizontal?: boolean;\n}\n\n/**\n * @since 5.0.0\n * @since 6.0.0 Removed `attach`, `detach` and `watching`\n * @internal\n */\nexport interface KeyboardMovementContext\n  extends Required<KeyboardMovementBehavior> {\n  /** {@inheritDoc KeyboardMovementConfig} */\n  config: NonNullRef<KeyboardMovementConfig>;\n\n  /** @see {@link TabIndexBehavior} */\n  tabIndexBehavior: TabIndexBehavior | undefined;\n\n  /**\n   * Note: This will only update if the {@link KeyboardMovementProviderOptions.tabIndexBehavior}\n   * has been set to `\"roving\"` or `\"virtual\"`.\n   */\n  activeDescendantId: string;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface FocusableIndexOptions {\n  focusables: readonly HTMLElement[];\n  includeDisabled: boolean;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type GetDefaultFocusedIndex = (options: FocusableIndexOptions) => number;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type ExtendKeyDown<E extends HTMLElement> = (\n  movementData: KeyboardMovementExtensionData<E>\n) => void;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementFocusChangeEvent {\n  index: number;\n  element: HTMLElement;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type KeyboardMovementFocusChangeEventHandler = (\n  event: KeyboardMovementFocusChangeEvent\n) => void;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementExtensionData<E extends HTMLElement>\n  extends KeyboardMovementContext {\n  event: KeyboardEvent<E>;\n  currentFocusIndex: NonNullMutableRef<number>;\n  setFocusIndex: (index: number, focusables: readonly HTMLElement[]) => void;\n  setActiveDescendantId: (id: string) => void;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProviderOptions<E extends HTMLElement>\n  extends KeyboardMovementBehavior,\n    KeyboardMovementConfiguration {\n  /** @see {@link TabIndexBehavior} */\n  tabIndexBehavior?: TabIndexBehavior;\n\n  onClick?: (event: MouseEvent<E>) => void;\n  onFocus?: (event: FocusEvent<E>) => void;\n  onKeyDown?: (event: KeyboardEvent<E>) => void;\n\n  /** @defaultValue `false` */\n  disabled?: boolean;\n\n  /**\n   * This is used to implement custom keyboard movement for the `keydown` event.\n   */\n  extendKeyDown?: ExtendKeyDown<E>;\n\n  /**\n   * Triggered whenever the focus changes.\n   */\n  onFocusChange?: KeyboardMovementFocusChangeEventHandler;\n\n  /**\n   * From what I've understood so far, programmatically focusable elements\n   * should only be included when disabled elements via `aria-disabled` are\n   * allowed.\n   *\n   * @defaultValue `includeDisabled`\n   */\n  programmatic?: boolean;\n\n  /** @see {@link GetFocusableElements} */\n  getFocusableElements?: GetFocusableElements;\n\n  /**\n   * This can be used to set the initial focus index whenever the container\n   * element is first focused or the focus index is `-1` on other focus events.\n   */\n  getDefaultFocusedIndex?: GetDefaultFocusedIndex;\n\n  /**\n   * This was added to support editable combobox behavior. As the user types or\n   * uses native input keyboard behavior, the focus index should be reset to\n   * `-1` so that the next \"ArrowDown\" event focuses the first option again\n   * instead of the last selected one.\n   *\n   * @defaultValue `false`\n   */\n  isNegativeOneAllowed?: boolean;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProps<E extends HTMLElement> {\n  /**\n   * This will only be provided if the {@link KeyboardMovementContext.tabIndexBehavior}\n   * is set to `\"virtual\"`.\n   */\n  \"aria-activedescendant\"?: string;\n\n  /**\n   * This will not be provided if the {@link KeyboardMovementContext.tabIndexBehavior}\n   * is `undefined`. Otherwise:\n   * - `0` when `\"virtual\"`\n   * - `0` when `\"roving\"` and the container element has not been focused at\n   *   least once\n   * - `-1` when `\"roving\"` and the container has been focused at least once\n   *   - a child element **should** have a `tabIndex={0}` instead\n   */\n  tabIndex?: number;\n  onClick: MouseEventHandler<E>;\n  onFocus: FocusEventHandler<E>;\n  onKeyDown: KeyboardEventHandler<E>;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProviderImplementation<E extends HTMLElement> {\n  movementProps: Readonly<KeyboardMovementProps<E>>;\n  movementContext: Readonly<KeyboardMovementContext>;\n  currentFocusIndex: NonNullMutableRef<number>;\n  activeDescendantId: string;\n  setActiveDescendantId: UseStateSetter<string>;\n}\n"],"names":[],"mappings":"AAoSA;;;CAGC,GACD,WAMC"}
+{"version":3,"sources":["../../src/movement/types.ts"],"sourcesContent":["import {\n  type HTMLAttributes,\n  type KeyboardEvent,\n  type Ref,\n  type RefCallback,\n  type RefObject,\n} from \"react\";\n\nimport {\n  type NonNullMutableRef,\n  type NonNullRef,\n  type UseStateSetter,\n} from \"../types.js\";\n\n/**\n * Set this to `\"roving\"` when:\n * - there are a group of focusable elements that have a `tabIndex={-1}`\n * - the container element defaults to having a `tabIndex={0}`\n * - if the container is focused, it should no longer be included in the normal\n *   tab flow. Instead, the current focused element should be included instead\n *   by changing its `tabIndex` from `-1` to `0`\n *\n * Set this to `\"virtual\"` when:\n * - the container element should never lose focus\n * - the \"focused\" element only gains focus styles instead of being focused\n * - the container element specifies an `aria-activedescendant` pointing to one\n *   of the ids for the child \"focusable\" elements\n *\n * @since 6.0.0\n */\nexport type TabIndexBehavior = \"roving\" | \"virtual\";\n\n/**\n * This should be used for specific widgets that should not include all\n * focusable elements and instead only specific elements.\n *\n * @example\n * ```ts\n * const getExpansionPanelsOnly: GetFocusableElements = (container) =>\n *   [...container.querySelectorAll(\".rmd-expansion-panel__button\")];\n *\n * const getTreeItemsOnly: GetFocusableElements = (container) =>\n *   [...container.querySelectorAll(\"[role='treeitem']\")];\n * ```\n *\n * @defaultValue `getFocusableElements`\n * @see the default `getFocusableElements` function.\n */\nexport type GetFocusableElements = (\n  container: HTMLElement,\n  programmatic: boolean\n) => readonly HTMLElement[];\n\n/**\n * @since 5.0.0\n */\nexport interface KeyboardMovementConfiguration {\n  /**\n   * A list of keys that will attempt to increment the focus index by 1.\n   *\n   * @defaultValue `[\"ArrowDown\"]`\n   */\n  incrementKeys?: readonly string[];\n\n  /**\n   * A list of keys that will attempt to decrement the focus index by 1.\n   *\n   * @defaultValue `[\"ArrowUp\"]`\n   */\n  decrementKeys?: readonly string[];\n\n  /**\n   * A list of keys that will set the focus index to `0`.\n   *\n   * @defaultValue `[\"Home\"]`\n   */\n  jumpToFirstKeys?: readonly string[];\n\n  /**\n   * A list of keys that will set the focus index to the last focusable index.\n   *\n   * @defaultValue `[\"End\"]`\n   */\n  jumpToLastKeys?: readonly string[];\n}\n\n/**\n * The defined {@link KeyboardMovementConfiguration} that should be used for\n * custom keyboard focus behavior.\n *\n * @since 5.0.0\n */\nexport type KeyboardMovementConfig = Required<KeyboardMovementConfiguration>;\n\n/**\n * @since 5.0.0\n */\nexport interface KeyboardMovementBehavior {\n  /**\n   * Boolean if pressing a letter will focus the next item in the\n   * {@link KeyboardMovementProvider} that starts with the same letter.\n   *\n   * @defaultValue `false`\n   */\n  searchable?: boolean;\n\n  /**\n   * Boolean if the {@link KeyboardMovementProvider} should allow the focus behavior\n   * to loop from the first to last or last to first item instead of preventing\n   * any new focus behavior. In other words... if the last item is focused and\n   * the user presses a key that should advance the focus to the next focusable\n   * element, should the focus stay on the current element or loop back and\n   * focus the first focusable item.\n   *\n   * @defaultValue `false`\n   */\n  loopable?: boolean;\n\n  /**\n   * Boolean if elements that are `aria-disabled` or `disabled` should still be\n   * able to gain focus.\n   *\n   * @defaultValue `false`\n   */\n  includeDisabled?: boolean;\n\n  /**\n   * Boolean if the keyboard movement is horizontal instead of vertical. This\n   * updates the default keyboard config to use `ArrowRight` and `ArrowLeft`\n   * instead of `ArrowDown` and `ArrowUp`,\n   *\n   * @since 5.1.2\n   * @defaultValue `false`\n   */\n  horizontal?: boolean;\n}\n\n/**\n * @since 6.3.0\n */\nexport interface KeyboardFocusFromKeyOptions {\n  key: string;\n  /** @defaultValue `false` */\n  reversed?: boolean;\n\n  /** @defaultValue `getFocusableElementsFromRef()` */\n  focusables?: readonly HTMLElement[];\n}\n\n/**\n * @since 6.3.0\n */\nexport type KeyboardFocusAction = (focusables?: readonly HTMLElement[]) => void;\n\n/**\n * @since 5.0.0\n * @since 6.0.0 Removed `attach`, `detach` and `watching`\n * @internal\n */\nexport interface KeyboardMovementContext\n  extends Required<KeyboardMovementBehavior> {\n  /** {@inheritDoc KeyboardMovementConfig} */\n  config: NonNullRef<KeyboardMovementConfig>;\n\n  /** @see {@link TabIndexBehavior} */\n  tabIndexBehavior: TabIndexBehavior | undefined;\n\n  /**\n   * Note: This will only update if the {@link KeyboardMovementProviderOptions.tabIndexBehavior}\n   * has been set to `\"roving\"` or `\"virtual\"`.\n   */\n  activeDescendantId: string;\n\n  /**\n   * @since 6.3.0\n   */\n  focusFirst: KeyboardFocusAction;\n\n  /**\n   * @since 6.3.0\n   */\n  focusLast: KeyboardFocusAction;\n\n  /**\n   * @since 6.3.0\n   */\n  focusNext: KeyboardFocusAction;\n\n  /**\n   * @since 6.3.0\n   */\n  focusPrevious: KeyboardFocusAction;\n\n  /**\n   * @since 6.3.0\n   */\n  focusFromKey: (options: KeyboardFocusFromKeyOptions) => void;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface FocusableIndexOptions {\n  focusables: readonly HTMLElement[];\n  includeDisabled: boolean;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type GetDefaultFocusedIndex = (options: FocusableIndexOptions) => number;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type ExtendKeyDown<E extends HTMLElement> = (\n  movementData: KeyboardMovementExtensionData<E>\n) => void;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementFocusChangeEvent {\n  index: number;\n  element: HTMLElement;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport type KeyboardMovementFocusChangeEventHandler = (\n  event: KeyboardMovementFocusChangeEvent\n) => void;\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementExtensionData<E extends HTMLElement>\n  extends KeyboardMovementContext {\n  event: KeyboardEvent<E>;\n  currentFocusIndex: NonNullMutableRef<number>;\n  setFocusIndex: (index: number, focusables: readonly HTMLElement[]) => void;\n  setActiveDescendantId: (id: string) => void;\n}\n\n/**\n * @since 6.3.0\n */\nexport type KeyboardMovementEventHandlers<E extends HTMLElement> = Pick<\n  HTMLAttributes<E>,\n  \"onClick\" | \"onFocus\" | \"onKeyDown\"\n>;\n\n/**\n * @since 6.3.0\n */\nexport interface SimpleKeyboardMovementWrapperOptions<E extends HTMLElement>\n  extends KeyboardMovementEventHandlers<E> {\n  ref?: Ref<E>;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProviderOptions<E extends HTMLElement>\n  extends KeyboardMovementBehavior,\n    SimpleKeyboardMovementWrapperOptions<E>,\n    KeyboardMovementConfiguration {\n  /** @see {@link TabIndexBehavior} */\n  tabIndexBehavior?: TabIndexBehavior;\n\n  /** @defaultValue `false` */\n  disabled?: boolean;\n\n  /**\n   * This is used to implement custom keyboard movement for the `keydown` event.\n   */\n  extendKeyDown?: ExtendKeyDown<E>;\n\n  /**\n   * Triggered whenever the focus changes.\n   */\n  onFocusChange?: KeyboardMovementFocusChangeEventHandler;\n\n  /**\n   * From what I've understood so far, programmatically focusable elements\n   * should only be included when disabled elements via `aria-disabled` are\n   * allowed.\n   *\n   * @defaultValue `includeDisabled`\n   */\n  programmatic?: boolean;\n\n  /** @see {@link GetFocusableElements} */\n  getFocusableElements?: GetFocusableElements;\n\n  /**\n   * This can be used to set the initial focus index whenever the container\n   * element is first focused or the focus index is `-1` on other focus events.\n   */\n  getDefaultFocusedIndex?: GetDefaultFocusedIndex;\n\n  /**\n   * This was added to support editable combobox behavior. As the user types or\n   * uses native input keyboard behavior, the focus index should be reset to\n   * `-1` so that the next \"ArrowDown\" event focuses the first option again\n   * instead of the last selected one.\n   *\n   * @defaultValue `false`\n   */\n  isNegativeOneAllowed?: boolean;\n\n  /**\n   * This was added to support spinbutton groups so the user can either use the\n   * ArrowLeft, ArrowRight, or Tab keys to move. Without this, switching\n   * between tab and the arrow keys would have the wrong tab index.\n   *\n   * @since 6.3.0\n   * @defaultValue `false`\n   */\n  trackTabKeys?: boolean;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProps<E extends HTMLElement>\n  extends Required<KeyboardMovementEventHandlers<E>> {\n  /**\n   * This will only be provided if the {@link KeyboardMovementContext.tabIndexBehavior}\n   * is set to `\"virtual\"`.\n   */\n  \"aria-activedescendant\"?: string;\n\n  /**\n   * This will not be provided if the {@link KeyboardMovementContext.tabIndexBehavior}\n   * is `undefined`. Otherwise:\n   * - `0` when `\"virtual\"`\n   * - `0` when `\"roving\"` and the container element has not been focused at\n   *   least once\n   * - `-1` when `\"roving\"` and the container has been focused at least once\n   *   - a child element **should** have a `tabIndex={0}` instead\n   */\n  tabIndex?: number;\n\n  ref: RefCallback<E>;\n}\n\n/**\n * @since 6.0.0\n * @internal\n */\nexport interface KeyboardMovementProviderImplementation<E extends HTMLElement> {\n  nodeRef: RefObject<E>;\n  movementProps: Readonly<KeyboardMovementProps<E>>;\n  movementContext: Readonly<KeyboardMovementContext>;\n  currentFocusIndex: NonNullMutableRef<number>;\n  activeDescendantId: string;\n  setActiveDescendantId: UseStateSetter<string>;\n}\n"],"names":[],"mappings":"AAoWA;;;CAGC,GACD,WAOC"}

package/dist/movement/useKeyboardMovementProvider.d.ts

@@ -1,4 +1,8 @@
-import type { KeyboardMovementContext, KeyboardMovementProviderImplementation, KeyboardMovementProviderOptions } from "./types.js";
+import { type KeyboardMovementContext, type KeyboardMovementProviderImplementation, type KeyboardMovementProviderOptions } from "./types.js";
+/**
+ * @since 6.3.0
+ */
+export declare const DEFAULT_KEYBOARD_MOVEMENT_CONTEXT: Readonly<KeyboardMovementContext>;
 export declare const KeyboardMovementProvider: import("react").Provider<KeyboardMovementContext>;
 /**
  * @since 5.0.0

package/dist/movement/useKeyboardMovementProvider.js

@@ -1,16 +1,19 @@
 "use client";
-import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
 import { getFocusableElements as defaultGetFocusableElements } from "../focus/utils.js";
 import { useUserInteractionMode } from "../interaction/UserInteractionModeProvider.js";
 import { useDir } from "../typography/WritingDirectionProvider.js";
+import { useEnsuredRef } from "../useEnsuredRef.js";
 import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
 import { DEFAULT_KEYBOARD_MOVEMENT, DEFAULT_LTR_KEYBOARD_MOVEMENT, DEFAULT_RTL_KEYBOARD_MOVEMENT } from "./constants.js";
 import { findMatchIndex } from "./findMatchIndex.js";
 import { getFirstFocusableIndex, getLastFocusableIndex, getNextFocusableIndex, getSearchText, getVirtualFocusDefaultIndex, isElementDisabled, isNotFocusable, isSearchableEvent, recalculateFocusIndex } from "./utils.js";
+const noop = ()=>{
+// do nothing
+};
 /**
- * @since 5.0.0
- * @internal
- */ const context = createContext({
+ * @since 6.3.0
+ */ export const DEFAULT_KEYBOARD_MOVEMENT_CONTEXT = {
     config: {
         current: DEFAULT_KEYBOARD_MOVEMENT
     },
@@ -19,8 +22,17 @@ import { getFirstFocusableIndex, getLastFocusableIndex, getNextFocusableIndex, g
     horizontal: false,
     includeDisabled: false,
     tabIndexBehavior: undefined,
-    activeDescendantId: ""
-});
+    activeDescendantId: "",
+    focusFirst: noop,
+    focusLast: noop,
+    focusNext: noop,
+    focusPrevious: noop,
+    focusFromKey: noop
+};
+/**
+ * @since 5.0.0
+ * @internal
+ */ const context = createContext(DEFAULT_KEYBOARD_MOVEMENT_CONTEXT);
 context.displayName = "KeyboardMovement";
 export const { Provider: KeyboardMovementProvider } = context;
 /**
@@ -29,9 +41,6 @@ export const { Provider: KeyboardMovementProvider } = context;
  */ export function useKeyboardMovementContext() {
     return useContext(context);
 }
-const noop = ()=>{
-// do nothing
-};
 const returnNegative1 = ()=>-1;
 /**
  * Implements the custom keyboard movement behavior throughout react-md. Using
@@ -154,7 +163,8 @@ const returnNegative1 = ()=>-1;
  * @since 6.0.0
  * @internal
  */ export function useKeyboardMovementProvider(options = {}) {
-    const { onClick = noop, onFocus = noop, onKeyDown = noop, loopable = false, disabled, searchable = false, horizontal = false, includeDisabled = false, tabIndexBehavior, extendKeyDown = noop, onFocusChange = noop, programmatic = includeDisabled, incrementKeys: propIncrementKeys, decrementKeys: propDecrementKeys, jumpToFirstKeys: propJumpToFirstKeys, jumpToLastKeys: propJumpToLastKeys, getFocusableElements = defaultGetFocusableElements, getDefaultFocusedIndex = returnNegative1, isNegativeOneAllowed = false } = options;
+    const { ref: propRef, onClick = noop, onFocus = noop, onKeyDown = noop, loopable = false, disabled, searchable = false, horizontal = false, trackTabKeys = false, includeDisabled = false, tabIndexBehavior, extendKeyDown = noop, onFocusChange = noop, programmatic = includeDisabled, incrementKeys: propIncrementKeys, decrementKeys: propDecrementKeys, jumpToFirstKeys: propJumpToFirstKeys, jumpToLastKeys: propJumpToLastKeys, getFocusableElements = defaultGetFocusableElements, getDefaultFocusedIndex = returnNegative1, isNegativeOneAllowed = false } = options;
+    const [nodeRef, nodeRefCallback] = useEnsuredRef(propRef);
     const isRTL = useDir().dir === "rtl";
     let defaults;
     if (horizontal) {
@@ -176,42 +186,153 @@ const returnNegative1 = ()=>-1;
     useIsomorphicLayoutEffect(()=>{
         config.current = configuration;
     });
+    const mode = useUserInteractionMode();
+    const refocus = useRef(false);
+    const currentFocusIndex = useRef(-1);
     const [activeDescendantId, setActiveDescendantId] = useState("");
+    if (process.env.NODE_ENV !== "production") {
+        // this fixes issues during hot reloading and using the `useId()` hook
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        useEffect(()=>{
+            return ()=>{
+                setActiveDescendantId("");
+            };
+        }, []);
+    }
+    let tabIndex;
+    if (tabIndexBehavior) {
+        tabIndex = disabled || tabIndexBehavior === "roving" && activeDescendantId ? -1 : 0;
+    }
+    const getFocusableElementsFromRef = useCallback(()=>{
+        const container = nodeRef.current;
+        if (!container) {
+            return [];
+        }
+        return getFocusableElements(container, programmatic);
+    }, [
+        getFocusableElements,
+        nodeRef,
+        programmatic
+    ]);
+    const updateFocusIndex = useCallback((index, focusables = getFocusableElementsFromRef())=>{
+        if (currentFocusIndex.current === index || index === -1) {
+            return;
+        }
+        currentFocusIndex.current = index;
+        const focused = focusables[index];
+        if (tabIndexBehavior) {
+            focused.scrollIntoView({
+                block: "nearest",
+                inline: "nearest"
+            });
+            setActiveDescendantId(focused.id);
+        }
+        if (tabIndexBehavior !== "virtual") {
+            focused.focus();
+        }
+        onFocusChange({
+            index,
+            element: focused
+        });
+    }, [
+        getFocusableElementsFromRef,
+        onFocusChange,
+        tabIndexBehavior
+    ]);
+    const focusNext = useCallback((focusables = getFocusableElementsFromRef())=>{
+        updateFocusIndex(getNextFocusableIndex({
+            loopable,
+            increment: true,
+            focusables,
+            includeDisabled: true,
+            currentFocusIndex: currentFocusIndex.current
+        }), focusables);
+    }, [
+        getFocusableElementsFromRef,
+        loopable,
+        updateFocusIndex
+    ]);
+    const focusPrevious = useCallback((focusables = getFocusableElementsFromRef())=>{
+        updateFocusIndex(getNextFocusableIndex({
+            loopable,
+            increment: false,
+            focusables,
+            includeDisabled: true,
+            currentFocusIndex: currentFocusIndex.current
+        }), focusables);
+    }, [
+        getFocusableElementsFromRef,
+        loopable,
+        updateFocusIndex
+    ]);
+    const focusFirst = useCallback((focusables = getFocusableElementsFromRef())=>{
+        updateFocusIndex(getFirstFocusableIndex({
+            focusables,
+            includeDisabled
+        }), focusables);
+    }, [
+        getFocusableElementsFromRef,
+        includeDisabled,
+        updateFocusIndex
+    ]);
+    const focusLast = useCallback((focusables = getFocusableElementsFromRef())=>{
+        updateFocusIndex(getLastFocusableIndex({
+            focusables,
+            includeDisabled
+        }), focusables);
+    }, [
+        getFocusableElementsFromRef,
+        includeDisabled,
+        updateFocusIndex
+    ]);
+    const focusFromKey = useCallback((options)=>{
+        const { key, reversed, focusables = getFocusableElementsFromRef() } = options;
+        if (!searchable) {
+            return;
+        }
+        const index = findMatchIndex({
+            value: key,
+            values: focusables.map((element)=>getSearchText(element, !isNotFocusable(element, includeDisabled))),
+            startIndex: reversed ? -1 : currentFocusIndex.current
+        });
+        updateFocusIndex(index, focusables);
+    }, [
+        getFocusableElementsFromRef,
+        includeDisabled,
+        searchable,
+        updateFocusIndex
+    ]);
     const movementContext = useMemo(()=>({
             config,
             loopable,
             searchable,
             horizontal,
+            focusFirst,
+            focusLast,
+            focusNext,
+            focusPrevious,
+            focusFromKey,
             includeDisabled,
             tabIndexBehavior,
             activeDescendantId
         }), [
         activeDescendantId,
+        focusFirst,
+        focusFromKey,
+        focusLast,
+        focusNext,
+        focusPrevious,
         horizontal,
         includeDisabled,
         loopable,
         searchable,
         tabIndexBehavior
     ]);
-    const currentFocusIndex = useRef(-1);
-    const mode = useUserInteractionMode();
-    const refocus = useRef(false);
-    if (process.env.NODE_ENV !== "production") {
-        // this fixes issues during hot reloading and using the `useId()` hook
-        // eslint-disable-next-line react-hooks/rules-of-hooks
-        useEffect(()=>{
-            return ()=>{
-                setActiveDescendantId("");
-            };
-        }, []);
-    }
-    let tabIndex;
-    if (tabIndexBehavior) {
-        tabIndex = disabled || tabIndexBehavior === "roving" && activeDescendantId ? -1 : 0;
-    }
     return {
+        nodeRef,
         movementProps: {
             "aria-activedescendant": tabIndexBehavior === "virtual" ? activeDescendantId : undefined,
+            ref: nodeRefCallback,
             tabIndex,
             // Note: This used to be on the `onFocus` event, but this causes issues in
             // Chromium browsers for drag and drop behavior
@@ -312,25 +433,7 @@ const returnNegative1 = ()=>-1;
                 const setFocusIndex = (index, focusables)=>{
                     event.preventDefault();
                     event.stopPropagation();
-                    if (currentFocusIndex.current === index || index === -1) {
-                        return;
-                    }
-                    currentFocusIndex.current = index;
-                    const focused = focusables[index];
-                    if (tabIndexBehavior) {
-                        focused.scrollIntoView({
-                            block: "nearest",
-                            inline: "nearest"
-                        });
-                        setActiveDescendantId(focused.id);
-                    }
-                    if (tabIndexBehavior !== "virtual") {
-                        focused.focus();
-                    }
-                    onFocusChange({
-                        index,
-                        element: focused
-                    });
+                    updateFocusIndex(index, focusables);
                 };
                 extendKeyDown({
                     event,
@@ -368,44 +471,39 @@ const returnNegative1 = ()=>-1;
                 }
                 const { incrementKeys, decrementKeys, jumpToFirstKeys, jumpToLastKeys } = config.current;
                 if (searchable && isSearchableEvent(event)) {
-                    const focusables = getFocusableElements(currentTarget, programmatic);
-                    const index = findMatchIndex({
-                        value: key,
-                        values: focusables.map((element)=>getSearchText(element, !isNotFocusable(element, includeDisabled))),
-                        startIndex: shiftKey ? -1 : currentFocusIndex.current
+                    event.preventDefault();
+                    event.stopPropagation();
+                    focusFromKey({
+                        key,
+                        reversed: shiftKey
                     });
-                    setFocusIndex(index, focusables);
+                    return;
+                }
+                if (trackTabKeys && key === "Tab") {
+                    currentFocusIndex.current += event.shiftKey ? -1 : 1;
                     return;
                 }
                 const jumpToFirst = jumpToFirstKeys.includes(key);
                 const jumpToLast = !jumpToFirst && jumpToLastKeys.includes(key);
                 const increment = !jumpToFirst && !jumpToLast && incrementKeys.includes(key);
                 const decrement = !jumpToFirst && !jumpToLast && !increment && decrementKeys.includes(key);
-                if (!jumpToFirst && !jumpToLast && !increment && !decrement) {
-                    return;
-                }
-                const focusables = getFocusableElements(currentTarget, programmatic);
-                let index;
                 if (jumpToFirst) {
-                    index = getFirstFocusableIndex({
-                        focusables,
-                        includeDisabled
-                    });
+                    event.preventDefault();
+                    event.stopPropagation();
+                    focusFirst();
                 } else if (jumpToLast) {
-                    index = getLastFocusableIndex({
-                        focusables,
-                        includeDisabled
-                    });
-                } else {
-                    index = getNextFocusableIndex({
-                        loopable,
-                        increment,
-                        focusables,
-                        includeDisabled,
-                        currentFocusIndex: currentFocusIndex.current
-                    });
+                    event.preventDefault();
+                    event.stopPropagation();
+                    focusLast();
+                } else if (increment) {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    focusNext();
+                } else if (decrement) {
+                    event.preventDefault();
+                    event.stopPropagation();
+                    focusPrevious();
                 }
-                setFocusIndex(index, focusables);
             }
         },
         movementContext,