@react-md/core 6.2.1 → 6.3.1

package/src/card/styles.ts

@@ -3,7 +3,14 @@ import { cnb } from "cnbuilder";
 import { cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 
-const cardStyles = bem("rmd-card");
+const styles = bem("rmd-card");
+
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-card-background-color"?: string;
+    "--rmd-card-color"?: string;
+  }
+}
 
 /** @since 6.0.0 */
 export interface CardClassNameOptions {
@@ -42,7 +49,7 @@ export function card(options: CardClassNameOptions = {}): string {
   const { className, bordered, raisable, interactable } = options;
 
   return cnb(
-    cardStyles({
+    styles({
       bordered,
       shadowed: !bordered,
       raisable: !bordered && raisable,
@@ -70,7 +77,7 @@ export function cardHeader(options: CardHeaderClassNameOptions = {}): string {
   const { className, addonAfter = false, addonBefore = false } = options;
 
   return cnb(
-    cardStyles("header", {
+    styles("header", {
       "addon-after": addonAfter && !addonBefore,
       "addon-before": addonBefore && !addonAfter,
       surrounded: addonAfter && addonBefore,
@@ -92,7 +99,7 @@ export function cardHeaderContent(
 ): string {
   const { className } = options;
 
-  return cnb(cardStyles("header-content"), className);
+  return cnb(styles("header-content"), className);
 }
 
 /** @since 6.0.0 */
@@ -106,7 +113,7 @@ export interface CardTitleClassNameOptions {
 export function cardTitle(options: CardTitleClassNameOptions = {}): string {
   const { className } = options;
 
-  return cnb(cardStyles("title"), className);
+  return cnb(styles("title"), className);
 }
 
 /** @since 6.0.0 */
@@ -122,7 +129,7 @@ export function cardSubtitle(
 ): string {
   const { className } = options;
 
-  return cnb(cardStyles("subtitle"), className);
+  return cnb(styles("subtitle"), className);
 }
 
 /** @since 6.0.0 */
@@ -165,7 +172,7 @@ export function cardContent(options: CardContentClassNameOptions = {}): string {
   } = options;
 
   return cnb(
-    cardStyles("content", {
+    styles("content", {
       padded: !disablePadding,
       "padding-bottom": !disableLastChildPadding,
     }),
@@ -187,5 +194,5 @@ export interface CardFooterClassNameOptions {
 export function cardFooter(options: CardFooterClassNameOptions = {}): string {
   const { className } = options;
 
-  return cnb(cardStyles("footer"), className);
+  return cnb(styles("footer"), className);
 }

package/src/chip/Chip.tsx

@@ -14,33 +14,27 @@ import { getIcon } from "../icon/config.js";
 import { type ComponentWithRippleProps } from "../interaction/types.js";
 import { useElementInteraction } from "../interaction/useElementInteraction.js";
 import { useHigherContrastChildren } from "../interaction/useHigherContrastChildren.js";
-import { useMaxWidthTransition } from "../transition/useMaxWidthTransition.js";
+import {
+  type BaseMaxWidthTransitionOptions,
+  useMaxWidthTransition,
+} from "../transition/useMaxWidthTransition.js";
 import { type PropsWithRef } from "../types.js";
-import { chip, chipContent } from "./styles.js";
-
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-chip-solid-background-color"?: string;
-    "--rmd-chip-solid-disabled-background-color"?: string;
-    "--rmd-chip-solid-color"?: string;
-    "--rmd-chip-theme-background-color"?: string;
-    "--rmd-chip-theme-color"?: string;
-    "--rmd-chip-outline-background-color"?: string;
-    "--rmd-chip-outline-color"?: string;
-  }
-}
+import { type ChipTheme, chip, chipContent } from "./styles.js";
 
 /**
  * @since 6.0.0 Renamed the `noninteractive` prop to
  * `noninteractable`.
+ * @since 6.3.1 Extends BaseMaxWidthTransitionOptions for CSSProperties module
+ * augmentation.
  */
 export interface ChipProps
   extends ButtonHTMLAttributes<HTMLButtonElement>,
+    BaseMaxWidthTransitionOptions,
     ComponentWithRippleProps {
   /**
    * @defaultValue `"solid"`
    */
-  theme?: "outline" | "solid";
+  theme?: ChipTheme;
 
   /**
    * Set this to `true` if the chip should gain additional box shadow while the

package/src/chip/styles.ts

@@ -5,6 +5,30 @@ import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-chip");
 
+declare module "react" {
+  interface CSSProperties {
+    "--rmd-chip-gap"?: string;
+    "--rmd-chip-height"?: string;
+    "--rmd-chip-border-radius"?: string | number;
+    "--rmd-chip-horizontal-padding"?: string | number;
+    "--rmd-chip-vertical-padding"?: string | number;
+    "--rmd-chip-solid-background-color"?: string;
+    "--rmd-chip-solid-disabled-background-color"?: string;
+    "--rmd-chip-solid-color"?: string;
+    "--rmd-chip-theme-background-color"?: string;
+    "--rmd-chip-theme-color"?: string;
+    "--rmd-chip-outline-color"?: string;
+    "--rmd-chip-outline-width"?: string | number;
+    "--rmd-chip-outline-background-color"?: string;
+    "--rmd-chip-outline-text-color"?: string;
+  }
+}
+
+/**
+ * @since 6.3.1
+ */
+export type ChipTheme = "outline" | "solid";
+
 /**
  * @since 6.0.0
  *
@@ -39,10 +63,14 @@ const styles = bem("rmd-chip");
  */
 export interface ChipClassNameOptions {
   className?: string;
+
+  /**
+   * An optional className to provide only while {@link selected} is `true`.
+   */
   selectedClassName?: string;
 
   /** @defaultValue `"solid"` */
-  theme?: "outline" | "solid";
+  theme?: ChipTheme;
 
   backgroundColor?: BackgroundColor;
 

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",
+    },
+  };
+}