@react-md/core 6.2.1 → 6.3.1

package/src/datetime/useTimeField.ts

@@ -0,0 +1,233 @@
+"use client";
+
+import { type InputHTMLAttributes, useRef } from "react";
+
+import {
+  type ProvidedFormMessageProps,
+  type ProvidedTextFieldProps,
+  type TextFieldHookOptions,
+  type TextFieldImplementation,
+  type TextFieldWithMessageImplementation,
+  useTextField,
+} from "../form/useTextField.js";
+import { type TimeFieldStepOptions, getTimeStep } from "./utils.js";
+
+/** @since 6.3.0 */
+export interface TimeFieldConstraints {
+  /**
+   * This **must** be in the format `HH:mm`:
+   * - `00:30` (12:30 AM)
+   * - `15:15` (03:15 PM)
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/time#time_value_format | Time value format}
+   */
+  min?: string;
+
+  /**
+   * This **must** be in the format `HH:mm`:
+   * - `00:30` (12:30 AM)
+   * - `15:15` (03:15 PM)
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/time#time_value_format | Time value format}
+   */
+  max?: string;
+
+  /**
+   * For time inputs, the value of step is given in seconds, with a scaling
+   * factor of 1000 (since the underlying numeric value is in milliseconds).
+   * The default value of step is 60, indicating 60 seconds (or 1 minute, or
+   * 60,000 milliseconds).
+   *
+   * When any is set as the value for step, the default 60 seconds is used, and
+   * the seconds value is not displayed in the UI.
+   *
+   * Here are a few examples:
+   *
+   * - `15`   -> 15 seconds
+   * - `60`   -> 1 minute
+   * - `900`  -> 15 minutes
+   * - `3600` -> 1 hour
+   *
+   * Since this might be a bit confusing, the values can be provided in an
+   * object instead:
+   *
+   * ```ts
+   * { seconds: 30 }
+   * { minutes: 1 }
+   * { minutes: 15 }
+   * { hours: 1 }
+   * { seconds: 15, minutes: 30, hours: 1 }
+   * ```
+   *
+   * NOTE: The `min` and `max` props **must** be provided as well for the
+   * `step` to work.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/time#step | step attribute}
+   */
+  step?: number | "any" | TimeFieldStepOptions;
+}
+
+/** @since 6.3.0 */
+export interface TimeFieldOptions
+  extends Omit<
+      TextFieldHookOptions,
+      | "isNumber"
+      | "counter"
+      | "pattern"
+      | "maxLength"
+      | "minLength"
+      | "disableMaxLength"
+    >,
+    TimeFieldConstraints {}
+
+/** @since 6.3.0 */
+export interface ProvidedTimeFieldProps
+  extends Omit<ProvidedTextFieldProps, "value">,
+    Omit<TimeFieldConstraints, "step"> {
+  type: "time";
+  step?: number | "any";
+  defaultValue: Required<InputHTMLAttributes<HTMLInputElement>>["defaultValue"];
+}
+
+/** @since 6.3.0 */
+export interface ProvidedTimeFieldMessageProps extends ProvidedTimeFieldProps {
+  /**
+   * These props will be defined as long as the `disableMessage` prop is not
+   * `true` from the `useTextField` hook.
+   */
+  messageProps: ProvidedFormMessageProps;
+}
+
+/** @since 6.3.0 */
+export interface TimeFieldImplementation
+  extends Omit<TextFieldImplementation, "fieldProps"> {
+  fieldProps: ProvidedTimeFieldProps;
+}
+
+/** @since 6.3.0 */
+export interface TimeFieldWithMessageImplementation
+  extends Omit<TextFieldWithMessageImplementation, "fieldProps"> {
+  fieldProps: ProvidedTimeFieldMessageProps;
+}
+
+/** @since 6.3.0 */
+export interface ValidatedTimeFieldImplementation
+  extends TimeFieldImplementation {
+  fieldProps: ProvidedTimeFieldProps | ProvidedTimeFieldMessageProps;
+}
+
+/**
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-time-field | NativeTimeField Demos}
+ * @see {@link https://react-md.dev/hooks/use-time-field | useTimeField Demos}
+ */
+export function useTimeField(
+  options: TimeFieldOptions & { disableMessage: true }
+): TimeFieldImplementation;
+
+/**
+ * The `useTimeField` is a small wrapper around the {@link useTextField} to be used
+ * with `<input type="time" />`. It is used in the `NativeTimeField` if an example
+ * implementation would like to be seen.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { useTimeField } from "@react-md/core/datetime/useTimeField";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, fieldProps, error, errorMessage } = useTimeField({
+ *     name: "appt",
+ *     required: true,
+ *     min: "08:00",
+ *     max: "17:00",
+ *     step: { minute: 15 },
+ *     disableMessage: true,
+ *   });
+ *
+ *   // value: `""` or `"HH:mm"`
+ *
+ *   return <TextField label="Appointment" {...fieldProps} />
+ * }
+ * ```
+ *
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-time-field | NativeTimeField Demos}
+ * @see {@link https://react-md.dev/hooks/use-time-field | useTimeField Demos}
+ */
+export function useTimeField(
+  options: TimeFieldOptions
+): TimeFieldWithMessageImplementation;
+
+/**
+ * The `useTimeField` is a small wrapper around the {@link useTextField} to be used
+ * with `<input type="time" />`. It is used in the `NativeTimeField` if an example
+ * implementation would like to be seen.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { useTimeField } from "@react-md/core/datetime/useTimeField";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, fieldProps } = useTimeField({
+ *     name: "appt",
+ *     required: true,
+ *     min: "08:00",
+ *     max: "17:00",
+ *     step: { minute: 15 },
+ *   });
+ *
+ *   // value: `""` or `"HH:mm"`
+ *
+ *   return <TextField label="Appointment" {...fieldProps} />
+ * }
+ * ```
+ *
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-time-field | NativeTimeField Demos}
+ * @see {@link https://react-md.dev/hooks/use-time-field | useTimeField Demos}
+ */
+export function useTimeField(
+  options: TimeFieldOptions
+): ValidatedTimeFieldImplementation {
+  const { min, max, step, ...fieldOptions } = options;
+  if (
+    process.env.NODE_ENV !== "production" &&
+    typeof step !== "undefined" &&
+    (!min || !max)
+  ) {
+    throw new Error(
+      "A `step` was provided to a time field without the `min` or `max` props."
+    );
+  }
+
+  const { errorMessage, fieldProps, ...impl } = useTextField(fieldOptions);
+
+  // NOTE: Unlike the other text field components, the `value` should **not**
+  // be provided since the time input behaves a bit weirdly with the `onChange`
+  // event and it is better to rely on default browser behavior instead of
+  // controlling the value. The flow is:
+  // - user types `12:30`
+  //   - `onChange` is fired with `12:30`
+  // - user selects `30` and hits backspace
+  //   - `onChange` is fired with `""`
+  // If the `value` is set, the other time values would be lost
+  const { value, ...allowedFieldProps } = fieldProps;
+  const initial = useRef(value);
+
+  return {
+    ...impl,
+    errorMessage,
+    fieldProps: {
+      ...allowedFieldProps,
+      defaultValue: initial.current,
+      min,
+      max,
+      step: getTimeStep(step),
+      type: "time",
+    },
+  };
+}

package/src/datetime/utils.ts

@@ -0,0 +1,48 @@
+/**
+ * Since time input steps are based on seconds, this is a simple helper to
+ * create the step in a human-readable form.
+ *
+ * @since 6.3.0
+ */
+export interface TimeFieldStepOptions {
+  /**
+   * @defaultValue `0`
+   */
+  seconds?: number;
+
+  /**
+   * @defaultValue `0`
+   */
+  minutes?: number;
+
+  /**
+   * @defaultValue `0`
+   */
+  hours?: number;
+}
+
+/**
+ * Since time input steps are based on seconds, this is a simple helper to
+ * create the step in a human-readable form.
+ *
+ * @example Simple Example
+ * ```tsx
+ * const step1 = getTimeStep({ minutes: 15 });
+ * const step2 = getTimeStep({ hours: 1 });
+ * const step3 = getTimeStep({ seconds: 15, minutes: 30, hours: 2 });
+ * ```
+ *
+ * @since 6.3.0
+ */
+export function getTimeStep(
+  step: TimeFieldStepOptions | "any" | number | undefined
+): number | "any" | undefined {
+  if (!step || typeof step === "string" || typeof step === "number") {
+    return step;
+  }
+
+  const { hours = 0, minutes = 0, seconds = 0 } = step;
+
+  const total = Math.abs(Math.round(seconds + minutes * 60 + hours * 60 * 60));
+  return total === 0 ? undefined : total;
+}

package/src/dialog/styles.ts

@@ -9,8 +9,6 @@ import { DISPLAY_NONE_CLASS } from "../utils/isElementVisible.js";
 
 declare module "react" {
   interface CSSProperties {
-    "--rmd-dialog-background-color"?: string;
-    "--rmd-dialog-color"?: string;
     "--rmd-dialog-min-width"?: string | number;
     "--rmd-dialog-horizontal-margin"?: string | number;
     "--rmd-dialog-vertical-margin"?: string | number;
@@ -19,6 +17,11 @@ declare module "react" {
     "--rmd-dialog-header-padding-bottom"?: string | number;
     "--rmd-dialog-content-padding"?: string | number;
     "--rmd-dialog-footer-padding"?: string | number;
+    "--rmd-dialog-width"?: string | number;
+    "--rmd-dialog-small-width"?: string | number;
+    "--rmd-dialog-medium-width"?: string | number;
+    "--rmd-dialog-large-width"?: string | number;
+    "--rmd-dialog-extra-large-width"?: string | number;
   }
 }
 

package/src/divider/styles.ts

@@ -5,7 +5,7 @@ import { bem } from "../utils/bem.js";
 declare module "react" {
   interface CSSProperties {
     "--rmd-divider-size"?: string | number;
-    "--rmd-divider-vertical-size"?: string | number;
+    "--rmd-divider-border-size"?: string | number;
     "--rmd-divider-color"?: string;
     "--rmd-divider-spacing"?: string | number;
     "--rmd-divider-vertical-spacing"?: string | number;

package/src/draggable/utils.ts

@@ -1,5 +1,6 @@
 import { type MouseEvent, type RefObject, type TouchEvent } from "react";
 
+import { type MinMaxRange } from "../types.js";
 import {
   type ClientPositionEvent,
   type ClientPositionOptions,
@@ -62,9 +63,7 @@ export const getDragPosition = (options: DragPositionOptions): number => {
 /**
  * @internal
  */
-interface RelativeDragPositionOptions extends DragPositionOptions {
-  min: number;
-  max: number;
+interface RelativeDragPositionOptions extends DragPositionOptions, MinMaxRange {
   step: number;
   rangeMin: number;
   rangeMax: number;
@@ -218,9 +217,7 @@ export const updateDragPosition = (
  * @internal
  * @since 6.0.0
  */
-export interface DeserializeDraggableValueOptions {
-  min: number;
-  max: number;
+export interface DeserializeDraggableValueOptions extends MinMaxRange {
   item: string;
 }
 

package/src/expansion-panel/ExpansionList.tsx

@@ -29,6 +29,7 @@ export const ExpansionList = forwardRef<HTMLDivElement, ExpansionListProps>(
     const { onClick, onFocus, onKeyDown, children, ...remaining } = props;
 
     const { movementContext, movementProps } = useExpansionList({
+      ref,
       onClick,
       onFocus,
       onKeyDown,
@@ -36,7 +37,7 @@ export const ExpansionList = forwardRef<HTMLDivElement, ExpansionListProps>(
 
     return (
       <KeyboardMovementProvider value={movementContext}>
-        <div {...remaining} {...movementProps} ref={ref}>
+        <div {...remaining} {...movementProps}>
           {children}
         </div>
       </KeyboardMovementProvider>

package/src/expansion-panel/useExpansionList.ts

@@ -1,12 +1,9 @@
 "use client";
 
-import type {
-  FocusEventHandler,
-  KeyboardEventHandler,
-  MouseEventHandler,
-} from "react";
-
-import type { KeyboardMovementProviderImplementation } from "../movement/types.js";
+import {
+  type KeyboardMovementProviderImplementation,
+  type SimpleKeyboardMovementWrapperOptions,
+} from "../movement/types.js";
 import { useKeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
 
 /**
@@ -18,11 +15,8 @@ const getPanelsOnly = (container: HTMLElement): readonly HTMLElement[] => [
 ];
 
 /** @since 6.0.0 */
-export interface ExpansionListHookOptions<E extends HTMLElement> {
-  onClick?: MouseEventHandler<E>;
-  onFocus?: FocusEventHandler<E>;
-  onKeyDown?: KeyboardEventHandler<E>;
-}
+export type ExpansionListHookOptions<E extends HTMLElement> =
+  SimpleKeyboardMovementWrapperOptions<E>;
 
 /** @since 6.0.0 */
 export type ExpansionListImplementation<E extends HTMLElement> =

package/src/form/FormMessage.tsx

@@ -38,6 +38,8 @@ export const FormMessage = forwardRef<
     children,
     length,
     maxLength,
+    counterProps,
+    messageProps,
     ...remaining
   } = props;
   const id = useEnsuredId(propId, "form-message");
@@ -48,6 +50,7 @@ export const FormMessage = forwardRef<
     message = (
       <p
         id={`${id}-message`}
+        {...messageProps}
         style={messageStyle}
         className={formMessageText({ className: messageClassName })}
       >
@@ -69,6 +72,7 @@ export const FormMessage = forwardRef<
       {typeof length === "number" && typeof maxLength === "number" && (
         <FormMessageCounter
           id={`${id}-counter`}
+          {...counterProps}
           style={counterStyle}
           className={counterClassName}
         >

package/src/form/FormMessageContainer.tsx

@@ -2,14 +2,18 @@ import { type HTMLAttributes, forwardRef } from "react";
 
 import { type PropsWithRef } from "../types.js";
 import { FormMessage } from "./FormMessage.js";
-import { formMessageContainer } from "./formMessageContainerStyles.js";
+import {
+  type FormMessageContainerClassNameOptions,
+  formMessageContainer,
+} from "./formMessageContainerStyles.js";
 import { type FormMessageProps } from "./types.js";
 
 /**
  * @since 2.5.0
  */
 export interface FormMessageContainerProps
-  extends HTMLAttributes<HTMLDivElement> {
+  extends HTMLAttributes<HTMLDivElement>,
+    FormMessageContainerClassNameOptions {
   /**
    * If the extension doesn't actually want to render the `FormMessage`
    * component, these props are optional. It kind of eliminates the whole
@@ -29,7 +33,7 @@ export const FormMessageContainer = forwardRef<
   HTMLDivElement,
   FormMessageContainerProps
 >(function FormMessageContainer(props, ref) {
-  const { className, children, messageProps, ...remaining } = props;
+  const { className, children, inline, messageProps, ...remaining } = props;
   if (!messageProps) {
     return <>{children}</>;
   }
@@ -38,7 +42,7 @@ export const FormMessageContainer = forwardRef<
     <div
       {...remaining}
       ref={ref}
-      className={formMessageContainer({ className })}
+      className={formMessageContainer({ className, inline })}
     >
       {children}
       <FormMessage {...messageProps} />

package/src/form/FormMessageCounter.tsx

@@ -1,4 +1,9 @@
-import { type HTMLAttributes, type ReactElement, type ReactNode } from "react";
+import {
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+  forwardRef,
+} from "react";
 
 import { formMessageCounter } from "./formMessageStyles.js";
 
@@ -44,15 +49,21 @@ export interface FormMessageCounterProps
  * @see {@link https://react-md.dev/components/form-message | FormMessage Demos}
  * @see {@link https://react-md.dev/components/text-field | TextField Demos}
  * @since 2.9.0
+ * @since 6.3.0 Supports refs.
  */
-export function FormMessageCounter(
-  props: FormMessageCounterProps
-): ReactElement {
+export const FormMessageCounter = forwardRef<
+  HTMLSpanElement,
+  FormMessageCounterProps
+>(function FormMessageCounter(props, ref): ReactElement {
   const { children, className, ...remaining } = props;
 
   return (
-    <span {...remaining} className={formMessageCounter({ className })}>
+    <span
+      ref={ref}
+      {...remaining}
+      className={formMessageCounter({ className })}
+    >
       {children}
     </span>
   );
-}
+});

package/src/form/InputToggle.tsx

@@ -18,6 +18,8 @@ import { FormMessageContainer } from "./FormMessageContainer.js";
 import { InputToggleIcon } from "./InputToggleIcon.js";
 import { Label } from "./Label.js";
 import { type InputToggleSize } from "./inputToggleStyles.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type LabelClassNameOptions } from "./types.js";
 import {
   type FormComponentStates,
   type FormMessageContainerExtension,

package/src/form/Label.tsx

@@ -3,17 +3,6 @@ import { forwardRef } from "react";
 import { label } from "./labelStyles.js";
 import { type LabelProps } from "./types.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-label-floating-x"?: string | number;
-    "--rmd-label-floating-y"?: string | number;
-    "--rmd-label-floating-active-x"?: string | number;
-    "--rmd-label-floating-active-y"?: string | number;
-    "--rmd-label-active-padding"?: string | number;
-    "--rmd-label-active-background-color"?: string;
-  }
-}
-
 /**
  * Most of the form components already use this `Label` internally when a
  * `label` prop has been provided. You should generally use this component if

package/src/form/Listbox.tsx

@@ -1,21 +1,15 @@
-import {
-  type Dispatch,
-  type ReactElement,
-  type ReactNode,
-  type Ref,
-  useMemo,
-} from "react";
+"use client";
+
+import { type ReactElement, type ReactNode, type Ref } from "react";
 
 import { Menu, type MenuProps } from "../menu/Menu.js";
 import { type LabelRequiredForA11y } from "../types.js";
-import { ListboxProvider } from "./ListboxProvider.js";
-import { type OptionSelectedIconProps } from "./Option.js";
-
-/**
- * @since 6.0.0
- * @internal
- */
-export type ListboxValue = string | number | null | object;
+import {
+  ListboxProvider,
+  type ListboxProviderOptions,
+  type ListboxValue,
+  useListboxProvider,
+} from "./ListboxProvider.js";
 
 /**
  * @since 6.0.0
@@ -23,11 +17,8 @@ export type ListboxValue = string | number | null | object;
  */
 export interface ListboxProps<Value extends ListboxValue>
   extends MenuProps,
-    OptionSelectedIconProps {
+    ListboxProviderOptions<Value> {
   nodeRef?: Ref<HTMLDivElement>;
-
-  value: Value | readonly NonNullable<ListboxValue>[];
-  setValue: Dispatch<NonNullable<Value>>;
   children: ReactNode;
 }
 
@@ -49,36 +40,17 @@ export function Listbox<T extends ListboxValue>(
     disableSelectedIcon,
     ...remaining
   } = props;
-  const values = useMemo(() => {
-    if (Array.isArray(value)) {
-      return new Set(value);
-    }
-
-    return new Set([value]);
-  }, [value]);
 
   return (
     <ListboxProvider
-      value={useMemo(
-        () => ({
-          selectOption: setValue,
-          isOptionSelected(option) {
-            return values.has(option);
-          },
-          selectedIcon,
-          unselectedIcon,
-          selectedIconAfter,
-          disableSelectedIcon,
-        }),
-        [
-          disableSelectedIcon,
-          selectedIcon,
-          selectedIconAfter,
-          setValue,
-          unselectedIcon,
-          values,
-        ]
-      )}
+      value={useListboxProvider({
+        value,
+        setValue,
+        selectedIcon,
+        selectedIconAfter,
+        disableSelectedIcon,
+        unselectedIcon,
+      })}
     >
       <Menu {...remaining} ref={nodeRef}>
         {children}

package/src/form/ListboxProvider.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { createContext, useContext } from "react";
+import { type Dispatch, createContext, useContext, useMemo } from "react";
 
 import { type OptionSelectedIconProps } from "./Option.js";
 
@@ -37,3 +37,63 @@ export function useListboxContext(): ListboxContext {
 
   return value;
 }
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export type ListboxValue = string | number | null | object;
+
+/**
+ * @since 6.3.0
+ */
+export interface ListboxProviderOptions<Value extends ListboxValue>
+  extends OptionSelectedIconProps {
+  value: ListboxValue | readonly NonNullable<ListboxValue>[];
+  setValue: Dispatch<NonNullable<Value>>;
+}
+
+/**
+ * @since 6.3.0
+ */
+export function useListboxProvider<Value extends ListboxValue>(
+  options: ListboxProviderOptions<Value>
+): ListboxContext {
+  const {
+    value,
+    setValue,
+    selectedIconAfter,
+    selectedIcon,
+    unselectedIcon,
+    disableSelectedIcon,
+  } = options;
+
+  const values = useMemo(() => {
+    if (Array.isArray(value)) {
+      return new Set(value);
+    }
+
+    return new Set([value]);
+  }, [value]);
+
+  return useMemo(
+    () => ({
+      selectOption: setValue,
+      isOptionSelected(option) {
+        return values.has(option);
+      },
+      selectedIcon,
+      unselectedIcon,
+      selectedIconAfter,
+      disableSelectedIcon,
+    }),
+    [
+      disableSelectedIcon,
+      selectedIcon,
+      selectedIconAfter,
+      setValue,
+      unselectedIcon,
+      values,
+    ]
+  );
+}

package/src/form/NativeSelect.tsx

@@ -161,6 +161,7 @@ export const NativeSelect = forwardRef<HTMLSelectElement, NativeSelectProps>(
 
     return (
       <FormMessageContainer
+        inline={inline}
         {...messageContainerProps}
         messageProps={
           messageProps && {