@react-md/core 6.2.1 → 6.3.1

package/src/movement/constants.ts

@@ -13,24 +13,46 @@ export const DEFAULT_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
   jumpToLastKeys: ["End"],
 };
 
+/**
+ * @since 6.3.0
+ * @internal
+ */
+export const DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP: Readonly<KeyboardMovementConfig> =
+  {
+    incrementKeys: ["ArrowRight"],
+    decrementKeys: ["ArrowLeft"],
+    jumpToFirstKeys: [],
+    jumpToLastKeys: [],
+  };
+
 /**
  * @since 5.1.2
  * @internal
  */
 export const DEFAULT_LTR_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
-  incrementKeys: ["ArrowRight"],
-  decrementKeys: ["ArrowLeft"],
+  ...DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
   jumpToFirstKeys: ["Home"],
   jumpToLastKeys: ["End"],
 };
 
+/**
+ * @since 6.3.0
+ * @internal
+ */
+export const DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP: Readonly<KeyboardMovementConfig> =
+  {
+    incrementKeys: ["ArrowLeft"],
+    decrementKeys: ["ArrowRight"],
+    jumpToFirstKeys: [],
+    jumpToLastKeys: [],
+  };
+
 /**
  * @since 5.1.2
  * @internal
  */
 export const DEFAULT_RTL_KEYBOARD_MOVEMENT: Readonly<KeyboardMovementConfig> = {
-  incrementKeys: ["ArrowLeft"],
-  decrementKeys: ["ArrowRight"],
+  ...DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
   jumpToFirstKeys: ["Home"],
   jumpToLastKeys: ["End"],
 };

package/src/movement/types.ts

@@ -1,16 +1,15 @@
-import type {
-  FocusEvent,
-  FocusEventHandler,
-  KeyboardEvent,
-  KeyboardEventHandler,
-  MouseEvent,
-  MouseEventHandler,
+import {
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type Ref,
+  type RefCallback,
+  type RefObject,
 } from "react";
 
-import type {
-  NonNullMutableRef,
-  NonNullRef,
-  UseStateSetter,
+import {
+  type NonNullMutableRef,
+  type NonNullRef,
+  type UseStateSetter,
 } from "../types.js";
 
 /**
@@ -136,6 +135,23 @@ 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`
@@ -154,6 +170,31 @@ export interface KeyboardMovementContext
    * 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;
 }
 
 /**
@@ -208,20 +249,33 @@ export interface KeyboardMovementExtensionData<E extends HTMLElement>
   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,
+    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;
 
@@ -262,13 +316,24 @@ export interface KeyboardMovementProviderOptions<E extends HTMLElement>
    * @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"`.
@@ -285,9 +350,8 @@ 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>;
 }
 
 /**
@@ -295,6 +359,7 @@ export interface KeyboardMovementProps<E extends HTMLElement> {
  * @internal
  */
 export interface KeyboardMovementProviderImplementation<E extends HTMLElement> {
+  nodeRef: RefObject<E>;
   movementProps: Readonly<KeyboardMovementProps<E>>;
   movementContext: Readonly<KeyboardMovementContext>;
   currentFocusIndex: NonNullMutableRef<number>;

package/src/movement/useKeyboardMovementProvider.ts

@@ -2,6 +2,7 @@
 
 import {
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useMemo,
@@ -12,6 +13,7 @@ import {
 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,
@@ -19,12 +21,13 @@ import {
   DEFAULT_RTL_KEYBOARD_MOVEMENT,
 } from "./constants.js";
 import { findMatchIndex } from "./findMatchIndex.js";
-import type {
-  KeyboardMovementConfig,
-  KeyboardMovementConfiguration,
-  KeyboardMovementContext,
-  KeyboardMovementProviderImplementation,
-  KeyboardMovementProviderOptions,
+import {
+  type KeyboardFocusFromKeyOptions,
+  type KeyboardMovementConfig,
+  type KeyboardMovementConfiguration,
+  type KeyboardMovementContext,
+  type KeyboardMovementProviderImplementation,
+  type KeyboardMovementProviderOptions,
 } from "./types.js";
 import {
   getFirstFocusableIndex,
@@ -38,19 +41,36 @@ import {
   recalculateFocusIndex,
 } from "./utils.js";
 
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * @since 6.3.0
+ */
+export const DEFAULT_KEYBOARD_MOVEMENT_CONTEXT: Readonly<KeyboardMovementContext> =
+  {
+    config: { current: DEFAULT_KEYBOARD_MOVEMENT },
+    loopable: false,
+    searchable: false,
+    horizontal: false,
+    includeDisabled: false,
+    tabIndexBehavior: undefined,
+    activeDescendantId: "",
+    focusFirst: noop,
+    focusLast: noop,
+    focusNext: noop,
+    focusPrevious: noop,
+    focusFromKey: noop,
+  };
+
 /**
  * @since 5.0.0
  * @internal
  */
-const context = createContext<KeyboardMovementContext>({
-  config: { current: DEFAULT_KEYBOARD_MOVEMENT },
-  loopable: false,
-  searchable: false,
-  horizontal: false,
-  includeDisabled: false,
-  tabIndexBehavior: undefined,
-  activeDescendantId: "",
-});
+const context = createContext<KeyboardMovementContext>(
+  DEFAULT_KEYBOARD_MOVEMENT_CONTEXT
+);
 context.displayName = "KeyboardMovement";
 export const { Provider: KeyboardMovementProvider } = context;
 
@@ -62,10 +82,6 @@ export function useKeyboardMovementContext(): Readonly<KeyboardMovementContext>
   return useContext(context);
 }
 
-const noop = (): void => {
-  // do nothing
-};
-
 const returnNegative1 = (): number => -1;
 
 /**
@@ -193,6 +209,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
   options: KeyboardMovementProviderOptions<E> = {}
 ): KeyboardMovementProviderImplementation<E> {
   const {
+    ref: propRef,
     onClick = noop,
     onFocus = noop,
     onKeyDown = noop,
@@ -200,6 +217,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     disabled,
     searchable = false,
     horizontal = false,
+    trackTabKeys = false,
     includeDisabled = false,
     tabIndexBehavior,
     extendKeyDown = noop,
@@ -214,6 +232,8 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     isNegativeOneAllowed = false,
   } = options;
 
+  const [nodeRef, nodeRefCallback] = useEnsuredRef(propRef);
+
   const isRTL = useDir().dir === "rtl";
   let defaults: Readonly<Required<KeyboardMovementConfiguration>>;
   if (horizontal) {
@@ -240,29 +260,10 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
     config.current = configuration;
   });
 
-  const [activeDescendantId, setActiveDescendantId] = useState("");
-  const movementContext = useMemo<KeyboardMovementContext>(
-    () => ({
-      config,
-      loopable,
-      searchable,
-      horizontal,
-      includeDisabled,
-      tabIndexBehavior,
-      activeDescendantId,
-    }),
-    [
-      activeDescendantId,
-      horizontal,
-      includeDisabled,
-      loopable,
-      searchable,
-      tabIndexBehavior,
-    ]
-  );
-  const currentFocusIndex = useRef(-1);
   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
@@ -282,10 +283,155 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
         : 0;
   }
 
+  const getFocusableElementsFromRef = useCallback(() => {
+    const container = nodeRef.current;
+    if (!container) {
+      return [];
+    }
+
+    return getFocusableElements(container, programmatic);
+  }, [getFocusableElements, nodeRef, programmatic]);
+  const updateFocusIndex = useCallback(
+    (index: number, 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: KeyboardFocusFromKeyOptions) => {
+      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<KeyboardMovementContext>(
+    () => ({
+      config,
+      loopable,
+      searchable,
+      horizontal,
+      focusFirst,
+      focusLast,
+      focusNext,
+      focusPrevious,
+      focusFromKey,
+      includeDisabled,
+      tabIndexBehavior,
+      activeDescendantId,
+    }),
+    [
+      activeDescendantId,
+      focusFirst,
+      focusFromKey,
+      focusLast,
+      focusNext,
+      focusPrevious,
+      horizontal,
+      includeDisabled,
+      loopable,
+      searchable,
+      tabIndexBehavior,
+    ]
+  );
+
   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
@@ -411,28 +557,7 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
         ): void => {
           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({
@@ -487,15 +612,14 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
         } = 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,
-          });
-          setFocusIndex(index, focusables);
+          event.preventDefault();
+          event.stopPropagation();
+          focusFromKey({ key, reversed: shiftKey });
+          return;
+        }
+
+        if (trackTabKeys && key === "Tab") {
+          currentFocusIndex.current += event.shiftKey ? -1 : 1;
           return;
         }
 
@@ -509,33 +633,23 @@ export function useKeyboardMovementProvider<E extends HTMLElement>(
           !increment &&
           decrementKeys.includes(key);
 
-        if (!jumpToFirst && !jumpToLast && !increment && !decrement) {
-          return;
-        }
-        const focusables = getFocusableElements(currentTarget, programmatic);
-
-        let index: number;
         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,

package/src/navigation/NavItem.tsx

@@ -1,11 +1,15 @@
 import { type LiHTMLAttributes, type ReactNode, forwardRef } from "react";
 
-import { navItem } from "./navItemStyles.js";
+import { type NavItemClassNameOptions, navItem } from "./navItemStyles.js";
 
 /**
  * @since 6.0.0
+ * @since 6.3.1 Extends NavItemClassNameOptions to allow for CSS properties
+ * augmentation.
  */
-export interface NavItemProps extends LiHTMLAttributes<HTMLLIElement> {
+export interface NavItemProps
+  extends LiHTMLAttributes<HTMLLIElement>,
+    NavItemClassNameOptions {
   children: ReactNode;
 }
 

package/src/navigation/navItemStyles.ts

@@ -6,6 +6,14 @@ import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-nav-item");
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-navigation-border-radius"?: string | number;
+    "--rmd-navigation-horizontal-padding"?: string | number;
+    "--rmd-navigation-padding-incrementor"?: string | number;
+  }
+}
+
 /**
  * @since 6.0.0
  */

package/src/overlay/Overlay.tsx

@@ -3,7 +3,6 @@
 import { type HTMLAttributes, forwardRef } from "react";
 
 import { useSsr } from "../SsrProvider.js";
-import { type BoxAlignItems, type BoxJustifyContent } from "../box/styles.js";
 import { Portal } from "../portal/Portal.js";
 import {
   type CSSTransitionComponentProps,
@@ -11,44 +10,23 @@ import {
 } from "../transition/types.js";
 import { useCSSTransition } from "../transition/useCSSTransition.js";
 import {
+  type BaseOverlayClassNameOptions,
   DEFAULT_OVERLAY_CLASSNAMES,
   DEFAULT_OVERLAY_TIMEOUT,
   overlay,
 } from "./styles.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-overlay-background-color"?: string;
-    "--rmd-overlay-z-index"?: number;
-  }
-}
-
 /**
  * @since 6.0.0 Added `align` and `justify` props.
  * @since 6.0.0 Renamed `hidden` to `noOpacity`.
+ * @since 6.3.1 Extends BaseOverlayClassNameOptions for CSSProperties module
+ * augmentation.
  */
 export interface OverlayProps
   extends HTMLAttributes<HTMLSpanElement>,
+    BaseOverlayClassNameOptions,
     CSSTransitionComponentProps,
     TransitionActions {
-  /**
-   * @defaultValue `"center"`
-   * @since 6.0.0
-   */
-  align?: BoxAlignItems;
-
-  /**
-   * @defaultValue `"center"`
-   * @since 6.0.0
-   */
-  justify?: BoxJustifyContent;
-
-  /**
-   * Set this to `true` for when the overlay should be visible. Toggling this
-   * value will trigger the enter/exit animation.
-   */
-  visible: boolean;
-
   /**
    * Set this to `true` if the overlay should be rendered with an `opacity: 0`
    * and disabling the animation. This is useful if you'd like a "close on