@react-md/core 6.3.3 → 6.4.0

package/src/spinbutton/useSpinButton.ts

@@ -0,0 +1,311 @@
+"use client";
+
+import { type Dispatch, useCallback, useRef, useState } from "react";
+
+import { tryToSubmitRelatedForm } from "../form/utils.js";
+import { useEnsuredId } from "../useEnsuredId.js";
+import { useEnsuredRef } from "../useEnsuredRef.js";
+import { useEnsuredState } from "../useEnsuredState.js";
+import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
+import { withinRange } from "../utils/withinRange.js";
+import { useSpinButtonGroup } from "./SpinButtonGroupProvider.js";
+import {
+  defaultGetSpinButtonTextContent,
+  defaultSpinButtonGetValueText,
+} from "./defaults.js";
+import {
+  type SpinButtonChangeEvent,
+  type SpinButtonChangeEventOptions,
+  type SpinButtonImplementation,
+  type SpinButtonOptions,
+  type SpinButtonValue,
+} from "./types.js";
+import { deselectNode } from "./utils/deselectNode.js";
+import { resolveInputEvent } from "./utils/resolveInputEvent.js";
+import { selectNode } from "./utils/selectNode.js";
+
+/**
+ * @since 6.4.0
+ */
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * @since 6.4.0
+ */
+export function useSpinButton<E extends HTMLElement = HTMLDivElement>(
+  options: SpinButtonOptions<E>
+): SpinButtonImplementation<E> {
+  const {
+    id: propId,
+    ref: propRef,
+    min,
+    max,
+    step = 1,
+    minDigits,
+    maxDigits,
+    form,
+    readOnly,
+    disabled,
+    required,
+    error,
+    onBlur = noop,
+    onFocus = noop,
+    onInput = noop,
+    onClick = noop,
+    onKeyDown = noop,
+    fallback,
+    mappings,
+    value: propValue,
+    onValueChange = noop,
+    defaultValue = null,
+    getValueText = defaultSpinButtonGetValueText,
+    getTextContent = defaultGetSpinButtonTextContent,
+    placeholderChar,
+    defaultKeyboardValue,
+  } = options;
+  const id = useEnsuredId(propId, "spinbutton");
+
+  // trigger a noop setValue when `value` and `onValueChange` are provided
+  // since `onValueChange is always called with  `setValue
+  let propSetValue: Dispatch<SpinButtonValue> | undefined;
+  if (typeof propValue !== "undefined" && options.onValueChange) {
+    propSetValue = noop;
+  }
+
+  const [value, setValue] = useEnsuredState({
+    value: propValue,
+    setValue: propSetValue,
+    defaultValue,
+  });
+
+  const focused = useRef(false);
+  const typedCount = useRef(0);
+  const prevText = useRef("");
+  const [nodeRef, nodeRefCallback] = useEnsuredRef(propRef);
+  const { focusNext } = useSpinButtonGroup();
+  const [keyboardValue] = useState(defaultKeyboardValue);
+
+  // NOTE: I might be able to get rid of this since I don't remember why it was
+  // added maybe for controlled fields? I'll have to see when I get to the
+  // date/time components again
+  useIsomorphicLayoutEffect(() => {
+    const node = nodeRef.current;
+    if (!focused.current || !node) {
+      return;
+    }
+
+    prevText.current = node.textContent || "";
+    selectNode(node);
+  }, [nodeRef, value]);
+
+  const updateValue = useCallback(
+    (options: SpinButtonChangeEventOptions<E>) => {
+      setValue(options.value);
+      onValueChange(options);
+      if (options.reason === "typed-to-completion") {
+        focusNext();
+      }
+    },
+    [focusNext, onValueChange, setValue]
+  );
+  const increment = useCallback(
+    (event: SpinButtonChangeEvent<E>) => {
+      let nextValue: SpinButtonValue =
+        value ?? keyboardValue ?? min ?? max ?? 0;
+      nextValue = withinRange({ min, max, value: nextValue + step });
+
+      // this actually means both min and max are a number
+      if (nextValue === value && typeof min === "number") {
+        nextValue = min;
+      }
+
+      updateValue({
+        event,
+        reason: "change",
+        value: nextValue,
+      });
+    },
+    [keyboardValue, max, min, step, updateValue, value]
+  );
+  const decrement = useCallback(
+    (event: SpinButtonChangeEvent<E>) => {
+      let nextValue: SpinButtonValue =
+        value ?? keyboardValue ?? max ?? min ?? 0;
+      nextValue = withinRange({ min, max, value: nextValue - step });
+
+      // this actually means both min and max are a number
+      if (nextValue === value && typeof max === "number") {
+        nextValue = max;
+      }
+
+      updateValue({
+        event,
+        reason: "change",
+        value: nextValue,
+      });
+    },
+    [keyboardValue, max, min, step, updateValue, value]
+  );
+
+  return {
+    value,
+    setValue,
+    spinButtonRef: nodeRef,
+    spinButtonProps: {
+      "aria-readonly": readOnly || undefined,
+      "aria-disabled": disabled || undefined,
+      "aria-invalid": error || undefined,
+      "aria-required": required || undefined,
+      "aria-valuemin": min,
+      "aria-valuemax": max,
+      "aria-valuenow": value === null ? undefined : value,
+      "aria-valuetext": getValueText(value),
+      id,
+      ref: nodeRefCallback,
+      role: "spinbutton",
+      autoCapitalize: "none",
+      autoCorrect: "off",
+      spellCheck: false,
+      inputMode: "numeric",
+      contentEditable: !disabled || undefined,
+      suppressContentEditableWarning: true,
+      tabIndex: disabled ? undefined : 0,
+      onBlur: (event) => {
+        onBlur(event);
+
+        focused.current = false;
+        deselectNode(event.currentTarget);
+      },
+      onFocus: (event) => {
+        onFocus(event);
+
+        if (disabled) {
+          return;
+        }
+
+        focused.current = true;
+        typedCount.current = 0;
+        selectNode(event.currentTarget);
+      },
+      onKeyDown: (event) => {
+        onKeyDown(event);
+
+        if (disabled || (readOnly && event.key !== "Enter")) {
+          return;
+        }
+
+        const setValue = (nextValue: number): void =>
+          updateValue({ value: nextValue, event, reason: "change" });
+
+        let stop = false;
+        switch (event.key) {
+          case "ArrowRight":
+          case "ArrowLeft":
+            // `event.stopPropagation()` should not be called here since the
+            // parent `useSpinButtonGroup` keyboard event handler should
+            // still be called to handle advancing to the next spinbutton in
+            // the group. Only the default cursor movement needs to be disabled
+            // instead.
+            event.preventDefault();
+            break;
+          case "ArrowUp":
+            stop = true;
+            increment(event);
+            break;
+          case "ArrowDown":
+            stop = true;
+            decrement(event);
+            break;
+          case "Home":
+            stop = true;
+            if (typeof min === "number") {
+              setValue(min);
+            }
+            break;
+          case "End":
+            stop = true;
+            if (typeof max === "number") {
+              setValue(max);
+            }
+            break;
+          case "Enter":
+            stop = true;
+            tryToSubmitRelatedForm(event, form);
+        }
+
+        if (stop) {
+          event.preventDefault();
+          event.stopPropagation();
+          typedCount.current = 0;
+        }
+      },
+      onClick: (event) => {
+        onClick(event);
+
+        event.preventDefault();
+        if (disabled) {
+          return;
+        }
+
+        focused.current = true;
+        typedCount.current = 0;
+        selectNode(event.currentTarget);
+      },
+      onInput: (event) => {
+        onInput(event);
+
+        const node = event.currentTarget;
+        // if the input event is fired while readOnly or disabled, ignore it
+        // and set it back to the previous state
+        if (readOnly || disabled) {
+          node.textContent = prevText.current;
+          selectNode(node);
+          return;
+        }
+
+        const { reason, nextValue } = resolveInputEvent({
+          min,
+          max,
+          text: node.textContent || "",
+          mappings,
+          maxDigits,
+          prevText: prevText.current,
+          prevValue: value,
+          typedCount: typedCount.current,
+        });
+
+        if (
+          reason === "change" ||
+          reason === "cleared" ||
+          reason === "typed-to-completion"
+        ) {
+          typedCount.current = 0;
+        } else if (reason !== "ignored") {
+          typedCount.current++;
+        }
+
+        node.textContent = getTextContent({
+          min,
+          max,
+          minDigits,
+          maxDigits,
+          value: nextValue,
+          fallback,
+          placeholderChar,
+        });
+        prevText.current = node.textContent;
+        selectNode(node);
+
+        if (reason !== "ignored" && reason !== "placeholder-digit") {
+          updateValue({
+            event,
+            value: nextValue,
+            reason,
+          });
+        }
+      },
+    },
+  };
+}

package/src/spinbutton/useSpinButtonGroupProvider.ts

@@ -0,0 +1,104 @@
+"use client";
+
+import {
+  DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
+  DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP,
+} from "../movement/constants.js";
+import {
+  type KeyboardMovementProps,
+  type KeyboardMovementProviderImplementation,
+  type SimpleKeyboardMovementWrapperOptions,
+} from "../movement/types.js";
+import { useKeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
+import { useDir } from "../typography/WritingDirectionProvider.js";
+
+const SPINBUTTON_ROLE = '[role="spinbutton"]';
+
+/**
+ * @internal
+ * @since 6.4.0
+ */
+const getSpinButtonsOnly = (container: HTMLElement): readonly HTMLElement[] => [
+  ...container.querySelectorAll<HTMLElement>(SPINBUTTON_ROLE),
+];
+
+/**
+ * @since 6.4.0
+ */
+export interface SpinButtonGroupProviderOptions<
+  E extends HTMLElement = HTMLElement,
+> extends SimpleKeyboardMovementWrapperOptions<E> {
+  /**
+   * Set this to `true` to update the container's `onClick` handler to move
+   * focus to the first spinbutton that does not have a value or the first
+   * spinbutton in the group so that focus is always moved to the spin buttons.
+   *
+   * @defaultValue `false`
+   */
+  forceFocusWithin?: boolean;
+}
+
+export interface ProvidedSpinButtonGroupProps<
+  E extends HTMLElement = HTMLElement,
+> extends KeyboardMovementProps<E> {
+  role: "group";
+}
+
+/**
+ * @since 6.4.0
+ */
+export interface SpinButtonGroupProviderImplementation<
+  E extends HTMLElement = HTMLElement,
+> extends KeyboardMovementProviderImplementation<E> {
+  movementProps: Readonly<ProvidedSpinButtonGroupProps<E>>;
+}
+
+/**
+ * @since 6.4.0
+ */
+export function useSpinButtonGroupProvider<E extends HTMLElement = HTMLElement>(
+  options: SpinButtonGroupProviderOptions<E> = {}
+): SpinButtonGroupProviderImplementation<E> {
+  const { disabled, forceFocusWithin } = options;
+
+  const isRTL = useDir().dir === "rtl";
+  const movementKeys = isRTL
+    ? DEFAULT_RTL_KEYBOARD_MOVEMENT_WITHOUT_JUMP
+    : DEFAULT_LTR_KEYBOARD_MOVEMENT_WITHOUT_JUMP;
+
+  const { movementProps, ...remaining } = useKeyboardMovementProvider({
+    ...options,
+    ...movementKeys,
+    loopable: false,
+    trackTabKeys: true,
+    getFocusableElements: getSpinButtonsOnly,
+  });
+
+  return {
+    ...remaining,
+    movementProps: {
+      ...movementProps,
+      role: "group",
+      onClick: (event) => {
+        movementProps.onClick(event);
+
+        const { target, currentTarget } = event;
+        if (
+          disabled ||
+          !forceFocusWithin ||
+          !(target instanceof HTMLElement) ||
+          target.closest(SPINBUTTON_ROLE)
+        ) {
+          return;
+        }
+
+        const buttons = [...currentTarget.querySelectorAll(SPINBUTTON_ROLE)];
+        const i = buttons.findIndex((button) => !button.ariaValueNow);
+        remaining.movementContext.updateFocusIndex({
+          index: Math.max(0, i),
+          force: true,
+        });
+      },
+    },
+  };
+}

package/src/spinbutton/utils/deselectNode.ts

@@ -0,0 +1,17 @@
+/**
+ * @since 6.4.0
+ * @internal
+ */
+export function deselectNode(node: Node): void {
+  const selection = window.getSelection();
+  if (!selection) {
+    return;
+  }
+
+  for (let i = 0; i < selection.rangeCount; i++) {
+    const range = selection.getRangeAt(i);
+    if (range.startContainer.contains(node)) {
+      selection.removeRange(range);
+    }
+  }
+}

package/src/spinbutton/utils/resolveInputEvent.ts

@@ -0,0 +1,112 @@
+import { type MinMaxRange } from "../../types.js";
+import { getNumberOfDigits } from "../../utils/getNumberOfDigits.js";
+import {
+  type SpinButtonChangeReason,
+  type SpinButtonCharacterValueMap,
+  type SpinButtonValue,
+} from "../types.js";
+
+/**
+ * @since 6.4.0
+ * @internal
+ */
+interface ResolveInputEventOptions extends Partial<MinMaxRange> {
+  text: string;
+  mappings?: SpinButtonCharacterValueMap;
+  minDigits?: number;
+  maxDigits?: number;
+  prevText: string;
+  prevValue: SpinButtonValue;
+  typedCount: number;
+}
+
+type SpinButtonResolvedInputReason =
+  | SpinButtonChangeReason
+  | "ignored"
+  | "placeholder-digit";
+
+/**
+ * @since 6.4.0
+ * @internal
+ */
+interface ResolveInputEvent {
+  reason: SpinButtonResolvedInputReason;
+  nextValue: SpinButtonValue;
+}
+
+/**
+ * @since 6.4.0
+ * @internal
+ */
+export function resolveInputEvent(
+  options: ResolveInputEventOptions
+): ResolveInputEvent {
+  const {
+    min,
+    max,
+    minDigits = getNumberOfDigits(min),
+    maxDigits = getNumberOfDigits(max),
+    text,
+    mappings,
+    typedCount,
+    prevValue,
+  } = options;
+
+  let { prevText } = options;
+  if (typedCount === 0) {
+    prevText = "";
+  }
+
+  if (!text) {
+    return {
+      reason: "cleared",
+      nextValue: null,
+    };
+  }
+
+  if (mappings) {
+    const nextValue = mappings[text] ?? prevValue;
+
+    let reason: SpinButtonResolvedInputReason = "ignored";
+    if (typeof mappings[text] === "number") {
+      reason = "typed-to-completion";
+    }
+
+    return {
+      reason,
+      nextValue,
+    };
+  }
+
+  if (/[^0-9]/.test(text)) {
+    return {
+      reason: "ignored",
+      nextValue: prevValue,
+    };
+  }
+
+  let reason: SpinButtonResolvedInputReason = "type";
+  let nextValue: SpinButtonValue = parseInt(prevText + text, 10);
+  if (typeof minDigits === "number" && typedCount + 1 < minDigits) {
+    reason = "placeholder-digit";
+  }
+
+  if (typeof max === "number" && nextValue > max) {
+    nextValue = prevValue;
+  }
+
+  if (
+    typeof nextValue === "number" &&
+    // if typing a new value surpasses the number of digits allowed
+    ((typeof maxDigits === "number" && typedCount + 1 >= maxDigits) ||
+      // typing a new value would exceed the max value
+      (typeof max === "number" && nextValue * 10 > max))
+  ) {
+    reason = "typed-to-completion";
+  }
+
+  return {
+    reason,
+    nextValue,
+  };
+}

package/src/spinbutton/utils/selectNode.ts

@@ -0,0 +1,15 @@
+/**
+ * @since 6.4.0
+ * @internal
+ */
+export function selectNode(node: Node): void {
+  const selection = window.getSelection();
+  if (!selection) {
+    return;
+  }
+
+  const range = document.createRange();
+  range.selectNodeContents(node);
+  selection.removeAllRanges();
+  selection.addRange(range);
+}

package/src/table/StickyTableSection.tsx

@@ -14,7 +14,8 @@ import { useTableSectionConfig } from "./useTableSectionConfig.js";
 
 /** @since 6.0.0 */
 export interface StickyTableSectionProps
-  extends HTMLAttributes<HTMLTableSectionElement>,
+  extends
+    HTMLAttributes<HTMLTableSectionElement>,
     TableStickySectionConfiguration,
     TableSectionConfiguration {
   type: "header" | "footer";

package/src/table/Table.tsx

@@ -27,8 +27,7 @@ declare module "react" {
 }
 
 export interface TableProps
-  extends TableHTMLAttributes<HTMLTableElement>,
-    TableConfiguration {}
+  extends TableHTMLAttributes<HTMLTableElement>, TableConfiguration {}
 
 /**
  * **Client Component**

package/src/table/TableBody.tsx

@@ -10,7 +10,8 @@ import {
 import { type TableConfig, type TableConfigContext } from "./types.js";
 
 export interface TableBodyProps
-  extends HTMLAttributes<HTMLTableSectionElement>,
+  extends
+    HTMLAttributes<HTMLTableSectionElement>,
     Omit<TableConfig, "header"> {}
 
 /**

package/src/table/TableCellContent.tsx

@@ -19,8 +19,7 @@ export type TableCellContentsIconRotatorProps = Omit<
  * can be passed to the `ButtonUnstyled`
  * @internal
  */
-export interface TableCellContentProps
-  extends ButtonHTMLAttributes<HTMLButtonElement> {
+export interface TableCellContentProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /**
    * The current sort order for this cell. Setting this to `null` will prevent
    * the button from being rendered.

package/src/table/TableCheckbox.tsx

@@ -48,8 +48,7 @@ export type TableCheckboxSupportedCheckboxProps = Pick<
  * `"Toggle Row Selection"` to `"Select Row"`.
  */
 export interface TableCheckboxProps
-  extends TableCheckboxTdHTMLAttributes,
-    TableCheckboxSupportedCheckboxProps {
+  extends TableCheckboxTdHTMLAttributes, TableCheckboxSupportedCheckboxProps {
   /**
    * @defaultValue `!props["aria-labelledby"] ? "Select Row" : undefined`
    */

package/src/table/TableFooter.tsx

@@ -8,8 +8,7 @@ import { type TableSectionConfiguration } from "./types.js";
 import { useTableSectionConfig } from "./useTableSectionConfig.js";
 
 export interface TableFooterProps
-  extends HTMLAttributes<HTMLTableSectionElement>,
-    TableSectionConfiguration {
+  extends HTMLAttributes<HTMLTableSectionElement>, TableSectionConfiguration {
   /**
    * NOTE: It is recommended to use the `StickyTableSection` component instead
    * of enabling this prop since it supports dynamically adding styles while the

package/src/table/TableHeader.tsx

@@ -8,8 +8,7 @@ import { type TableSectionConfiguration } from "./types.js";
 import { useTableSectionConfig } from "./useTableSectionConfig.js";
 
 export interface TableHeaderProps
-  extends HTMLAttributes<HTMLTableSectionElement>,
-    TableSectionConfiguration {
+  extends HTMLAttributes<HTMLTableSectionElement>, TableSectionConfiguration {
   /**
    * NOTE: It is recommended to use the `StickyTableSection` component instead
    * of enabling this prop since it supports dynamically adding styles while the

package/src/table/TableRadio.tsx

@@ -43,8 +43,7 @@ export type TableRadioSupportedRadioProps = Pick<
  * @since 6.0.0
  */
 export interface TableRadioProps
-  extends TableRadioTdHTMLAttributes,
-    TableRadioSupportedRadioProps {
+  extends TableRadioTdHTMLAttributes, TableRadioSupportedRadioProps {
   /**
    * @defaultValue `!props["aria-labelledby"] ? "Select Row" : undefined`
    */

package/src/table/TableRow.tsx

@@ -7,8 +7,7 @@ import { tableRow } from "./tableRowStyles.js";
 import { type TableRowConfiguration } from "./types.js";
 
 export interface TableRowProps
-  extends HTMLAttributes<HTMLTableRowElement>,
-    TableRowConfiguration {
+  extends HTMLAttributes<HTMLTableRowElement>, TableRowConfiguration {
   /**
    * Boolean if the current row has been selected and should apply the selected
    * background-color.

package/src/table/useStickyTableSection.tsx

@@ -44,8 +44,7 @@ export const isTableFooterStickyActive: IsStickyTableSectionActive = (
 };
 
 /** @since 6.0.0 */
-export interface TableStickySectionOptions
-  extends TableStickySectionConfiguration {
+export interface TableStickySectionOptions extends TableStickySectionConfiguration {
   ref?: Ref<HTMLTableSectionElement>;
   type: "header" | "footer";
 }

package/src/tabs/SimpleTabPanel.tsx

@@ -8,7 +8,8 @@ import { type ProvidedTabPanelProps } from "./useTabs.js";
  * @since 6.0.0
  */
 export interface SimpleTabPanelProps
-  extends Omit<HTMLAttributes<HTMLDivElement>, keyof ProvidedTabPanelProps>,
+  extends
+    Omit<HTMLAttributes<HTMLDivElement>, keyof ProvidedTabPanelProps>,
     ProvidedTabPanelProps {
   children: ReactNode;
 }

package/src/tabs/SimpleTabPanels.tsx

@@ -6,7 +6,8 @@ import { type ProvidedTabPanelsProps } from "./useTabs.js";
  * @since 6.0.0
  */
 export interface SimpleTabPanelsProps
-  extends HTMLAttributes<HTMLDivElement>,
+  extends
+    HTMLAttributes<HTMLDivElement>,
     Omit<ProvidedTabPanelsProps<HTMLDivElement>, "ref"> {
   children: ReactNode;
 }