@react-md/core 6.2.0 → 6.3.0

package/src/datetime/NativeDateField.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import { forwardRef } from "react";
+
+import { TextField, type TextFieldProps } from "../form/TextField.js";
+import { type DateFieldOptions, useDateField } from "./useDateField.js";
+
+/** @since 6.3.0 */
+export interface NativeDateFieldProps
+  extends Omit<TextFieldProps, keyof DateFieldOptions | "value">,
+    Omit<DateFieldOptions, "ref"> {}
+
+/**
+ * The `NativeDateField` is a simple wrapper around the `TextField` using the
+ * `useDateField` hook.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { NativeDateField } from "@react-md/core/datetime/NativeDateField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   return <NativeDateField label="Delivery Date" name="delivery" />;
+ * }
+ * ```
+ *
+ * @see {@link https://react-md.dev/components/native-time-field | NativeDateField Demos}
+ * @see {@link https://react-md.dev/components/text-field | TextField Demos}
+ * @since 6.3.0
+ */
+export const NativeDateField = forwardRef<
+  HTMLInputElement,
+  NativeDateFieldProps
+>(function NativeDateField(props, ref) {
+  const {
+    id,
+    min,
+    max,
+    step,
+    onBlur,
+    onInvalid,
+    onChange,
+    helpText,
+    required,
+    validationType,
+    disableMessage,
+    errorIcon,
+    isErrored,
+    getErrorIcon,
+    getErrorMessage,
+    onErrorChange,
+    disableReset,
+    defaultValue,
+    ...remaining
+  } = props;
+  const { name, form } = props;
+  const { fieldProps } = useDateField({
+    id,
+    ref,
+    name,
+    form,
+    min,
+    max,
+    step,
+    onBlur,
+    onChange,
+    onInvalid,
+    helpText,
+    required,
+    validationType,
+    disableMessage: disableMessage ?? (!min && !max && !step && !required),
+    errorIcon,
+    isErrored,
+    getErrorIcon,
+    getErrorMessage,
+    onErrorChange,
+    disableReset,
+    defaultValue,
+  });
+
+  let { messageProps } = remaining;
+  if (fieldProps.messageProps) {
+    messageProps = {
+      ...fieldProps.messageProps,
+      ...remaining.messageProps,
+    };
+  }
+
+  return (
+    <TextField {...remaining} {...fieldProps} messageProps={messageProps} />
+  );
+});

package/src/datetime/NativeTimeField.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { forwardRef } from "react";
+
+import { TextField, type TextFieldProps } from "../form/TextField.js";
+import { type TimeFieldOptions, useTimeField } from "./useTimeField.js";
+
+/**
+ * @since 6.3.0
+ */
+export interface NativeTimeFieldProps
+  extends Omit<TextFieldProps, keyof TimeFieldOptions | "value">,
+    Omit<TimeFieldOptions, "ref"> {}
+
+/**
+ * The `NativeTimeField` is a simple wrapper around the `TextField` using the
+ * `useTimeField` hook.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { NativeTimeField } from "@react-md/core/datetime/NativeTimeField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   return <NativeTimeField label="Time" name="appt" />;
+ * }
+ * ```
+ *
+ * @see {@link https://react-md.dev/components/native-time-field | NativeTimeField Demos}
+ * @see {@link https://react-md.dev/components/text-field | TextField Demos}
+ * @since 6.3.0
+ */
+export const NativeTimeField = forwardRef<
+  HTMLInputElement,
+  NativeTimeFieldProps
+>(function NativeTimeField(props, ref) {
+  const {
+    id,
+    min,
+    max,
+    step,
+    onBlur,
+    onInvalid,
+    onChange,
+    helpText,
+    required,
+    validationType,
+    disableMessage,
+    errorIcon,
+    isErrored,
+    getErrorIcon,
+    getErrorMessage,
+    onErrorChange,
+    disableReset,
+    defaultValue,
+    ...remaining
+  } = props;
+  const { name, form } = props;
+  const { fieldProps } = useTimeField({
+    id,
+    ref,
+    name,
+    form,
+    min,
+    max,
+    step,
+    onBlur,
+    onChange,
+    onInvalid,
+    helpText,
+    required,
+    validationType,
+    disableMessage: disableMessage ?? (!min && !max && !step && !required),
+    errorIcon,
+    isErrored,
+    getErrorIcon,
+    getErrorMessage,
+    onErrorChange,
+    disableReset,
+    defaultValue,
+  });
+
+  let { messageProps } = remaining;
+  if (fieldProps.messageProps) {
+    messageProps = {
+      ...fieldProps.messageProps,
+      ...remaining.messageProps,
+    };
+  }
+
+  return (
+    <TextField {...remaining} {...fieldProps} messageProps={messageProps} />
+  );
+});

package/src/datetime/useDateField.ts

@@ -0,0 +1,193 @@
+"use client";
+
+import { type InputHTMLAttributes, useRef } from "react";
+
+import {
+  type ProvidedFormMessageProps,
+  type ProvidedTextFieldProps,
+  type TextFieldHookOptions,
+  type TextFieldImplementation,
+  type TextFieldWithMessageImplementation,
+  useTextField,
+} from "../form/useTextField.js";
+
+/**
+ * @since 6.3.0
+ */
+export interface DateFieldConstraints {
+  /**
+   * This **must** be in the format `yyyy-mm-dd`
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date#min | min attribute}
+   */
+  min?: string;
+
+  /**
+   * This **must** be in the format `yyyy-mm-dd`
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date#max | max attribute}
+   */
+  max?: string;
+
+  /**
+   * For date inputs, the value of step is given in days; and is treated as a
+   * number of milliseconds equal to 86,400,000 times the step value (the
+   * underlying numeric value is in milliseconds). The default value of step is
+   * 1, indicating 1 day.
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/date#step | step attribute}
+   */
+  step?: number | "any";
+}
+
+/** @since 6.3.0 */
+export interface DateFieldOptions
+  extends Omit<
+      TextFieldHookOptions,
+      | "isNumber"
+      | "counter"
+      | "pattern"
+      | "maxLength"
+      | "minLength"
+      | "disableMaxLength"
+    >,
+    DateFieldConstraints {}
+
+/** @since 6.3.0 */
+export interface ProvidedDateFieldProps
+  extends Omit<ProvidedTextFieldProps, "value">,
+    Omit<DateFieldConstraints, "step"> {
+  type: "date";
+  step?: number | "any";
+  defaultValue: Required<InputHTMLAttributes<HTMLInputElement>>["defaultValue"];
+}
+
+/** @since 6.3.0 */
+export interface ProvidedDateFieldMessageProps extends ProvidedDateFieldProps {
+  /**
+   * 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 DateFieldImplementation
+  extends Omit<TextFieldImplementation, "fieldProps"> {
+  fieldProps: ProvidedDateFieldProps;
+}
+
+/** @since 6.3.0 */
+export interface DateFieldWithMessageImplementation
+  extends Omit<TextFieldWithMessageImplementation, "fieldProps"> {
+  fieldProps: ProvidedDateFieldMessageProps;
+}
+
+/** @since 6.3.0 */
+export interface ValidatedDateFieldImplementation
+  extends DateFieldImplementation {
+  fieldProps: ProvidedDateFieldProps | ProvidedDateFieldMessageProps;
+}
+
+/**
+ * The `useDateField` is a small wrapper around the {@link useTextField} to be used
+ * with `<input type="date" />`. It is used in the `NativeDateField` if an example
+ * implementation would like to be seen.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { useDateField } from "@react-md/core/datetime/useDateField";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, fieldProps, error, errorMessage } = useDateField({
+ *     name: "delivery",
+ *     required: true,
+ *     min: "2025-01-01",
+ *     max: "2026-01-01",
+ *     disableMessage: true,
+ *   });
+ *
+ *   // value: `""` or `"yyyy-mm-dd"`
+ *
+ *   return <TextField label="Delivery Date" {...fieldProps} />
+ * }
+ * ```
+ *
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-date-field | NativeDateField Demos}
+ * @see {@link https://react-md.dev/hooks/use-date-field | useDateField Demos}
+ */
+export function useDateField(
+  options: DateFieldOptions & { disableMessage: true }
+): DateFieldImplementation;
+
+/**
+ * The `useDateField` is a small wrapper around the {@link useTextField} to be used
+ * with `<input type="date" />`. It is used in the `NativeDateField` if an example
+ * implementation would like to be seen.
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { useDateField } from "@react-md/core/datetime/useDateField";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { value, fieldProps } = useDateField({
+ *     name: "delivery",
+ *     required: true,
+ *     min: "2025-01-01",
+ *     max: "2026-01-01",
+ *   });
+ *
+ *   // value: `""` or `"yyyy-mm-dd"`
+ *
+ *   return <TextField label="Delivery Date" {...fieldProps} />
+ * }
+ * ```
+ *
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-date-field | NativeDateField Demos}
+ * @see {@link https://react-md.dev/hooks/use-date-field | useDateField Demos}
+ */
+export function useDateField(
+  options: DateFieldOptions
+): DateFieldWithMessageImplementation;
+
+/**
+ * @since 6.3.0
+ * @see {@link https://react-md.dev/components/native-date-field | NativeTimeField Demos}
+ * @see {@link https://react-md.dev/hooks/use-date-field | useTimeField Demos}
+ */
+export function useDateField(
+  options: DateFieldOptions
+): ValidatedDateFieldImplementation {
+  const { min, max, step, ...fieldOptions } = options;
+  const { 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,
+    fieldProps: {
+      ...allowedFieldProps,
+      defaultValue: initial.current,
+      min,
+      max,
+      step,
+      type: "date",
+    },
+  };
+}

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