@react-md/core 1.0.0-next.2 → 1.0.0-next.21

package/src/form/validation.ts

@@ -1,8 +1,8 @@
 import { type InputHTMLAttributes, type ReactNode } from "react";
 
 /**
- * @remarks \@since 2.5.6
- * @remarks \@since 6.0.0 Renamed from `TextConstraints` to
+ * @since 2.5.6
+ * @since 6.0.0 Renamed from `TextConstraints` to
  * `TextFieldValidationOptions`
  */
 export type TextFieldValidationOptions = Pick<
@@ -29,8 +29,8 @@ export type TextFieldValidationOptions = Pick<
  *
  * @see {@link RECOMMENDED_STATE_KEYS}
  * @see {@link RECOMMENDED_NUMBER_STATE_KEYS}
- * @remarks \@since 2.5.6
- * @remarks \@since 6.0.0 Renamed from `ChangeValidationBehavior` to
+ * @since 2.5.6
+ * @since 6.0.0 Renamed from `ChangeValidationBehavior` to
  * `TextFieldValidationType`
  */
 export type TextFieldValidationType =
@@ -41,7 +41,8 @@ export type TextFieldValidationType =
   | readonly (keyof ValidityState)[];
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
+ * @since 6.0.0 Renamed `validateOnChange` to `validationType`
  */
 export interface ErrorMessageOptions extends TextFieldValidationOptions {
   /**
@@ -84,13 +85,14 @@ export interface ErrorMessageOptions extends TextFieldValidationOptions {
  * @param options - An object containing metadata that can be used to create an
  * error message for your `TextField` or `TextArea`.
  * @returns An error message to display or an empty string.
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export type GetErrorMessage = (options: ErrorMessageOptions) => string;
 
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @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,12 +104,13 @@ const VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "tooLong",
   "tooShort",
   "typeMismatch",
+  "valid",
   "valueMissing",
 ];
 
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "badInput",
@@ -117,7 +120,7 @@ export const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[] = [
 
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityState)[] = [
   ...RECOMMENDED_STATE_KEYS,
@@ -135,7 +138,7 @@ export const RECOMMENDED_NUMBER_STATE_KEYS: readonly (keyof ValidityState)[] = [
  * of errors.
  *
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 const isRecommended = (validity: ValidityState, isNumber: boolean): boolean => {
   const errorable = isNumber
@@ -153,7 +156,7 @@ const isRecommended = (validity: ValidityState, isNumber: boolean): boolean => {
  * or `TextArea` components that relies on the behavior of the
  * {@link ChangeValidationBehavior}
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const defaultGetErrorMessage: GetErrorMessage = (options) => {
   const {
@@ -185,7 +188,7 @@ export const defaultGetErrorMessage: GetErrorMessage = (options) => {
 };
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface IsErroredOptions extends ErrorMessageOptions {
   /**
@@ -201,7 +204,7 @@ export interface IsErroredOptions extends ErrorMessageOptions {
  * @param options - All the current options that can be used to determine the
  * error state.
  * @returns True if the component is considered to be in an errored state.
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export type IsErrored = (options: IsErroredOptions) => boolean;
 
@@ -211,7 +214,7 @@ export type IsErrored = (options: IsErroredOptions) => boolean;
  * value is not within the `minLength` and `maxLength` constraints when they
  * exist.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const defaultIsErrored: IsErrored = (options) => {
   const { value, errorMessage, minLength, maxLength, isBlurEvent } = options;
@@ -224,7 +227,7 @@ export const defaultIsErrored: IsErrored = (options) => {
 };
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface GetErrorIconOptions {
   /**
@@ -249,8 +252,8 @@ export interface GetErrorIconOptions {
  *
  * @param options - The {@link GetErrorIconOptions}
  * @returns An icon to render or falsey to render nothing.
- * @remarks \@since 2.5.0
- * @remarks \@since 6.0.0 Updated to accept a single object argument
+ * @since 2.5.0
+ * @since 6.0.0 Updated to accept a single object argument
  */
 export type GetErrorIcon = (options: GetErrorIconOptions) => ReactNode;
 
@@ -258,7 +261,7 @@ export type GetErrorIcon = (options: GetErrorIconOptions) => ReactNode;
  * The default implementation for showing an error icon in `TextField` and
  * `TextArea` components that will only display when the error flag is enabled.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const defaultGetErrorIcon: GetErrorIcon = (options) => {
   const { error, errorIcon } = options;

package/src/hoverMode/useHoverMode.ts

@@ -1,11 +1,22 @@
 "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";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
   /** @defaultValue `false` */
@@ -23,7 +34,7 @@ export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeOptions
   extends HoverModeConfigurationOptions {
@@ -31,16 +42,16 @@ export interface ControlledHoverModeOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeImplementation {
-  startShowFlow(id?: string | MouseEvent): void;
-  startHideFlow(): void;
-  clearVisibilityTimeout(): void;
+  startShowFlow: (id?: string | MouseEvent) => void;
+  startHideFlow: () => void;
+  clearVisibilityTimeout: () => void;
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeOptions
   extends HoverModeConfigurationOptions {
@@ -48,7 +59,7 @@ export interface UncontrolledHoverModeOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeImplementation
   extends ControlledHoverModeImplementation {
@@ -57,7 +68,7 @@ export interface UncontrolledHoverModeImplementation
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeImplementation
   extends ControlledHoverModeImplementation {
@@ -66,11 +77,71 @@ export interface HoverModeImplementation
 }
 
 /**
- * @remarks
- * \@since 2.8.0
- * \@since 5.0.0 This hook no longer returns `handlers` or
+ * 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.
- * \@since 6.0.0 Requires passing the custom hover mode context to
+ * @since 6.0.0 Requires passing the custom hover mode context to
  * work.
  */
 export function useHoverMode(

package/src/hoverMode/useHoverModeProvider.ts

@@ -1,16 +1,17 @@
 "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
 };
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface SimpleHoverModeContext {
   /**
-   * @example
-   * Main Usage
+   * @example Main Usage
    * ```ts
    * onMouseEnter(event) {
    *   const hoverTimeout = hoverTimeoutRef.current;
@@ -31,8 +32,7 @@ export interface SimpleHoverModeContext {
   hoverTimeoutRef: NonNullRef<number | undefined>;
 
   /**
-   * @example
-   * Main Usage
+   * @example Main Usage
    * ```ts
    * onMouseLeave() {
    *   if (mode === "touch") {
@@ -55,29 +55,28 @@ export interface SimpleHoverModeContext {
    *
    * @see {@link hoverTimeoutRef} for an example.
    */
-  enableHoverMode(activeId: string): void;
+  enableHoverMode: (activeId: string) => void;
 
   /**
    * Disables all hover mode behavior by clearing all timeouts and resetting
    * internal state.
    */
-  disableHoverMode(): void;
+  disableHoverMode: () => void;
 
   /**
    * @see {@link leaveTimeoutRef} for an example.
    */
-  startDisableTimer(): void;
+  startDisableTimer: () => void;
 
   /**
    * @see {@link hoverTimeoutRef} for an example.
    */
-  clearDisableTimer(): void;
+  clearDisableTimer: () => void;
 }
 
 /**
- * @remarks
- * \@since 2.8.0
- * \@since 6.0.0 Uses refs to increase performance by preventing unneeded
+ * @since 2.8.0
+ * @since 6.0.0 Uses refs to increase performance by preventing unneeded
  * re-renders of the entire hover mode provider's component tree. The API also
  * changed to support custom hover mode providers.
  */
@@ -108,7 +107,7 @@ export interface HoverModeContext extends SimpleHoverModeContext {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface CreateHoverModeContextOptions {
   /**
@@ -132,14 +131,14 @@ export interface CreateHoverModeContextOptions {
    * visibility to `false`.
    *
    * @defaultValue `0`
-   * @remarks \@since 6.0.0 This was renamed from `exitVisibilityDelay` and the
+   * @since 6.0.0 This was renamed from `exitVisibilityDelay` and the
    * default value changed from `300` to `0`.
    */
   leaveTimeout?: number;
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function createHoverModeContext(
   options: CreateHoverModeContextOptions = {}
@@ -159,7 +158,7 @@ export function createHoverModeContext(
   };
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
   /**
    * The amount of time to wait before disabling the hover mode behavior if none
@@ -178,25 +177,34 @@ export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
 }
 
 /**
- * @example
- * Creating a Hover Mode Group
+ * @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 {
@@ -224,7 +232,7 @@ export interface HoverModeConfiguration extends CreateHoverModeContextOptions {
  *
  * @see {@link CreateHoverModeContextOptions}
  * @see {@link useHoverMode}
- * @remarks \@since 6.0.0 The `HoverModeProvider` component was replaced by this
+ * @since 6.0.0 The `HoverModeProvider` component was replaced by this
  * hook implementation. After developing the `MenuBar`, I realized the hover
  * mode should normally be grouped by related components or types instead of a
  * top-level catch all.

package/src/icon/FontIcon.tsx

@@ -1,39 +1,51 @@
-import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
-import { icon, type FontIconClassNameOptions } from "./styles.js";
+import {
+  type AriaAttributes,
+  type HTMLAttributes,
+  type ReactNode,
+  forwardRef,
+} from "react";
 
+import { type FontIconClassNameOptions, icon } from "./styles.js";
+
+/**
+ * @since 6.0.0 Removed the `forceSize`/`forceFontSize` props and added the
+ * `inline` and `theme` props.
+ */
 export interface FontIconProps
-  extends HTMLAttributes<HTMLElement>,
+  extends HTMLAttributes<HTMLSpanElement>,
     FontIconClassNameOptions {
+  /** @defaultValue `true` */
+  "aria-hidden"?: AriaAttributes["aria-hidden"];
+
   /**
    * Any children to render to create the font icon. This is required for
-   * material-icons.
+   * material-icons. For example:
+   *
+   * ```tsx
+   * <FontIcon>clear</FontIcon>
+   * ```
    */
   children?: ReactNode;
 }
 
 /**
- * **Server Component**
- *
  * The `FontIcon` component is used for rendering a font-icon library's icon.
  * The default is to use the `material-icons` library, but others can be used as
  * well.
  *
- * If you are using another font icon library that does not always create icons
- * with a perfect 1:1 scale (such as font awesome), it is recommended to use the
- * `forceSize` and `forceFontSize` props to fix the sizing issues.
- *
- * \@remarks \@since 6.0.0 Switched from `<i>` to `<span>` element and removed
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
+ * @since 6.0.0 Switched from `<i>` to `<span>` element and removed
  * the `forceSize`/`forceFontSize` props.
  */
 export const FontIcon = forwardRef<HTMLElement, FontIconProps>(
   function FontIcon(props, ref) {
     const {
-      className,
-      children,
       "aria-hidden": ariaHidden = true,
+      iconClassName = "material-icons",
       dense = false,
       theme,
-      iconClassName = "material-icons",
+      className,
+      children,
       ...remaining
     } = props;
 

package/src/icon/IconRotator.tsx

@@ -1,17 +1,18 @@
 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";
 
 /**
- * @remarks \@since 6.0.0 Removed `animate` prop and added `disableTransition`
+ * @since 6.0.0 Removed `animate` prop and added `disableTransition`
  */
 export interface IconRotatorBaseProps
   extends HTMLAttributes<HTMLSpanElement>,
@@ -42,15 +43,14 @@ export interface IconRotatorProps extends IconRotatorBaseProps {
 }
 
 /**
- * **Server Component**
- *
  * The `IconRotator` is a simple component that is used to rotate an icon from a
  * one degrees to another.
+ *
+ * @see {@link https://next.react-md.dev/components/icon-rotator | IconRotator Demos}
  */
 export const IconRotator = forwardRef<HTMLSpanElement, IconRotatorProps>(
   function IconRotator(props, ref) {
     const {
-      style,
       className: propClassName,
       rotated,
       children,
@@ -72,7 +72,7 @@ export const IconRotator = forwardRef<HTMLSpanElement, IconRotatorProps>(
     }
 
     return (
-      <span {...remaining} style={style} className={className} ref={ref}>
+      <span {...remaining} ref={ref} className={className}>
         {children}
       </span>
     );

package/src/icon/MaterialIcon.tsx

@@ -1,22 +1,42 @@
-import { forwardRef, type AriaAttributes, type HTMLAttributes } from "react";
-import { type MaterialIconName } from "./material.js";
+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";
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface MaterialIconProps
   extends HTMLAttributes<HTMLSpanElement>,
     Partial<MaterialIconClassNameOptions> {
+  /**
+   * The icon name to use
+   */
+  name: MaterialIconName;
+
   /** @defaultValue `true` */
   "aria-hidden"?: AriaAttributes["aria-hidden"];
-  name: MaterialIconName;
+
+  /** @defaultValue `MATERIAL_CONFIG.iconFamily` */
+  family?: MaterialIconFamily;
   children?: never;
 }
 
 /**
- * **Server Component**
+ * The `MaterialIcon` component is used for rendering a material icon using the
+ * Google Fonts stylesheet (handled separately). This is mostly a convenience
+ * wrapper around the `FontIcon` that will catch typos for the supported icon
+ * names.
  *
- * @remarks \@since 6.0.0
+ * @example Simple Example
+ * ```tsx
+ * <MaterialIcon name="3k" />
+ * <MaterialIcon name="favorite" theme="primary" />
+ * <MaterialIcon name="wifi" family="two-tone" dense theme="warning" />
+ * ```
+ *
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
+ * @see {@link https://next.react-md.dev/components/material-icons|Available Material Icons}
+ * @since 6.0.0
  */
 export const MaterialIcon = forwardRef<HTMLSpanElement, MaterialIconProps>(
   function MaterialIcon(props, ref) {
@@ -32,9 +52,9 @@ export const MaterialIcon = forwardRef<HTMLSpanElement, MaterialIconProps>(
 
     return (
       <span
-        ref={ref}
-        aria-hidden={ariaHidden}
         {...remaining}
+        aria-hidden={ariaHidden}
+        ref={ref}
         className={icon({
           type: "material",
           family,

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 {
@@ -20,7 +21,7 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface MaterialSymbolProps
   extends HTMLAttributes<HTMLSpanElement>,
@@ -33,7 +34,6 @@ export interface MaterialSymbolProps
 }
 
 /**
- * **Server Component**
  * This is a convenience component that provides autocomplete for all the
  * available material symbols via the `name` prop.
  *
@@ -41,10 +41,9 @@ export interface MaterialSymbolProps
  * there are so many icons available. If it becomes an issue, just stop using
  * this component and define the icons inline instead.
  *
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
- * import { MaterialSymbol } from "@react-md/core";
+ * import { MaterialSymbol } from "@react-md/core/icon/MaterialSymbol";
  * import type { ReactElement } from "react";
  * import { createRoot } from "react-dom/client";
  *
@@ -64,7 +63,9 @@ export interface MaterialSymbolProps
  * root.render(<App />);
  * ```
  *
- * @remarks \@since 6.0.0
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
+ * @see {@link https://next.react-md.dev/components/material-icons|Available Material Icons}
+ * @since 6.0.0
  */
 export const MaterialSymbol = forwardRef<HTMLSpanElement, MaterialSymbolProps>(
   function MaterialSymbol(props, ref) {