@react-md/core 6.2.1 → 6.3.0

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/tabs/useTabList.ts

@@ -176,6 +176,7 @@ export function useTabList(
   const forwardRef = useRef<HTMLDivElement>(null);
   const backwardRef = useRef<HTMLDivElement>(null);
   const { movementProps, movementContext } = useKeyboardMovementProvider({
+    ref: tabListRef,
     onClick(event) {
       onClick(event);
       if (event.isPropagationStopped() || !(event.target instanceof Element)) {
@@ -226,7 +227,6 @@ export function useTabList(
   return {
     elementProps: {
       "aria-orientation": vertical ? "vertical" : "horizontal",
-      ref: tabListRef,
       style: {
         ...style,
         ...(disableTransition ? undefined : indicatorStyles),

package/src/test-utils/drag.ts

@@ -1,25 +1,21 @@
 import { fireEvent } from "@testing-library/dom";
 import type { MouseEvent } from "react";
 
+import { type Point } from "../types.js";
 import { wait } from "../utils/wait.js";
 
-interface XYCoords {
-  x: number;
-  y: number;
-}
-
 interface BaseDragOptions {
-  to?: XYCoords | Element;
-  from?: XYCoords;
-  delta?: XYCoords;
+  to?: Point | Element;
+  from?: Point;
+  delta?: Point;
   steps?: number;
   duration?: number;
 }
 
 type DragOptions = BaseDragOptions &
-  ({ to: XYCoords | Element; delta?: never } | { delta: XYCoords; to?: never });
+  ({ to: Point | Element; delta?: never } | { delta: Point; to?: never });
 
-const getElementClientCenter = (element: Element): XYCoords => {
+const getElementClientCenter = (element: Element): Point => {
   const { left, top, width, height } = element.getBoundingClientRect();
   return {
     x: left + width / 2,
@@ -27,7 +23,7 @@ const getElementClientCenter = (element: Element): XYCoords => {
   };
 };
 
-const getCoords = (elementOrCoords: Element | XYCoords): XYCoords =>
+const getCoords = (elementOrCoords: Element | Point): Point =>
   "x" in elementOrCoords && "y" in elementOrCoords
     ? elementOrCoords
     : getElementClientCenter(elementOrCoords);
@@ -58,7 +54,7 @@ export async function drag(
       }
     : getCoords(inTo);
 
-  const step: XYCoords = {
+  const step: Point = {
     x: (to.x - from.x) / steps,
     y: (to.y - from.y) / steps,
   };

package/src/transition/useCarousel.ts

@@ -2,10 +2,10 @@
 
 import { useCallback, useEffect, useState } from "react";
 
-import type { UseStateSetter } from "../types.js";
+import { type UseStateSetter } from "../types.js";
 import { useToggle } from "../useToggle.js";
 import { loop } from "../utils/loop.js";
-import type { SlideDirection } from "./SlideContainer.js";
+import { type SlideDirection } from "./SlideContainer.js";
 
 /** @since 6.0.0 */
 export interface CarouselSlideState {

package/src/tree/Tree.tsx

@@ -270,6 +270,7 @@ export function Tree<T extends TreeItemNode>(
   });
 
   const { metadataLookup, movementContext, movementProps } = useTreeMovement({
+    ref: treeRef,
     onClick,
     onFocus,
     onKeyDown,
@@ -305,7 +306,6 @@ export function Tree<T extends TreeItemNode>(
           {...remaining}
           {...movementProps}
           id={treeId}
-          ref={treeRef}
           role="tree"
           tabIndex={0}
           className={tree({ className })}

package/src/tree/useTreeMovement.ts

@@ -4,6 +4,7 @@ import type {
   FocusEventHandler,
   KeyboardEventHandler,
   MouseEventHandler,
+  Ref,
 } from "react";
 import { useRef } from "react";
 
@@ -59,6 +60,7 @@ const getVisibleTreeItems = (
  * @internal
  */
 interface TreeMovementOptions<T extends TreeItemNode> extends TreeExpansion {
+  ref?: Ref<HTMLUListElement>;
   data: TreeData<T>;
   onClick: MouseEventHandler<HTMLUListElement> | undefined;
   onFocus: FocusEventHandler<HTMLUListElement> | undefined;
@@ -88,6 +90,7 @@ export function useTreeMovement<T extends TreeItemNode>(
   options: TreeMovementOptions<T>
 ): TreeMovement {
   const {
+    ref,
     onClick,
     onFocus,
     onKeyDown,
@@ -106,6 +109,7 @@ export function useTreeMovement<T extends TreeItemNode>(
     itemToElement: {},
   });
   const movement = useKeyboardMovementProvider({
+    ref,
     onClick,
     onFocus,
     onKeyDown,

package/src/types.ts

@@ -227,6 +227,22 @@ export interface ElementSize {
   width: number;
 }
 
+/**
+ * @since 6.3.0
+ */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * @since 6.3.0
+ */
+export interface MinMaxRange {
+  min: number;
+  max: number;
+}
+
 /**
  * @since 6.2.0
  */

package/src/utils/getMiddleOfRange.ts

@@ -1,12 +1,11 @@
+import { type MinMaxRange } from "../types.js";
 import { getRangeSteps } from "./getRangeSteps.js";
 import { nearest } from "./nearest.js";
 
 /**
  * @since 6.0.0
  */
-export interface GetMiddleOfRangeOptions {
-  min: number;
-  max: number;
+export interface GetMiddleOfRangeOptions extends MinMaxRange {
   step: number;
 }
 

package/src/utils/getPercentage.ts

@@ -1,15 +1,7 @@
-/** @since 4.0.1 */
-export interface GetPercentageOptions {
-  /**
-   * The min value allowed.
-   */
-  min: number;
-
-  /**
-   * The max value allowed.
-   */
-  max: number;
+import { type MinMaxRange } from "../types.js";
 
+/** @since 4.0.1 */
+export interface GetPercentageOptions extends MinMaxRange {
   /**
    * The current value
    */

package/src/utils/getRangeSteps.ts

@@ -1,10 +1,10 @@
+import { type MinMaxRange } from "../types.js";
+
 /**
  * @internal
  * @since 6.0.0
  */
-export interface RangeStepsOptions {
-  min: number;
-  max: number;
+export interface RangeStepsOptions extends MinMaxRange {
   step: number;
 }
 

package/src/utils/nearest.ts

@@ -1,10 +1,10 @@
+import { type MinMaxRange } from "../types.js";
+
 /**
  * @internal
  * @since 6.0.0
  */
-export interface NearestOptions {
-  min: number;
-  max: number;
+export interface NearestOptions extends MinMaxRange {
   steps: number;
   value: number;
 

package/src/utils/trigonometry.ts

@@ -0,0 +1,46 @@
+import { type Point } from "../types.js";
+
+/**
+ * @since 6.3.0
+ * @internal
+ */
+export const radiansToDegrees = (radians: number): number =>
+  (radians * 180) / Math.PI;
+
+/**
+ * @since 6.3.0
+ * @internal
+ */
+export const degreesToRadians = (degrees: number): number =>
+  (degrees * Math.PI) / 180;
+
+/**
+ * @since 6.3.0
+ * @internal
+ */
+interface IsPointInCircleOptions {
+  point: Point;
+  center: Point;
+  radius: number;
+}
+
+/**
+ * @since 6.3.0
+ * @internal
+ */
+export function isPointInCircle(options: IsPointInCircleOptions): boolean {
+  const { point, center, radius } = options;
+
+  const distance = (center.x - point.x) ** 2 + (center.y - point.y) ** 2;
+  return distance <= radius ** 2;
+}
+
+/**
+ * @internal
+ * @since 6.3.0
+ */
+export function calcHypotenuse(point: Point): number {
+  const { x, y } = point;
+
+  return Math.sqrt(x * x + y * y);
+}

package/src/window-splitter/useWindowSplitter.ts

@@ -42,8 +42,9 @@ export type WindowSplitterOptions<E extends HTMLElement = HTMLButtonElement> =
 /**
  * @since 6.0.0
  */
-export interface WindowSplitterWidgetProps<E extends HTMLElement>
-  extends Required<DraggableMouseEventHandlers<E>>,
+export interface WindowSplitterWidgetProps<
+  E extends HTMLElement = HTMLButtonElement,
+> extends Required<DraggableMouseEventHandlers<E>>,
     Required<DraggableKeyboardEventHandlers<E>> {
   "aria-orientation": "vertical" | undefined;
   "aria-valuenow": number;