@react-md/core 1.0.0-next.19 → 1.0.0-next.20

package/src/form/useTextField.ts

@@ -1,15 +1,17 @@
 "use client";
+
 import {
-  useCallback,
-  useRef,
-  useState,
   type HTMLAttributes,
   type ReactNode,
   type Ref,
   type RefCallback,
   type RefObject,
+  useCallback,
+  useRef,
+  useState,
 } from "react";
-import { getIcon } from "../icon/iconConfig.js";
+
+import { getIcon } from "../icon/config.js";
 import { type UseStateInitializer, type UseStateSetter } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
@@ -19,15 +21,15 @@ import {
   type FormMessageProps,
 } from "./types.js";
 import {
-  defaultGetErrorIcon,
-  defaultGetErrorMessage,
-  defaultIsErrored,
   type ErrorMessageOptions,
   type GetErrorIcon,
   type GetErrorMessage,
   type IsErrored,
   type TextFieldValidationOptions,
   type TextFieldValidationType,
+  defaultGetErrorIcon,
+  defaultGetErrorMessage,
+  defaultIsErrored,
 } from "./validation.js";
 
 const noop = (): void => {
@@ -287,11 +289,12 @@ export interface TextFieldHookOptions<
   onErrorChange?: ErrorChangeHandler<E>;
 
   /**
-   * Boolean if the `TextField` or `TextArea` will **not** be rendered along
-   * with a `FormMessage` component. This will prevent the `aria-describedby`
-   * prop from being returned when set to `true`.
+   * Set this to `true` to prevent the `errorMessage` from being
+   * rendered inline below the `TextField`.
    *
    * @defaultValue `false`
+   * @since 6.0.0 Only disables the `errorMessage` behavior so
+   * that counters and help text can still be rendered easily.
    */
   disableMessage?: boolean;
 
@@ -342,8 +345,9 @@ export interface ValidatedTextFieldImplementation<
  *
  * @example No Inline Error Messages
  * ```tsx
- * import type { ReactElement } from "react";
- * import { TextField, useTextField } from "@react-md/core";
+ * import { type ReactElement } from "react";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useTextField } from "@react-md/core/form/useTextField";
  *
  * function Example(): ReactElement {
  *   const { fieldProps } = useTextField({
@@ -364,8 +368,9 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
 /**
  * @example Simple Example
  * ```tsx
- * import type { ReactElement } from "react";
- * import { TextField, useTextField } from "@react-md/core";
+ * import { type ReactElement } from "react";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useTextField } from "@react-md/core/form/useTextField";
  *
  * function Example(): ReactElement {
  *   const { fieldProps } = useTextField({
@@ -378,8 +383,9 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  *
  * @example Inline Counter
  * ```tsx
- * import type { ReactElement } from "react";
- * import { TextField, useTextField } from "@react-md/core";
+ * import { type ReactElement } from "react";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useTextField } from "@react-md/core/form/useTextField";
  *
  * function Example(): ReactElement {
  *   const { fieldProps } = useTextField({
@@ -387,6 +393,8 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  *     counter: true,
  *     required: true,
  *     maxLength: 20,
+ *     // this allows the user to type beyond the max length limit and display
+ *     // an error message. omit or set to `false` to enforce the max length instead
  *     disableMaxLength: true,
  *   });
  *
@@ -396,8 +404,9 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  *
  * @example Adding Constraints
  * ```tsx
- * import type { ReactElement } from "react";
- * import { TextField, useTextField } from "@react-md/core";
+ * import { type ReactElement } from "react";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useTextField } from "@react-md/core/form/useTextField";
  *
  * function Example(): ReactElement {
  *   const { fieldProps } = useTextField({
@@ -414,8 +423,9 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  *
  * @example Custom Validation
  * ```tsx
- * import type { ReactElement } from "react";
- * import { TextField, useTextField } from "@react-md/core";
+ * import { type ReactElement } from "react";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useTextField } from "@react-md/core/form/useTextField";
  *
  * function Example(): ReactElement {
  *   const { fieldProps } = useTextField({
@@ -461,7 +471,9 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
  * @since 2.5.6
- * @since 6.0.0 This hook returns an object instead of an ordered list.
+ * @since 6.0.0 This hook returns an object instead of an ordered list. Also
+ * 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>
@@ -627,6 +639,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
       if (event.isPropagationStopped()) {
         return;
       }
+
       checkValidity(true);
     },
     onChange(event) {
@@ -636,9 +649,10 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
       }
 
       if (validationType === "blur") {
+        const { value } = event.currentTarget;
         setState((prevState) => ({
           ...prevState,
-          value: event.currentTarget.value,
+          value,
         }));
         return;
       }
@@ -675,15 +689,15 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
     },
   };
 
-  if (!disableMessage) {
+  const isCounter = counter && typeof maxLength === "number";
+  if (isCounter || helpText || !disableMessage) {
     fieldProps["aria-describedby"] = messageId;
     fieldProps.messageProps = {
       id: messageId,
       error,
       length: counter ? value.length : undefined,
-      maxLength:
-        counter && typeof maxLength === "number" ? maxLength : undefined,
-      children: errorMessage || helpText,
+      maxLength: (counter && maxLength) || undefined,
+      children: (!disableMessage && errorMessage) || helpText,
     };
   }
 

package/src/form/useTextFieldContainerAddons.ts

@@ -1,11 +1,13 @@
 "use client";
+
 import {
-  useCallback,
-  useState,
   type CSSProperties,
   type Ref,
   type RefCallback,
+  useCallback,
+  useState,
 } from "react";
+
 import { useResizeObserver } from "../useResizeObserver.js";
 import { getFormConfig } from "./formConfig.js";
 import { type FormTheme } from "./types.js";

package/src/form/validation.ts

@@ -91,6 +91,7 @@ export type GetErrorMessage = (options: ErrorMessageOptions) => string;
 /**
  * @internal
  * @since 2.5.0
+ * @since 6.0.0 Added `"valid"` since it exists in the type definition
  */
 const VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "badInput",
@@ -102,6 +103,7 @@ const VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "tooLong",
   "tooShort",
   "typeMismatch",
+  "valid",
   "valueMissing",
 ];
 

package/src/hoverMode/useHoverMode.ts

@@ -1,8 +1,19 @@
 "use client";
-import type { MouseEvent } from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
-import type { UseStateInitializer, UseStateSetter } from "../types.js";
-import type { SimpleHoverModeContext } from "./useHoverModeProvider.js";
+
+import {
+  type MouseEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+import {
+  type SimpleHoverModeContext,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type useHoverModeProvider,
+} from "./useHoverModeProvider.js";
 
 /**
  * @since 6.0.0
@@ -66,6 +77,67 @@ export interface HoverModeImplementation
 }
 
 /**
+ * The `useHoverMode` hook is used to implement an immediate hover state after
+ * hovering related elements for a short duration. The main use-case is for
+ * showing tooltips immediately after hovering another tooltipped element.
+ *
+ * This relies on creating a context provider using {@link useHoverModeProvider}
+ * to link related elements together.
+ *
+ * @example Example Usage
+ * ```ts
+ * import { type MouseEvent } from "react";
+ *
+ * import {
+ *   type CustomHoverContext,
+ *   useCustomHoverContext,
+ * } from "./useCustomHoverContext.jsx";
+ *
+ * interface CustomHoverModeImplementation {
+ *   onMouseEnter: <E extends HTMLElement>(event: MouseEvent<E>) => void;
+ *   onMouseLeave: <E extends HTMLElement>(event: MouseEvent<E>) => void;
+ * }
+ *
+ * function useCustomHoverMode(): CustomHoverModeImplementation {
+ *   const {
+ *     animatedOnceRef,
+ *     hoverTimeoutRef,
+ *     leaveTimeoutRef,
+ *     enableHoverMode,
+ *     disableHoverMode,
+ *     startDisableTimer,
+ *     clearDisableTimer,
+ *   } = useCustomHoverContext();
+ *   const {
+ *     visible,
+ *     setVisible,
+ *     startShowFlow,
+ *     startHideFlow,
+ *     clearVisibilityTimeout,
+ *   } = useHoverMode({
+ *     hoverTimeout,
+ *     hoverTimeoutRef,
+ *     leaveTimeout,
+ *     leaveTimeoutRef,
+ *     enableHoverMode,
+ *     disableHoverMode,
+ *     startDisableTimer,
+ *     clearDisableTimer,
+ *   });
+ *
+ *   return {
+ *     onMouseEnter(event) {
+ *       startShowFlow(event.currentTarget.id);
+ *     },
+ *     onMouseLeave(event) {
+ *       startHideFlow();
+ *     },
+ *   };
+ * }
+ * ```
+ *
+ * @see The `useTooltip` source code for a real world example.
+ *
  * @since 2.8.0
  * @since 5.0.0 This hook no longer returns `handlers` or
  * `stickyHandlers` and does not hide when an element on the page is clicked.

package/src/hoverMode/useHoverModeProvider.ts

@@ -1,6 +1,8 @@
 "use client";
+
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { NonNullMutableRef, NonNullRef } from "../types.js";
+
+import { type NonNullMutableRef, type NonNullRef } from "../types.js";
 
 const noop = (): void => {
   // do nothing
@@ -177,22 +179,32 @@ export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
 /**
  * @example Creating a Hover Mode Group
  * ```tsx
- * import type {
- *   HoverModeConfiguration,
- *   HoverModeContext,
- * } from "@react-md/core";
  * import {
+ *   type HoverModeContext,
  *   createHoverModeContext,
  *   useHoverModeProvider,
- * } from "@react-md/core";
- * import type { ReactElement } from "react";
- * import { createContext, useContext } from "react";
+ * } from "@react-md/core/hoverMode/useHoverModeProvider";
+ * import {
+ *   type ReactElement,
+ *   type ReactNode,
+ *   createContext,
+ *   useContext,
+ * } from "react";
  *
- * // extend as needed
- * type CustomHoverMode = HoverModeContext;
+ * export interface CustomHoverContext extends HoverModeContext {
+ *   // any additional fields in the context
+ * }
  *
- * // you can also add defaults if there is no parent provider.
- * const context = createContext<CustomHoverMode>(createHoverModeContext());
+ * const context = createContext<CustomHoverContext>(
+ *   createHoverModeContext()
+ *   // you can also provide default values if needed when the context provider
+ *   // isn't a parent component. the following are the defaults
+ *   // createHoverModeContext({
+ *   //    hoverTimeout: undefined,
+ *   //    leaveTimeout: 0,
+ *   //    defaultActiveId: "",
+ *   // })
+ * );
  * const { Provider } = context;
  *
  * interface Props extends HoverModeConfiguration {

package/src/icon/FontIcon.tsx

@@ -1,10 +1,11 @@
 import {
-  forwardRef,
   type AriaAttributes,
   type HTMLAttributes,
   type ReactNode,
+  forwardRef,
 } from "react";
-import { icon, type FontIconClassNameOptions } from "./styles.js";
+
+import { type FontIconClassNameOptions, icon } from "./styles.js";
 
 /**
  * @since 6.0.0 Removed the `forceSize`/`forceFontSize` props and added the

package/src/icon/IconRotator.tsx

@@ -1,14 +1,15 @@
 import { cnb } from "cnbuilder";
 import {
+  type CSSProperties,
   Children,
+  type HTMLAttributes,
+  type ReactNode,
   cloneElement,
   forwardRef,
   isValidElement,
-  type CSSProperties,
-  type HTMLAttributes,
-  type ReactNode,
 } from "react";
-import { iconRotator, type IconRotatorClassNameOptions } from "./styles.js";
+
+import { type IconRotatorClassNameOptions, iconRotator } from "./styles.js";
 
 /**
  * @since 6.0.0 Removed `animate` prop and added `disableTransition`

package/src/icon/MaterialIcon.tsx

@@ -1,7 +1,8 @@
-import { forwardRef, type AriaAttributes, type HTMLAttributes } from "react";
+import { type AriaAttributes, type HTMLAttributes, forwardRef } from "react";
+
 import { type MaterialIconFamily, type MaterialIconName } from "./material.js";
 import { MATERIAL_CONFIG } from "./materialConfig.js";
-import { icon, type MaterialIconClassNameOptions } from "./styles.js";
+import { type MaterialIconClassNameOptions, icon } from "./styles.js";
 
 /** @since 6.0.0 */
 export interface MaterialIconProps

package/src/icon/MaterialSymbol.tsx

@@ -1,14 +1,15 @@
-import { forwardRef, type AriaAttributes, type HTMLAttributes } from "react";
+import { type AriaAttributes, type HTMLAttributes, forwardRef } from "react";
+
 import { type MaterialSymbolName } from "./material.js";
 import {
-  getFontVariationSettings,
   type MaterialSymbolCustomization,
   type MaterialSymbolFill,
   type MaterialSymbolGrade,
   type MaterialSymbolOpticalSize,
   type MaterialSymbolWeight,
+  getFontVariationSettings,
 } from "./materialConfig.js";
-import { icon, type MaterialSymbolClassNameOptions } from "./styles.js";
+import { type MaterialSymbolClassNameOptions, icon } from "./styles.js";
 
 declare module "react" {
   interface CSSProperties {

package/src/icon/SVGIcon.tsx

@@ -1,5 +1,6 @@
-import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
-import { icon, type SVGIconClassNameOptions } from "./styles.js";
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
+import { type SVGIconClassNameOptions, icon } from "./styles.js";
 
 /**
  * @since 6.0.0 Added the `inline` and `theme` props.

package/src/icon/TextIconSpacing.tsx

@@ -1,10 +1,10 @@
 import { cnb } from "cnbuilder";
 import {
   Children,
-  cloneElement,
-  isValidElement,
   type ReactElement,
   type ReactNode,
+  cloneElement,
+  isValidElement,
 } from "react";
 
 export interface TextIconSpacingProps {

package/src/icon/{iconConfig.tsx → config.tsx}

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+
 import { FontIcon } from "./FontIcon.js";
 
 /**

package/src/icon/materialConfig.ts

@@ -1,4 +1,5 @@
 import { type CSSProperties } from "react";
+
 import {
   type MaterialIconFamily,
   type MaterialSymbolFamily,

package/src/icon/styles.ts

@@ -1,5 +1,6 @@
 import { cnb } from "cnbuilder";
-import { cssUtils, type TextColor, type ThemeColor } from "../cssUtils.js";
+
+import { type TextColor, type ThemeColor, cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 import type { MaterialIconFamily, MaterialSymbolFamily } from "./material.js";
 

package/src/interaction/Ripple.tsx

@@ -1,6 +1,8 @@
 "use client";
+
 import { cnb } from "cnbuilder";
 import { type ReactElement } from "react";
+
 import {
   type CSSTransitionClassNames,
   type TransitionTimeout,

package/src/interaction/RippleContainer.tsx

@@ -1,5 +1,6 @@
 import { cnb } from "cnbuilder";
 import { type ReactElement } from "react";
+
 import { Ripple } from "./Ripple.js";
 import { type ProvidedRippleContainerProps } from "./types.js";
 

package/src/interaction/UserInteractionModeProvider.tsx

@@ -1,13 +1,14 @@
 "use client";
+
 import {
+  type ReactElement,
+  type ReactNode,
   createContext,
   useContext,
   useEffect,
   useMemo,
   useRef,
   useState,
-  type ReactElement,
-  type ReactNode,
 } from "react";
 
 /**

package/src/interaction/useElementInteraction.tsx

@@ -1,21 +1,25 @@
 "use client";
-import type {
-  FocusEvent,
-  KeyboardEvent,
-  MouseEvent,
-  ReactElement,
-  TouchEvent,
+
+import {
+  type FocusEvent,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactElement,
+  type TouchEvent,
+  useCallback,
+  useReducer,
+  useRef,
 } from "react";
-import { useCallback, useReducer, useRef } from "react";
+
 import { RippleContainer } from "./RippleContainer.js";
 import { useUserInteractionMode } from "./UserInteractionModeProvider.js";
 import { INTERACTION_CONFIG } from "./config.js";
-import type {
-  ElementInteractionHandlers,
-  ElementInteractionMode,
-  ElementInteractionState,
-  RippleState,
-  RippleStyle,
+import {
+  type ElementInteractionHandlers,
+  type ElementInteractionMode,
+  type ElementInteractionState,
+  type RippleState,
+  type RippleStyle,
 } from "./types.js";
 import { getRippleStyle, releaseRipple, updateRipplesState } from "./utils.js";
 
@@ -49,7 +53,7 @@ export interface ElementInteractionOptions<E extends HTMLElement>
 }
 
 /** @since 6.0.0 */
-export interface ElementInteractionHookReturnValue<E extends HTMLElement> {
+export interface ElementInteractionImplementation<E extends HTMLElement> {
   /**
    * The event handlers required for element interaction.
    */
@@ -90,9 +94,9 @@ const noop = (): void => {
  *
  * @example Providing Element Interaction
  * ```tsx
- * import { useElementInteraction } from "@react-md/core";
+ * import { useElementInteraction } from "@react-md/core/interaction/useElementInteraction";
  * import { cnb } from "cnbuilder";
- * import type { ReactElement } from "react";
+ * import { type ReactElement } from "react";
  *
  * import styles from "./CustomComponent.module.scss";
  *
@@ -114,26 +118,25 @@ const noop = (): void => {
  *     onTouchStart,
  *     onTouchMove,
  *     onTouchEnd,
- *     ...remaining,
+ *     ...remaining
  *   } = props;
  *
- *   const { handlers, pressed, ripples } =
- *     useElementInteraction({
- *       disabled,
- *       // pass remaining props so that if any event handlers were provided to
- *       // the component, they will be merged with the element interaction
- *       // handlers
- *       onBlur,
- *       onClick,
- *       onKeyDown,
- *       onKeyUp,
- *       onMouseDown,
- *       onMouseUp,
- *       onMouseLeave,
- *       onTouchStart,
- *       onTouchMove,
- *       onTouchEnd,
- *     })
+ *   const { handlers, pressed, ripples } = useElementInteraction({
+ *     disabled,
+ *     // pass remaining props so that if any event handlers were provided to
+ *     // the component, they will be merged with the element interaction
+ *     // handlers
+ *     onBlur,
+ *     onClick,
+ *     onKeyDown,
+ *     onKeyUp,
+ *     onMouseDown,
+ *     onMouseUp,
+ *     onMouseLeave,
+ *     onTouchStart,
+ *     onTouchMove,
+ *     onTouchEnd,
+ *   });
  *
  *   return (
  *     <div
@@ -153,14 +156,14 @@ const noop = (): void => {
  *
  * @param options - An object of {@link ElementInteractionOptions} that is used
  * to merge event handlers or disable the interactions.
- * @returns the {@link ElementInteractionHookReturnValue}
+ * @returns the {@link ElementInteractionImplementation}
  * @since 6.0.0 Touch interactions were removed since it never looked
  * good if the user touched a clickable element right before scrolling. The
  * ripple effect will only be fired on click now for touch devices.
  */
 export function useElementInteraction<E extends HTMLElement>(
   options: ElementInteractionOptions<E> = {}
-): ElementInteractionHookReturnValue<E> {
+): ElementInteractionImplementation<E> {
   const {
     onBlur = noop,
     onClick = noop,

package/src/interaction/useHigherContrastChildren.tsx

@@ -1,4 +1,5 @@
 import { Children, type ReactNode } from "react";
+
 import { INTERACTION_CONFIG } from "./config.js";
 
 /**
@@ -14,11 +15,13 @@ import { INTERACTION_CONFIG } from "./config.js";
  *
  * @example Simple Example
  * ```tsx
+ * import { useElementInteraction } from "@react-md/core/interaction/useElementInteraction";
+ * import { useHigherContrastChildren, } from "@react-md/core/interaction/useHigherContrastChildren";
  * import {
- *   useElementInteraction,
- *   useHigherContrastChildren,
- * } from "@react-md/core";
- * import type { ButtonHTMLAttributes, ReactElement, ReactNode } from "react";
+ *   type ButtonHTMLAttributes,
+ *   type ReactElement,
+ *   type ReactNode,
+ * } from "react";
  *
  * function Example(props: ButtonHTMLAttributes<HTMLButtonElement>): ReactElement {
  *   const {
@@ -60,7 +63,7 @@ import { INTERACTION_CONFIG } from "./config.js";
  * }
  * ```
  *
- * @param propChildren - The children to conditionally wrap in spans.
+ * @param children - The children to conditionally wrap in spans.
  * @param disable - Manually disable this functionality even if the higher
  * contrast mode is enabled. This is really used within `ListItem`s so there
  * aren't unneeded `<span>`s for string/number children when there are addons.
@@ -69,16 +72,16 @@ import { INTERACTION_CONFIG } from "./config.js";
  * @internal
  */
 export function useHigherContrastChildren(
-  propChildren: ReactNode,
+  children: ReactNode,
   disable = false
 ): ReactNode {
   if (!INTERACTION_CONFIG.higherContrast || disable) {
-    return propChildren;
+    return children;
   }
 
   // Note: This will fail if the child is wrapped in a Fragment, but that use
   // case doesn't matter to me
-  return Children.map(propChildren, (child) => {
+  return Children.map(children, (child) => {
     const t = typeof child;
     if (t === "string" || t === "number") {
       return <span>{child}</span>;