@react-md/core 1.0.0-next.12 → 1.0.0-next.14

package/src/form/useSlider.ts

@@ -4,7 +4,7 @@ import { type UseStateInitializer, type UseStateSetter } from "../types.js";
 import { getRangeDefaultValue } from "../utils/getRangeDefaultValue.js";
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface SliderValueOptions {
   /**
@@ -32,7 +32,7 @@ export interface SliderValueOptions {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface SliderState {
   value: number;
@@ -40,14 +40,14 @@ export interface SliderState {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface SliderImplementation
   extends Required<SliderValueOptions>,
     SliderState {}
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface SliderOptions extends SliderValueOptions {
   /**
@@ -57,8 +57,7 @@ export interface SliderOptions extends SliderValueOptions {
 }
 
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import { Form, Slider, useSlider } from "@react-md/core";
  * import type { ReactElement } from "react";
@@ -85,9 +84,8 @@ export interface SliderOptions extends SliderValueOptions {
  * ```
  *
  * @see The `Slider` component for additional examples.
- * @remarks
- * \@since 2.5.0
- * \@since 6.0.0 Now returns an object instead of an ordered tuple and only
+ * @since 2.5.0
+ * @since 6.0.0 Now returns an object instead of an ordered tuple and only
  * return the `value` and `setValue` instead of all the slider functionality. In
  * addition, the hook only accepts a single object argument.
  */

package/src/form/useTextField.ts

@@ -35,15 +35,14 @@ const noop = (): void => {
 };
 
 /**
- * @remarks
- * \@since 2.5.0
- * \@since 6.0.0 Added the `onInvalid` handler
+ * @since 2.5.0
+ * @since 6.0.0 Added the `onInvalid` handler
  */
 export type TextFieldChangeHandlers<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > = Pick<HTMLAttributes<E>, "onBlur" | "onChange" | "onInvalid">;
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ErrorChangeHandlerOptions<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > {
@@ -89,15 +88,14 @@ export interface ErrorChangeHandlerOptions<
  * <Button type="submit" disabled={invalid} onClick={submitForm}>Submit</Button>
  * ```
  *
- * @remarks
- * \@since 2.5.0
- * \@since 6.0.0 Changed to object argument.
+ * @since 2.5.0
+ * @since 6.0.0 Changed to object argument.
  */
 export type ErrorChangeHandler<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > = (options: ErrorChangeHandlerOptions<E>) => void;
 
-/** @remarks \@since 2.5.6 */
+/** @since 2.5.6 */
 export interface TextFieldHookState {
   /**
    * The current value for the `TextField` or `TextArea`.
@@ -121,7 +119,7 @@ export interface TextFieldHookState {
  * All the props that will be generated and return from the `useTextField` hook
  * that should be passed to a `FormMessage` component.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface ProvidedFormMessageProps
   extends Pick<FormMessageProps, "id" | "theme" | "children">,
@@ -132,7 +130,7 @@ export interface ProvidedFormMessageProps
  * All the props that will be generated and returned by the `useTextField` hook
  * that should be passed to a `TextField` component.
  *
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface ProvidedTextFieldProps<
   E extends HTMLInputElement | HTMLTextAreaElement,
@@ -144,13 +142,13 @@ export interface ProvidedTextFieldProps<
    * A ref that must be passed to the `TextField`/`TextArea` so that the custom
    * validity behavior can work.
    *
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   ref: RefCallback<E>;
 }
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface ProvidedTextFieldMessageProps<
   E extends HTMLInputElement | HTMLTextAreaElement,
@@ -162,7 +160,7 @@ export interface ProvidedTextFieldMessageProps<
   messageProps: ProvidedFormMessageProps;
 }
 
-/** @remarks \@since 2.5.6 */
+/** @since 2.5.6 */
 export interface TextFieldHookOptions<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > extends TextFieldValidationOptions,
@@ -182,8 +180,7 @@ export interface TextFieldHookOptions<
    * `<textarea>` DOM node, you can use the `fieldRef` returned by this hook
    * instead.
    *
-   * @example
-   * Accessing TextField DOM Node
+   * @example Accessing TextField DOM Node
    * ```tsx
    * import { TextField, useTextField } from "@react-md/core";
    * import { useEffect } from "react";
@@ -315,7 +312,7 @@ export interface TextFieldHookOptions<
   validationType?: TextFieldValidationType;
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface TextFieldImplementation<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > extends TextFieldHookState {
@@ -325,14 +322,14 @@ export interface TextFieldImplementation<
   fieldProps: ProvidedTextFieldProps<E>;
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface TextFieldWithMessageImplementation<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > extends TextFieldImplementation<E> {
   fieldProps: ProvidedTextFieldMessageProps<E>;
 }
 
-/** @remarks \@since 6.0.0 */
+/** @since 6.0.0 */
 export interface ValidatedTextFieldImplementation<
   E extends HTMLInputElement | HTMLTextAreaElement,
 > extends TextFieldImplementation<E> {
@@ -343,8 +340,7 @@ export interface ValidatedTextFieldImplementation<
  * If you do not want to display the error messages below the `TextField` and
  * handle error messages separately, set the `disableMessage` option to `true`.
  *
- * @example
- * No Inline Error Messages
+ * @example No Inline Error Messages
  * ```tsx
  * import type { ReactElement } from "react";
  * import { TextField, useTextField } from "@react-md/core";
@@ -366,8 +362,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
 ): TextFieldImplementation<E>;
 
 /**
- * @example
- * Simple Example
+ * @example Simple Example
  * ```tsx
  * import type { ReactElement } from "react";
  * import { TextField, useTextField } from "@react-md/core";
@@ -381,8 +376,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * }
  * ```
  *
- * @example
- * Inline Counter
+ * @example Inline Counter
  * ```tsx
  * import type { ReactElement } from "react";
  * import { TextField, useTextField } from "@react-md/core";
@@ -400,8 +394,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * }
  * ```
  *
- * @example
- * Adding Constraints
+ * @example Adding Constraints
  * ```tsx
  * import type { ReactElement } from "react";
  * import { TextField, useTextField } from "@react-md/core";
@@ -419,8 +412,7 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * }
  * ```
  *
- * @example
- * Custom Validation
+ * @example Custom Validation
  * ```tsx
  * import type { ReactElement } from "react";
  * import { TextField, useTextField } from "@react-md/core";
@@ -468,9 +460,8 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * ```
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
- * @remarks
- * \@since 2.5.6
- * \@since 6.0.0 This hook returns an object instead of an ordered list.
+ * @since 2.5.6
+ * @since 6.0.0 This hook returns an object instead of an ordered list.
  */
 export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
   options: TextFieldHookOptions<E>

package/src/form/useTextFieldContainerAddons.ts

@@ -0,0 +1,195 @@
+"use client";
+import {
+  useCallback,
+  useState,
+  type CSSProperties,
+  type Ref,
+  type RefCallback,
+} from "react";
+import { useResizeObserver } from "../useResizeObserver.js";
+import { getFormConfig } from "./formConfig.js";
+import { type FormTheme } from "./types.js";
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+interface AddonPaddingOptions {
+  ref?: Ref<HTMLSpanElement>;
+  addon: boolean;
+  theme: FormTheme;
+  extra: string;
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+function useAddonPadding(
+  options: AddonPaddingOptions
+): [padding: string | undefined, addonRef: RefCallback<HTMLSpanElement>] {
+  const { ref, addon, theme, extra } = options;
+  const [padding, setPadding] = useState<string | undefined>();
+  const addonRef = useResizeObserver({
+    ref,
+    onUpdate: useCallback(
+      (entry) => {
+        const inlineSize = entry.borderBoxSize[0]?.inlineSize;
+        if (typeof inlineSize !== "number") {
+          return;
+        }
+
+        // the leading space for the extra calc is required
+        setPadding(
+          `calc(var(--rmd-text-field-${theme}d-padding) + ${inlineSize}px${extra ? ` ${extra}` : ""})`
+        );
+      },
+      [extra, theme]
+    ),
+    disabled: !addon,
+    disableHeight: true,
+  });
+
+  return [padding, addonRef];
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface TextFieldContainerAddonsOptions {
+  /**
+   * This style will automatically be merged with the returned `style`.
+   */
+  style?: CSSProperties;
+
+  /** @defaultValue `getFormConfig("theme")` */
+  theme?: FormTheme;
+
+  /**
+   * Set this to `true` if the `leftAddon` should be watched for size changes.
+   */
+  leftAddon: boolean;
+
+  /**
+   * An optional ref that will be merged with the returned
+   * {@link TextFieldContainerAddonsImplementation.leftAddonRef}.
+   */
+  leftAddonRef?: Ref<HTMLSpanElement>;
+
+  /**
+   * This can be used to update the CSS `calc()` expression to change the
+   * padding.
+   *
+   * @example Add an additional 0.25rem padding
+   * ```
+   * leftAddonExtraCalc="+ 0.25rem"
+   * ```
+   *
+   * @defaultValue `""`
+   */
+  leftAddonExtraCalc?: string;
+
+  /**
+   * Set this to `true` if the `rightAddon` should be watched for size changes.
+   */
+  rightAddon: boolean;
+
+  /**
+   * An optional ref that will be merged with the returned
+   * {@link TextFieldContainerAddonsImplementation.rightAddonRef}.
+   */
+  rightAddonRef?: Ref<HTMLSpanElement>;
+
+  /**
+   * This can be used to update the CSS `calc()` expression to change the
+   * padding.
+   *
+   * @example Add an additional 0.25rem padding
+   * ```
+   * leftAddonExtraCalc="+ 0.25rem"
+   * ```
+   *
+   * @defaultValue `""`
+   */
+  rightAddonExtraCalc?: string;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface TextFieldContainerAddonsImplementation {
+  style?: CSSProperties;
+  leftAddonRef: RefCallback<HTMLSpanElement>;
+  rightAddonRef: RefCallback<HTMLSpanElement>;
+}
+
+/**
+ * This hook can be used to automatically update the padding on the
+ * `TextFieldContainer` based on the size of the `leftAddon` and `rightAddon`.
+ *
+ * @example Simple Example
+ * ```tsx
+ * const { style, leftAddonRef, rightAddonRef } = useTextFieldContainerAddons({
+ *   leftAddon: true,
+ *   rightAddon: true,
+ * });
+ *
+ * return (
+ *   <TextField
+ *     style={style}
+ *     leftAddon={<SomeDynamicAddon />}
+ *     leftAddonProps={{ ref: leftAddonRef }}
+ *     rightAddon={<SomeDynamicAddon />}
+ *     rightAddonProps={{ ref: rightAddonRef }}
+ *   />
+ * );
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function useTextFieldContainerAddons(
+  options: TextFieldContainerAddonsOptions
+): TextFieldContainerAddonsImplementation {
+  const {
+    style: propStyle,
+    theme: propTheme,
+    leftAddon,
+    rightAddon,
+    leftAddonRef: propLeftAddonRef,
+    rightAddonRef: propRightAddonRef,
+    leftAddonExtraCalc = "",
+    rightAddonExtraCalc = "",
+  } = options;
+  const theme = getFormConfig("theme", propTheme);
+
+  const [paddingLeft, leftAddonRef] = useAddonPadding({
+    ref: propLeftAddonRef,
+    theme,
+    addon: leftAddon,
+    extra: `+ var(--rmd-addon-spacing)${leftAddonExtraCalc ? ` ${leftAddonExtraCalc}` : ""}`,
+  });
+
+  const [paddingRight, rightAddonRef] = useAddonPadding({
+    ref: propRightAddonRef,
+    theme,
+    addon: rightAddon,
+    extra: rightAddonExtraCalc,
+  });
+
+  let style = propStyle;
+  if (typeof paddingLeft === "string" || typeof paddingRight === "string") {
+    style = {
+      ...propStyle,
+      "--rmd-text-field-padding-left":
+        paddingLeft ?? propStyle?.["--rmd-text-field-padding-left"],
+      "--rmd-text-field-padding-right":
+        paddingRight ?? propStyle?.["--rmd-text-field-padding-right"],
+    };
+  }
+
+  return {
+    style,
+    leftAddonRef,
+    rightAddonRef,
+  };
+}

package/src/form/utils.ts

@@ -17,11 +17,10 @@ import { type KeyboardEvent } from "react";
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit
  * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/submit
  * @internal
- * @remarks
- * \@since 2.7.0
- * \@since 6.0.0 No longer returns a boolean, added the `formId` parameter, and
+ * @since 2.7.0
+ * @since 6.0.0 No longer returns a boolean, added the `formId` parameter, and
  * moved into the form package.
- * \@since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button
+ * @since 6.0.0 Uses `form.requestSubmit` instead of clicking the submit button
  */
 export function tryToSubmitRelatedForm<E extends HTMLElement>(
   event: KeyboardEvent<E>,
@@ -52,19 +51,19 @@ export function tryToSubmitRelatedForm<E extends HTMLElement>(
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type EditableHTMLElement = HTMLInputElement | HTMLTextAreaElement;
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ChangeableHTMLElement = EditableHTMLElement | HTMLSelectElement;
 
 /**
  * @internal
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function isChangeableHTMLElement(
   element: Element | null
@@ -77,7 +76,7 @@ export function isChangeableHTMLElement(
  *
  * @internal
  * @see https://stackoverflow.com/a/46012210
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export function triggerManualChangeEvent(
   element: ChangeableHTMLElement | null,

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,7 @@ export type TextFieldValidationType =
   | readonly (keyof ValidityState)[];
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface ErrorMessageOptions extends TextFieldValidationOptions {
   /**
@@ -84,13 +84,13 @@ 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
  */
 const VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "badInput",
@@ -107,7 +107,7 @@ const VALIDITY_STATE_KEYS: readonly (keyof ValidityState)[] = [
 
 /**
  * @internal
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export const RECOMMENDED_STATE_KEYS: readonly (keyof ValidityState)[] = [
   "badInput",
@@ -117,7 +117,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 +135,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 +153,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 +185,7 @@ export const defaultGetErrorMessage: GetErrorMessage = (options) => {
 };
 
 /**
- * @remarks \@since 2.5.0
+ * @since 2.5.0
  */
 export interface IsErroredOptions extends ErrorMessageOptions {
   /**
@@ -201,7 +201,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 +211,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 +224,7 @@ export const defaultIsErrored: IsErrored = (options) => {
 };
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface GetErrorIconOptions {
   /**
@@ -249,8 +249,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 +258,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

@@ -5,7 +5,7 @@ import type { UseStateInitializer, UseStateSetter } from "../types.js";
 import type { SimpleHoverModeContext } from "./useHoverModeProvider.js";
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
   /** @defaultValue `false` */
@@ -23,7 +23,7 @@ export interface HoverModeConfigurationOptions extends SimpleHoverModeContext {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeOptions
   extends HoverModeConfigurationOptions {
@@ -31,7 +31,7 @@ export interface ControlledHoverModeOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface ControlledHoverModeImplementation {
   startShowFlow(id?: string | MouseEvent): void;
@@ -40,7 +40,7 @@ export interface ControlledHoverModeImplementation {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeOptions
   extends HoverModeConfigurationOptions {
@@ -48,7 +48,7 @@ export interface UncontrolledHoverModeOptions
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface UncontrolledHoverModeImplementation
   extends ControlledHoverModeImplementation {
@@ -57,7 +57,7 @@ export interface UncontrolledHoverModeImplementation
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export interface HoverModeImplementation
   extends ControlledHoverModeImplementation {
@@ -66,11 +66,10 @@ export interface HoverModeImplementation
 }
 
 /**
- * @remarks
- * \@since 2.8.0
- * \@since 5.0.0 This hook no longer returns `handlers` or
+ * @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(