@react-md/core 6.2.1 → 6.3.0

package/src/form/useTextField.ts

@@ -20,6 +20,7 @@ import {
   type FormMessageInputLengthCounterProps,
   type FormMessageProps,
 } from "./types.js";
+import { useFormReset } from "./useFormReset.js";
 import {
   type ErrorMessageOptions,
   type GetErrorIcon,
@@ -41,12 +42,12 @@ const noop = (): void => {
  * @since 6.0.0 Added the `onInvalid` handler
  */
 export type TextFieldChangeHandlers<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > = Pick<HTMLAttributes<E>, "onBlur" | "onChange" | "onInvalid">;
 
 /** @since 6.0.0 */
 export interface ErrorChangeHandlerOptions<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > {
   /**
    * A ref containing the `TextField` or `TextArea` if you need access to that
@@ -94,7 +95,7 @@ export interface ErrorChangeHandlerOptions<
  * @since 6.0.0 Changed to object argument.
  */
 export type ErrorChangeHandler<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > = (options: ErrorChangeHandlerOptions<E>) => void;
 
 /** @since 2.5.6 */
@@ -135,7 +136,7 @@ export interface ProvidedFormMessageProps
  * @since 2.5.0
  */
 export interface ProvidedTextFieldProps<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > extends TextFieldValidationOptions,
     TextFieldChangeHandlers<E>,
     Required<Pick<TextFieldProps, "id" | "name" | "value" | "error">>,
@@ -153,7 +154,7 @@ export interface ProvidedTextFieldProps<
  * @since 2.5.0
  */
 export interface ProvidedTextFieldMessageProps<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > extends ProvidedTextFieldProps<E> {
   /**
    * These props will be defined as long as the `disableMessage` prop is not
@@ -162,52 +163,30 @@ export interface ProvidedTextFieldMessageProps<
   messageProps: ProvidedFormMessageProps;
 }
 
-/** @since 2.5.6 */
-export interface TextFieldHookOptions<
-  E extends HTMLInputElement | HTMLTextAreaElement,
-> extends TextFieldValidationOptions,
-    TextFieldChangeHandlers<E> {
+/**
+ * @since 6.3.0
+ */
+export interface TextFieldHookComponentOptions<
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+> {
   /**
-   * An optional id to use for the `TextField` or `TextArea` that is also used
-   * to create an id for the inline help/error messages.
+   * An optional id to use for the `TextField`, `Password`, or `TextArea` that
+   * is also used to create an id for the inline help/error messages.
    *
    * @defaultValue `"text-field-" + useId()`
    */
   id?: string;
 
   /**
-   * An optional ref that should be merged with the ref returned by this hook.
-   * This should really only be used if you are making a custom component using
-   * this hook and forwarding refs. If you need a ref to access the `<input>` or
-   * `<textarea>` DOM node, you can use the `fieldRef` returned by this hook
-   * instead.
-   *
-   * @example Accessing TextField DOM Node
-   * ```tsx
-   * import { TextField } from "@react-md/core/form/TextField";
-   * import { useTextField } from "@react-md/core/form/useTextField";
-   * import { useEffect } from "react";
-   * import type { ReactElement } from "react";
-   *
-   * function Example(): ReactElement {
-   *   const { fieldRef, fieldProps } = useTextField({ name: "example" });
-   *
-   *   useEffect(() => {
-   *     fieldRef.current;
-   *     //       ^ HTMLInputElement | null
-   *   }, [fieldRef]);
-   *
-   *   return <TextField {...fieldProps} label="Example" />;
-   * }
-   * ```
+   * A unique name to attach to the `TextField`, `TextArea`, or `Password`
+   * component.
    */
-  ref?: Ref<E>;
+  name: string;
 
   /**
-   * A unique name to attach to the `TextField`, `TextArea` or `Password`
-   * component.
+   * @since 6.3.0
    */
-  name: string;
+  form?: string;
 
   /**
    * Boolean if the `FormMessage` should also display a counter for the
@@ -220,25 +199,6 @@ export interface TextFieldHookOptions<
    */
   counter?: boolean;
 
-  /**
-   * This is used internally for the `useNumberField` hook and probably
-   * shouldn't be used otherwise. This is just passed into the
-   * {@link getErrorMessage} options and is used for additional validation.
-   *
-   * @defaultValue `false`
-   */
-  isNumber?: boolean;
-
-  /**
-   * The default value to use for the `TextField` or `TextArea` one initial
-   * render. If you want to manually change the value to something else after
-   * the initial render, either change the `key` for the component containing
-   * this hook, or use the `setState` function returned from this hook.
-   *
-   * @defaultValue `""`
-   */
-  defaultValue?: UseStateInitializer<string>;
-
   /**
    * An optional help text to display in the `FormMessage` component when there
    * is not an error.
@@ -289,6 +249,15 @@ export interface TextFieldHookOptions<
    */
   onErrorChange?: ErrorChangeHandler<E>;
 
+  /**
+   * Set to `true` to prevent the state from automatically resetting with a
+   * form's `reset` event.
+   *
+   * @defaultValue `false`
+   * @since 6.3.0
+   */
+  disableReset?: boolean;
+
   /**
    * Set this to `true` to prevent the `errorMessage` from being
    * rendered inline below the `TextField`.
@@ -316,9 +285,63 @@ export interface TextFieldHookOptions<
   validationType?: TextFieldValidationType;
 }
 
+/** @since 2.5.6 */
+export interface TextFieldHookOptions<
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+> extends TextFieldValidationOptions,
+    TextFieldHookComponentOptions<E>,
+    TextFieldChangeHandlers<E> {
+  /**
+   * An optional ref that should be merged with the ref returned by this hook.
+   * This should really only be used if you are making a custom component using
+   * this hook and forwarding refs. If you need a ref to access the `<input>` or
+   * `<textarea>` DOM node, you can use the `fieldRef` returned by this hook
+   * instead.
+   *
+   * @example Accessing TextField DOM Node
+   * ```tsx
+   * import { TextField } from "@react-md/core/form/TextField";
+   * import { useTextField } from "@react-md/core/form/useTextField";
+   * import { useEffect } from "react";
+   * import type { ReactElement } from "react";
+   *
+   * function Example(): ReactElement {
+   *   const { fieldRef, fieldProps } = useTextField({ name: "example" });
+   *
+   *   useEffect(() => {
+   *     fieldRef.current;
+   *     //       ^ HTMLInputElement | null
+   *   }, [fieldRef]);
+   *
+   *   return <TextField {...fieldProps} label="Example" />;
+   * }
+   * ```
+   */
+  ref?: Ref<E>;
+
+  /**
+   * This is used internally for the `useNumberField` hook and probably
+   * shouldn't be used otherwise. This is just passed into the
+   * {@link getErrorMessage} options and is used for additional validation.
+   *
+   * @defaultValue `false`
+   */
+  isNumber?: boolean;
+
+  /**
+   * The default value to use for the `TextField` or `TextArea` one initial
+   * render. If you want to manually change the value to something else after
+   * the initial render, either change the `key` for the component containing
+   * this hook, or use the `setState` function returned from this hook.
+   *
+   * @defaultValue `""`
+   */
+  defaultValue?: UseStateInitializer<string>;
+}
+
 /** @since 6.0.0 */
 export interface TextFieldImplementation<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > extends TextFieldHookState {
   fieldRef: RefObject<E>;
   reset: () => void;
@@ -328,14 +351,14 @@ export interface TextFieldImplementation<
 
 /** @since 6.0.0 */
 export interface TextFieldWithMessageImplementation<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > extends TextFieldImplementation<E> {
   fieldProps: ProvidedTextFieldMessageProps<E>;
 }
 
 /** @since 6.0.0 */
 export interface ValidatedTextFieldImplementation<
-  E extends HTMLInputElement | HTMLTextAreaElement,
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
 > extends TextFieldImplementation<E> {
   fieldProps: ProvidedTextFieldProps<E> | ProvidedTextFieldMessageProps<E>;
 }
@@ -365,7 +388,9 @@ export interface ValidatedTextFieldImplementation<
  * @see {@link https://react-md.dev/components/text-field | TextField Demos}
  * @see {@link https://react-md.dev/hooks/use-text-field | useTextField Demos}
  */
-export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
+export function useTextField<
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+>(
   options: TextFieldHookOptions<E> & { disableMessage: true }
 ): TextFieldImplementation<E>;
 
@@ -481,21 +506,22 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * added the ability to display an inline counter and help text while disabling
  * the error messaging.
  */
-export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
-  options: TextFieldHookOptions<E>
-): TextFieldWithMessageImplementation<E>;
+export function useTextField<
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+>(options: TextFieldHookOptions<E>): TextFieldWithMessageImplementation<E>;
 /**
  * @see {@link https://react-md.dev/components/text-field | TextField Demos}
  * @see {@link https://react-md.dev/hooks/use-text-field | useTextField Demos}
  * @since 6.0.0
  */
-export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
-  options: TextFieldHookOptions<E>
-): ValidatedTextFieldImplementation<E> {
+export function useTextField<
+  E extends HTMLInputElement | HTMLTextAreaElement = HTMLInputElement,
+>(options: TextFieldHookOptions<E>): ValidatedTextFieldImplementation<E> {
   const {
     id: propId,
     ref: propRef,
     name,
+    form,
     defaultValue = "",
     isNumber = false,
     required,
@@ -507,6 +533,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
     onInvalid = noop,
     counter = false,
     helpText,
+    disableReset,
     validationType = "recommended",
     disableMessage = false,
     disableMaxLength = false,
@@ -712,6 +739,12 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
     };
   }
 
+  useFormReset({
+    form,
+    onReset: disableReset ? undefined : reset,
+    elementRef: fieldRef,
+  });
+
   return {
     ...state,
     reset,

package/src/interaction/utils.ts

@@ -1,37 +1,35 @@
 import { type KeyboardEvent, type MouseEvent, type TouchEvent } from "react";
 
 import { findSizingContainer } from "../positioning/utils.js";
+import { type Point } from "../types.js";
+import { calcHypotenuse } from "../utils/trigonometry.js";
 import {
   type ElementInteractionState,
   type RippleState,
   type RippleStyle,
 } from "./types.js";
 
-/** @internal */
-function calcHypotenuse(a: number, b: number): number {
-  return Math.sqrt(a * a + b * b);
+/**
+ * @internal
+ * @since 6.3.0
+ */
+interface GetRadiusOptions extends Point {
+  height: number;
+  width: number;
 }
 
 /**
- * Gets the current radius for a ripple based on the x and y page dimensions
- * as well as the size of the element.
- *
- * This is really just in a separate file so I can easily mock this and write
- * tests.
- *
  * @internal
+ * @since 6.3.0
  */
-function getRadius(
-  x: number,
-  y: number,
-  offsetWidth: number,
-  offsetHeight: number
-): number {
+export function getRadius(options: GetRadiusOptions): number {
+  const { x, y, height, width } = options;
+
   return Math.max(
-    calcHypotenuse(x, y),
-    calcHypotenuse(offsetWidth - x, y),
-    calcHypotenuse(offsetWidth - x, offsetHeight - y),
-    calcHypotenuse(x, offsetHeight - y)
+    calcHypotenuse({ x, y }),
+    calcHypotenuse({ x: width - x, y }),
+    calcHypotenuse({ x: width - x, y: height - y }),
+    calcHypotenuse({ x, y: height - y })
   );
 }
 
@@ -66,7 +64,7 @@ export function getRippleStyle(
     y = pageY - (top + window.scrollY);
   }
 
-  const radius = getRadius(x, y, width, height);
+  const radius = getRadius({ x, y, width, height });
   const size = radius * 2;
 
   return {

package/src/menu/MenuBar.tsx

@@ -89,6 +89,7 @@ export const MenuBar = forwardRef<HTMLUListElement, MenuBarProps>(
     });
     const { activeId, enableHoverMode } = menuBarContext;
     const { movementProps, movementContext } = useKeyboardMovementProvider({
+      ref,
       onClick,
       onFocus,
       onKeyDown,
@@ -110,7 +111,6 @@ export const MenuBar = forwardRef<HTMLUListElement, MenuBarProps>(
           <List
             {...remaining}
             {...movementProps}
-            ref={ref}
             role="menubar"
             horizontal={horizontal}
           >

package/src/menu/MenuItemTextField.tsx

@@ -8,15 +8,13 @@ import { type PropsWithRef } from "../types.js";
 
 /**
  * @since 5.0.0
+ * @since 6.3.0 Removed the invalid `stretch` prop
  */
 export interface MenuItemTextFieldProps extends TextFieldProps {
   /**
    * Any additional props or a `ref` to apply to the surrounding `<li>` element.
    */
   liProps?: PropsWithRef<HTMLAttributes<HTMLLIElement>>;
-
-  /** @defaultValue `true` */
-  stretch?: boolean;
 }
 
 /**

package/src/menu/MenuWidget.tsx

@@ -84,6 +84,7 @@ export const MenuWidget = forwardRef<HTMLDivElement, MenuWidgetProps>(
       defaultActiveId: id,
     });
     const { movementProps, movementContext } = useKeyboardMovementProvider({
+      ref,
       onClick,
       onFocus(event) {
         onFocus(event);
@@ -110,9 +111,10 @@ export const MenuWidget = forwardRef<HTMLDivElement, MenuWidgetProps>(
           <div
             aria-orientation={horizontal ? "horizontal" : undefined}
             {...remaining}
-            {...(isListbox ? { onClick, onFocus, onKeyDown } : movementProps)}
+            {...(isListbox
+              ? { onClick, onFocus, onKeyDown, ref }
+              : movementProps)}
             id={id}
-            ref={ref}
             role={role}
             className={menu({
               className,

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>;