@react-md/core 6.2.1 → 6.3.1

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/types.ts

@@ -8,7 +8,6 @@ import type {
 
 declare module "react" {
   interface CSSProperties {
-    "--rmd-ripple-background-color"?: string;
     "--rmd-interaction-background-color"?: string;
     "--rmd-hover-background-color"?: string;
     "--rmd-focus-background-color"?: string;
@@ -16,6 +15,11 @@ declare module "react" {
     "--rmd-selected-background-color"?: string;
     "--rmd-focus-color"?: string;
     "--rmd-focus-width"?: string | number;
+    "--rmd-ripple-inset"?: string | number;
+    "--rmd-ripple-border-radius"?: string | number;
+    "--rmd-ripple-background-color"?: string;
+    "--rmd-surface-inset"?: string | number;
+    "--rmd-surface-border-radius"?: string | number;
   }
 }
 

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/link/Link.tsx

@@ -6,14 +6,6 @@ import {
 
 import { type LinkClassNameOptions, link } from "./styles.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-link-color"?: string;
-    "--rmd-link-visited-color"?: string;
-    "--rmd-link-hover-color"?: string;
-  }
-}
-
 /**
  * @since 6.0.0
  */

package/src/link/styles.ts

@@ -4,6 +4,14 @@ import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-link");
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-link-color"?: string;
+    "--rmd-link-visited-color"?: string;
+    "--rmd-link-hover-color"?: string;
+  }
+}
+
 /** @since 6.0.0 */
 export interface LinkClassNameOptions {
   className?: string;

package/src/list/List.tsx

@@ -1,30 +1,20 @@
 import { type HTMLAttributes, forwardRef } from "react";
 
-import { list } from "./listStyles.js";
-
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-list-padding-h"?: string | number;
-    "--rmd-list-padding-v"?: string | number;
-  }
-}
+import { type ListClassNameOptions, list } from "./listStyles.js";
 
 export type ListElement = HTMLUListElement | HTMLOListElement;
 
-export interface ListProps extends HTMLAttributes<ListElement> {
+/**
+ * @since 6.3.1 Extends the ListClassNameOptions
+ */
+export interface ListProps
+  extends HTMLAttributes<ListElement>,
+    ListClassNameOptions {
   /**
    * @defaultValue `"none"`
    */
   role?: HTMLAttributes<ListElement>["role"];
 
-  /**
-   * Set to `true` to decrease the amount of padding and font size within the
-   * list.
-   *
-   * @defaultValue `false`
-   */
-  dense?: boolean;
-
   /**
    * Set this to `true` to render as `<ol>` instead of `<ul>` when the children
    * are in a specific order. For example: steps within a recipe.
@@ -32,13 +22,6 @@ export interface ListProps extends HTMLAttributes<ListElement> {
    * @defaultValue `false`
    */
   ordered?: boolean;
-
-  /**
-   * Set this to `true` to render horizontally instead of vertically.
-   *
-   * @defaultValue `false`
-   */
-  horizontal?: boolean;
 }
 
 /**

package/src/list/ListItem.tsx

@@ -7,33 +7,21 @@ import { useElementInteraction } from "../interaction/useElementInteraction.js";
 import { useHigherContrastChildren } from "../interaction/useHigherContrastChildren.js";
 import { ListItemChildren } from "./ListItemChildren.js";
 import { getListItemHeight } from "./getListItemHeight.js";
-import { listItem } from "./listItemStyles.js";
-import { type ListItemChildrenProps, type ListItemHeight } from "./types.js";
-
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-list-item-keyline"?: string | number;
-    "--rmd-list-item-padding-h"?: string | number;
-    "--rmd-list-item-padding-v"?: string | number;
-    "--rmd-list-item-height"?: string | number;
-    "--rmd-list-item-medium-height"?: string | number;
-    "--rmd-list-item-large-height"?: string | number;
-    "--rmd-list-item-extra-large-height"?: string | number;
-    "--rmd-list-item-multiline-clamp"?: string | number;
-    "--rmd-list-item-multiline-height"?: string | number;
-    "--rmd-list-item-media-size"?: string | number;
-    "--rmd-list-item-media-spacing"?: string | number;
-    "--rmd-list-item-text-multiline-height"?: string | number;
-  }
-}
+import {
+  type BaseListItemClassNameOptions,
+  listItem,
+} from "./listItemStyles.js";
+import { type ListItemChildrenProps } from "./types.js";
 
 /**
  * @since 6.0.0 Renamed `threeLines` to `multiline` since it can
  * support more than three lines of text.
+ * @since 6.3.1 Extends the BaseListItemClassNameOptions
  */
 export interface ListItemProps
   extends HTMLAttributes<HTMLLIElement>,
     ListItemChildrenProps,
+    BaseListItemClassNameOptions,
     ComponentWithRippleProps {
   /**
    * @defaultValue `"button"`
@@ -45,30 +33,6 @@ export interface ListItemProps
    */
   tabIndex?: number;
 
-  /**
-   * @see {@link ListItemHeight}
-   * @defaultValue `"auto"`
-   */
-  height?: ListItemHeight;
-
-  /**
-   * @defaultValue `false`
-   */
-  multiline?: boolean;
-
-  /**
-   * @defaultValue `false`
-   */
-  disabled?: boolean;
-
-  /**
-   * Note: This does nothing if the `disabled` prop is not enabled.
-   *
-   * @defaultValue `false`
-   * @since 2.4.3
-   */
-  disabledOpacity?: boolean;
-
   /**
    * Set this to `false` if the list item should not gain the interaction
    * states: hover, focus, press, etc. This is kind of like being disabled

package/src/list/listItemStyles.ts

@@ -10,9 +10,27 @@ import {
 
 const styles = bem("rmd-list-item");
 
-/** @since 6.0.0 */
-export interface ListItemClassNameOptions {
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-list-item-keyline"?: string | number;
+    "--rmd-list-item-padding-h"?: string | number;
+    "--rmd-list-item-padding-v"?: string | number;
+    "--rmd-list-item-height"?: string | number;
+    "--rmd-list-item-medium-height"?: string | number;
+    "--rmd-list-item-large-height"?: string | number;
+    "--rmd-list-item-extra-large-height"?: string | number;
+    "--rmd-list-item-multiline-height"?: string | number;
+    "--rmd-list-item-media-size"?: string | number;
+    "--rmd-list-item-media-spacing"?: string | number;
+    "--rmd-list-item-text-multiline-height"?: string | number;
+    "--rmd-list-item-multiline-clamp"?: string | number;
+  }
+}
+
+/** @since 6.3.1 */
+export interface BaseListItemClassNameOptions {
   className?: string;
+
   /**
    * @see {@link ListItemHeight}
    * @defaultValue `"auto"`
@@ -25,7 +43,10 @@ export interface ListItemClassNameOptions {
   multiline?: boolean;
 
   /**
+   * Note: This does nothing if the `disabled` prop is not enabled.
+   *
    * @defaultValue `false`
+   * @since 2.4.3
    */
   disabled?: boolean;
 
@@ -36,7 +57,10 @@ export interface ListItemClassNameOptions {
    * @since 2.4.3
    */
   disabledOpacity?: boolean;
+}
 
+/** @since 6.0.0 */
+export interface ListItemClassNameOptions extends BaseListItemClassNameOptions {
   /**
    * Set this to `false` if the list item should not gain the interaction
    * states: hover, focus, press, etc. This is kind of like being disabled

package/src/list/listStyles.ts

@@ -4,14 +4,30 @@ import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-list");
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-list-padding-h"?: string | number;
+    "--rmd-list-padding-v"?: string | number;
+  }
+}
+
 /** @since 6.0.0 */
 export interface ListClassNameOptions {
   className?: string;
 
-  /** @defaultValue `false` */
+  /**
+   * Set to `true` to decrease the amount of padding and font size within the
+   * list.
+   *
+   * @defaultValue `false`
+   */
   dense?: boolean;
 
-  /** @defaultValue `false` */
+  /**
+   * Set this to `true` to render horizontally instead of vertically.
+   *
+   * @defaultValue `false`
+   */
   horizontal?: boolean;
 }
 

package/src/menu/Menu.tsx

@@ -40,6 +40,8 @@ import { MenuWidget } from "./MenuWidget.js";
 import { useMenuBarContext } from "./useMenuBarProvider.js";
 import { getDefaultAnchor } from "./utils.js";
 
+// NOTE: The augmentation is in this file since no types are imported from the
+// `styles` file at this time
 declare module "react" {
   interface CSSProperties {
     "--rmd-menu-background-color"?: string;

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,