@tale-ui/react 0.0.3

package/esm/number-field/input/NumberFieldInput.js

@@ -0,0 +1,327 @@
+'use client';
+
+import * as React from 'react';
+import { stopEvent } from "../../floating-ui-react/utils.js";
+import { useNumberFieldRootContext } from "../root/NumberFieldRootContext.js";
+import { useFieldRootContext } from "../../field/root/FieldRootContext.js";
+import { fieldValidityMapping } from "../../field/utils/constants.js";
+import { useField } from "../../field/useField.js";
+import { useFormContext } from "../../form/FormContext.js";
+import { useLabelableContext } from "../../labelable-provider/LabelableContext.js";
+import { DEFAULT_STEP } from "../utils/constants.js";
+import { ARABIC_DETECT_RE, PERSIAN_DETECT_RE, HAN_DETECT_RE, FULLWIDTH_DETECT_RE, getNumberLocaleDetails, parseNumber, ANY_MINUS_RE, ANY_PLUS_RE, ANY_MINUS_DETECT_RE, ANY_PLUS_DETECT_RE } from "../utils/parse.js";
+import { stateAttributesMapping as numberFieldStateAttributesMapping } from "../utils/stateAttributesMapping.js";
+import { useRenderElement } from "../../utils/useRenderElement.js";
+import { createChangeEventDetails, createGenericEventDetails } from "../../utils/createTaleUIEventDetails.js";
+import { formatNumber, formatNumberMaxPrecision } from "../../utils/formatNumber.js";
+import { useValueChanged } from "../../utils/useValueChanged.js";
+import { REASONS } from "../../utils/reasons.js";
+const stateAttributesMapping = {
+  ...fieldValidityMapping,
+  ...numberFieldStateAttributesMapping
+};
+const NAVIGATE_KEYS = new Set(['Backspace', 'Delete', 'ArrowLeft', 'ArrowRight', 'Tab', 'Enter', 'Escape']);
+
+/**
+ * The native input control in the number field.
+ * Renders an `<input>` element.
+ *
+ * Documentation: [Tale UI Number Field](https://base-ui.com/react/components/number-field)
+ */
+export const NumberFieldInput = /*#__PURE__*/React.forwardRef(function NumberFieldInput(componentProps, forwardedRef) {
+  const {
+    render,
+    className,
+    ...elementProps
+  } = componentProps;
+  const {
+    allowInputSyncRef,
+    disabled,
+    formatOptionsRef,
+    getAllowedNonNumericKeys,
+    getStepAmount,
+    id,
+    incrementValue,
+    inputMode,
+    inputValue,
+    max,
+    min,
+    name,
+    readOnly,
+    required,
+    setValue,
+    state,
+    setInputValue,
+    locale,
+    inputRef,
+    value,
+    onValueCommitted,
+    lastChangedValueRef,
+    hasPendingCommitRef,
+    valueRef
+  } = useNumberFieldRootContext();
+  const {
+    clearErrors
+  } = useFormContext();
+  const {
+    validationMode,
+    setTouched,
+    setFocused,
+    invalid,
+    shouldValidateOnChange,
+    validation
+  } = useFieldRootContext();
+  const {
+    labelId
+  } = useLabelableContext();
+  const hasTouchedInputRef = React.useRef(false);
+  const blockRevalidationRef = React.useRef(false);
+  useField({
+    id,
+    commit: validation.commit,
+    value,
+    controlRef: inputRef,
+    name,
+    getValue: () => value ?? null
+  });
+  useValueChanged(value, previousValue => {
+    const validateOnChange = shouldValidateOnChange();
+    clearErrors(name);
+    if (validateOnChange) {
+      validation.commit(value);
+    }
+    if (previousValue === value || validateOnChange) {
+      return;
+    }
+    if (blockRevalidationRef.current) {
+      blockRevalidationRef.current = false;
+      return;
+    }
+    validation.commit(value, true);
+  });
+  const inputProps = {
+    id,
+    required,
+    disabled,
+    readOnly,
+    inputMode,
+    value: inputValue,
+    type: 'text',
+    autoComplete: 'off',
+    autoCorrect: 'off',
+    spellCheck: 'false',
+    'aria-roledescription': 'Number field',
+    'aria-invalid': invalid || undefined,
+    'aria-labelledby': labelId,
+    // If the server's locale does not match the client's locale, the formatting may not match,
+    // causing a hydration mismatch.
+    suppressHydrationWarning: true,
+    onFocus(event) {
+      if (event.defaultPrevented || readOnly || disabled) {
+        return;
+      }
+      setFocused(true);
+      if (hasTouchedInputRef.current) {
+        return;
+      }
+      hasTouchedInputRef.current = true;
+
+      // Browsers set selection at the start of the input field by default. We want to set it at
+      // the end for the first focus.
+      const target = event.currentTarget;
+      const length = target.value.length;
+      target.setSelectionRange(length, length);
+    },
+    onBlur(event) {
+      if (event.defaultPrevented || readOnly || disabled) {
+        return;
+      }
+      setTouched(true);
+      setFocused(false);
+      const hadManualInput = !allowInputSyncRef.current;
+      const hadPendingProgrammaticChange = hasPendingCommitRef.current;
+      allowInputSyncRef.current = true;
+      if (inputValue.trim() === '') {
+        setValue(null, createChangeEventDetails(REASONS.inputClear, event.nativeEvent));
+        if (validationMode === 'onBlur') {
+          validation.commit(null);
+        }
+        onValueCommitted(null, createGenericEventDetails(REASONS.inputClear, event.nativeEvent));
+        return;
+      }
+      const formatOptions = formatOptionsRef.current;
+      const parsedValue = parseNumber(inputValue, locale, formatOptions);
+      if (parsedValue === null) {
+        return;
+      }
+
+      // If an explicit precision is requested, round the committed numeric value.
+      const hasExplicitPrecision = formatOptions?.maximumFractionDigits != null || formatOptions?.minimumFractionDigits != null;
+      const maxFrac = formatOptions?.maximumFractionDigits;
+      const committed = hasExplicitPrecision && typeof maxFrac === 'number' ? Number(parsedValue.toFixed(maxFrac)) : parsedValue;
+      const nextEventDetails = createGenericEventDetails(REASONS.inputBlur, event.nativeEvent);
+      const shouldUpdateValue = value !== committed;
+      const shouldCommit = hadManualInput || shouldUpdateValue || hadPendingProgrammaticChange;
+      if (validationMode === 'onBlur') {
+        validation.commit(committed);
+      }
+      if (shouldUpdateValue) {
+        blockRevalidationRef.current = true;
+        setValue(committed, createChangeEventDetails(REASONS.inputBlur, event.nativeEvent));
+      }
+      if (shouldCommit) {
+        onValueCommitted(committed, nextEventDetails);
+      }
+
+      // Normalize only the displayed text
+      const canonicalText = formatNumber(committed, locale, formatOptions);
+      const maxPrecisionText = formatNumberMaxPrecision(parsedValue, locale, formatOptions);
+      const shouldPreserveFullPrecision = !hasExplicitPrecision && parsedValue === value && inputValue === maxPrecisionText;
+      if (!shouldPreserveFullPrecision && inputValue !== canonicalText) {
+        setInputValue(canonicalText);
+      }
+    },
+    onChange(event) {
+      // Workaround for https://github.com/facebook/react/issues/9023
+      if (event.nativeEvent.defaultPrevented) {
+        return;
+      }
+      allowInputSyncRef.current = false;
+      const targetValue = event.target.value;
+      if (targetValue.trim() === '') {
+        setInputValue(targetValue);
+        setValue(null, createChangeEventDetails(REASONS.inputClear, event.nativeEvent));
+        return;
+      }
+
+      // Update the input text immediately and only fire onValueChange if the typed value is
+      // currently parseable into a number. This preserves good UX for IME
+      // composition/partial input while still providing live numeric updates when possible.
+      const allowedNonNumericKeys = getAllowedNonNumericKeys();
+      const isValidCharacterString = Array.from(targetValue).every(ch => {
+        const isAsciiDigit = ch >= '0' && ch <= '9';
+        const isArabicNumeral = ARABIC_DETECT_RE.test(ch);
+        const isHanNumeral = HAN_DETECT_RE.test(ch);
+        const isPersianNumeral = PERSIAN_DETECT_RE.test(ch);
+        const isFullwidthNumeral = FULLWIDTH_DETECT_RE.test(ch);
+        const isMinus = ANY_MINUS_DETECT_RE.test(ch);
+        return isAsciiDigit || isArabicNumeral || isHanNumeral || isPersianNumeral || isFullwidthNumeral || isMinus || allowedNonNumericKeys.has(ch);
+      });
+      if (!isValidCharacterString) {
+        return;
+      }
+      const parsedValue = parseNumber(targetValue, locale, formatOptionsRef.current);
+      setInputValue(targetValue);
+      if (parsedValue !== null) {
+        setValue(parsedValue, createChangeEventDetails(REASONS.inputChange, event.nativeEvent));
+      }
+    },
+    onKeyDown(event) {
+      if (event.defaultPrevented || readOnly || disabled) {
+        return;
+      }
+      const nativeEvent = event.nativeEvent;
+      allowInputSyncRef.current = true;
+      const allowedNonNumericKeys = getAllowedNonNumericKeys();
+      let isAllowedNonNumericKey = allowedNonNumericKeys.has(event.key);
+      const {
+        decimal,
+        currency,
+        percentSign
+      } = getNumberLocaleDetails(locale, formatOptionsRef.current);
+      const selectionStart = event.currentTarget.selectionStart;
+      const selectionEnd = event.currentTarget.selectionEnd;
+      const isAllSelected = selectionStart === 0 && selectionEnd === inputValue.length;
+
+      // Normalize handling of plus/minus signs via precomputed regexes
+      const selectionContainsIndex = index => selectionStart != null && selectionEnd != null && index >= selectionStart && index < selectionEnd;
+      if (ANY_MINUS_DETECT_RE.test(event.key) && Array.from(allowedNonNumericKeys).some(k => ANY_MINUS_DETECT_RE.test(k || ''))) {
+        // Only allow one sign unless replacing the existing one or all text is selected
+        const existingIndex = inputValue.search(ANY_MINUS_RE);
+        const isReplacingExisting = existingIndex != null && existingIndex !== -1 && selectionContainsIndex(existingIndex);
+        isAllowedNonNumericKey = !(ANY_MINUS_DETECT_RE.test(inputValue) || ANY_PLUS_DETECT_RE.test(inputValue)) || isAllSelected || isReplacingExisting;
+      }
+      if (ANY_PLUS_DETECT_RE.test(event.key) && Array.from(allowedNonNumericKeys).some(k => ANY_PLUS_DETECT_RE.test(k || ''))) {
+        const existingIndex = inputValue.search(ANY_PLUS_RE);
+        const isReplacingExisting = existingIndex != null && existingIndex !== -1 && selectionContainsIndex(existingIndex);
+        isAllowedNonNumericKey = !(ANY_MINUS_DETECT_RE.test(inputValue) || ANY_PLUS_DETECT_RE.test(inputValue)) || isAllSelected || isReplacingExisting;
+      }
+
+      // Only allow one of each symbol.
+      [decimal, currency, percentSign].forEach(symbol => {
+        if (event.key === symbol) {
+          const symbolIndex = inputValue.indexOf(symbol);
+          const isSymbolHighlighted = selectionContainsIndex(symbolIndex);
+          isAllowedNonNumericKey = !inputValue.includes(symbol) || isAllSelected || isSymbolHighlighted;
+        }
+      });
+      const isAsciiDigit = event.key >= '0' && event.key <= '9';
+      const isArabicNumeral = ARABIC_DETECT_RE.test(event.key);
+      const isHanNumeral = HAN_DETECT_RE.test(event.key);
+      const isFullwidthNumeral = FULLWIDTH_DETECT_RE.test(event.key);
+      const isNavigateKey = NAVIGATE_KEYS.has(event.key);
+      if (
+      // Allow composition events (e.g., pinyin)
+      // event.nativeEvent.isComposing does not work in Safari:
+      // https://bugs.webkit.org/show_bug.cgi?id=165004
+      event.which === 229 || event.altKey || event.ctrlKey || event.metaKey || isAllowedNonNumericKey || isAsciiDigit || isArabicNumeral || isFullwidthNumeral || isHanNumeral || isNavigateKey) {
+        return;
+      }
+
+      // We need to commit the number at this point if the input hasn't been blurred.
+      const parsedValue = parseNumber(inputValue, locale, formatOptionsRef.current);
+      const amount = getStepAmount(event) ?? DEFAULT_STEP;
+
+      // Prevent insertion of text or caret from moving.
+      stopEvent(event);
+      const commitDetails = createGenericEventDetails(REASONS.keyboard, nativeEvent);
+      if (event.key === 'ArrowUp') {
+        incrementValue(amount, {
+          direction: 1,
+          currentValue: parsedValue,
+          event: nativeEvent,
+          reason: REASONS.keyboard
+        });
+        onValueCommitted(lastChangedValueRef.current ?? valueRef.current, commitDetails);
+      } else if (event.key === 'ArrowDown') {
+        incrementValue(amount, {
+          direction: -1,
+          currentValue: parsedValue,
+          event: nativeEvent,
+          reason: REASONS.keyboard
+        });
+        onValueCommitted(lastChangedValueRef.current ?? valueRef.current, commitDetails);
+      } else if (event.key === 'Home' && min != null) {
+        setValue(min, createChangeEventDetails(REASONS.keyboard, nativeEvent));
+        onValueCommitted(lastChangedValueRef.current ?? valueRef.current, commitDetails);
+      } else if (event.key === 'End' && max != null) {
+        setValue(max, createChangeEventDetails(REASONS.keyboard, nativeEvent));
+        onValueCommitted(lastChangedValueRef.current ?? valueRef.current, commitDetails);
+      }
+    },
+    onPaste(event) {
+      if (event.defaultPrevented || readOnly || disabled) {
+        return;
+      }
+
+      // Prevent `onChange` from being called.
+      event.preventDefault();
+      const clipboardData = event.clipboardData || window.Clipboard;
+      const pastedData = clipboardData.getData('text/plain');
+      const parsedValue = parseNumber(pastedData, locale, formatOptionsRef.current);
+      if (parsedValue !== null) {
+        allowInputSyncRef.current = false;
+        setValue(parsedValue, createChangeEventDetails(REASONS.inputPaste, event.nativeEvent));
+        setInputValue(pastedData);
+      }
+    }
+  };
+  const element = useRenderElement('input', componentProps, {
+    ref: [forwardedRef, inputRef],
+    state,
+    props: [inputProps, validation.getValidationProps(), elementProps],
+    stateAttributesMapping
+  });
+  return element;
+});
+if (process.env.NODE_ENV !== "production") NumberFieldInput.displayName = "NumberFieldInput";

package/esm/number-field/input/NumberFieldInputDataAttributes.d.ts

@@ -0,0 +1,42 @@
+export declare enum NumberFieldInputDataAttributes {
+  /**
+   * Present while scrubbing.
+   */
+  scrubbing = "data-scrubbing",
+  /**
+   * Present when the number field is disabled.
+   */
+  disabled = "data-disabled",
+  /**
+   * Present when the number field is readonly.
+   */
+  readonly = "data-readonly",
+  /**
+   * Present when the number field is required.
+   */
+  required = "data-required",
+  /**
+   * Present when the number field is in valid state (when wrapped in Field.Root).
+   */
+  valid = "data-valid",
+  /**
+   * Present when the number field is in invalid state (when wrapped in Field.Root).
+   */
+  invalid = "data-invalid",
+  /**
+   * Present when the number field has been touched (when wrapped in Field.Root).
+   */
+  touched = "data-touched",
+  /**
+   * Present when the number field's value has changed (when wrapped in Field.Root).
+   */
+  dirty = "data-dirty",
+  /**
+   * Present when the number field is filled (when wrapped in Field.Root).
+   */
+  filled = "data-filled",
+  /**
+   * Present when the number field is focused (when wrapped in Field.Root).
+   */
+  focused = "data-focused",
+}

package/esm/number-field/input/NumberFieldInputDataAttributes.js

@@ -0,0 +1,43 @@
+export let NumberFieldInputDataAttributes = /*#__PURE__*/function (NumberFieldInputDataAttributes) {
+  /**
+   * Present while scrubbing.
+   */
+  NumberFieldInputDataAttributes["scrubbing"] = "data-scrubbing";
+  /**
+   * Present when the number field is disabled.
+   */
+  NumberFieldInputDataAttributes["disabled"] = "data-disabled";
+  /**
+   * Present when the number field is readonly.
+   */
+  NumberFieldInputDataAttributes["readonly"] = "data-readonly";
+  /**
+   * Present when the number field is required.
+   */
+  NumberFieldInputDataAttributes["required"] = "data-required";
+  /**
+   * Present when the number field is in valid state (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["valid"] = "data-valid";
+  /**
+   * Present when the number field is in invalid state (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["invalid"] = "data-invalid";
+  /**
+   * Present when the number field has been touched (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["touched"] = "data-touched";
+  /**
+   * Present when the number field's value has changed (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["dirty"] = "data-dirty";
+  /**
+   * Present when the number field is filled (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["filled"] = "data-filled";
+  /**
+   * Present when the number field is focused (when wrapped in Field.Root).
+   */
+  NumberFieldInputDataAttributes["focused"] = "data-focused";
+  return NumberFieldInputDataAttributes;
+}({});

package/esm/number-field/root/NumberFieldRoot.d.ts

@@ -0,0 +1,169 @@
+import * as React from 'react';
+import type { FieldRoot } from "../../field/root/FieldRoot.js";
+import type { TaleUIComponentProps } from "../../utils/types.js";
+import type { ChangeEventCustomProperties } from "../utils/types.js";
+import { type TaleUIChangeEventDetails, type TaleUIGenericEventDetails } from "../../utils/createTaleUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+/**
+ * Groups all parts of the number field and manages its state.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Tale UI Number Field](https://base-ui.com/react/components/number-field)
+ */
+export declare const NumberFieldRoot: React.ForwardRefExoticComponent<Omit<NumberFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface NumberFieldRootProps extends Omit<TaleUIComponentProps<'div', NumberFieldRootState>, 'onChange'> {
+  /**
+   * The id of the input element.
+   */
+  id?: string | undefined;
+  /**
+   * The minimum value of the input element.
+   */
+  min?: number | undefined;
+  /**
+   * The maximum value of the input element.
+   */
+  max?: number | undefined;
+  /**
+   * When true, direct text entry may be outside the `min`/`max` range without clamping,
+   * so native range underflow/overflow validation can occur.
+   * Step-based interactions (keyboard arrows, buttons, wheel, scrub) still clamp.
+   * @default false
+   */
+  allowOutOfRange?: boolean | undefined;
+  /**
+   * The small step value of the input element when incrementing while the meta key is held. Snaps
+   * to multiples of this value.
+   * @default 0.1
+   */
+  smallStep?: number | undefined;
+  /**
+   * Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area.
+   * To always enable step validation on form submission, specify the `min` prop explicitly in conjunction with this prop.
+   * Specify `step="any"` to always disable step validation.
+   * @default 1
+   */
+  step?: number | 'any' | undefined;
+  /**
+   * The large step value of the input element when incrementing while the shift key is held. Snaps
+   * to multiples of this value.
+   * @default 10
+   */
+  largeStep?: number | undefined;
+  /**
+   * Whether the user must enter a value before submitting a form.
+   * @default false
+   */
+  required?: boolean | undefined;
+  /**
+   * Whether the component should ignore user interaction.
+   * @default false
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Whether the user should be unable to change the field value.
+   * @default false
+   */
+  readOnly?: boolean | undefined;
+  /**
+   * Identifies the field when a form is submitted.
+   */
+  name?: string | undefined;
+  /**
+   * The raw numeric value of the field.
+   */
+  value?: number | null | undefined;
+  /**
+   * The uncontrolled value of the field when it’s initially rendered.
+   *
+   * To render a controlled number field, use the `value` prop instead.
+   */
+  defaultValue?: number | undefined;
+  /**
+   * Whether to allow the user to scrub the input value with the mouse wheel while focused and
+   * hovering over the input.
+   * @default false
+   */
+  allowWheelScrub?: boolean | undefined;
+  /**
+   * Whether the value should snap to the nearest step when incrementing or decrementing.
+   * @default false
+   */
+  snapOnStep?: boolean | undefined;
+  /**
+   * Options to format the input value.
+   */
+  format?: Intl.NumberFormatOptions | undefined;
+  /**
+   * Callback fired when the number value changes.
+   *
+   * The `eventDetails.reason` indicates what triggered the change:
+   * - `'input-change'` for parseable typing or programmatic text updates
+   * - `'input-clear'` when the field becomes empty
+   * - `'input-blur'` when formatting (and clamping, if enabled) occurs on blur
+   * - `'input-paste'` for paste interactions
+   * - `'keyboard'` for keyboard input
+   * - `'increment-press'` / `'decrement-press'` for button presses on the increment and decrement controls
+   * - `'wheel'` for wheel-based scrubbing
+   * - `'scrub'` for scrub area drags
+   */
+  onValueChange?: ((value: number | null, eventDetails: NumberFieldRoot.ChangeEventDetails) => void) | undefined;
+  /**
+   * Callback function that is fired when the value is committed.
+   * It runs later than `onValueChange`, when:
+   * - The input is blurred after typing a value.
+   * - The pointer is released after scrubbing or pressing the increment/decrement buttons.
+   *
+   * It runs simultaneously with `onValueChange` when interacting with the keyboard.
+   *
+   * **Warning**: This is a generic event not a change event.
+   */
+  onValueCommitted?: ((value: number | null, eventDetails: NumberFieldRoot.CommitEventDetails) => void) | undefined;
+  /**
+   * The locale of the input element.
+   * Defaults to the user's runtime locale.
+   */
+  locale?: Intl.LocalesArgument | undefined;
+  /**
+   * A ref to access the hidden input element.
+   */
+  inputRef?: React.Ref<HTMLInputElement> | undefined;
+}
+export interface NumberFieldRootState extends FieldRoot.State {
+  /**
+   * The raw numeric value of the field.
+   */
+  value: number | null;
+  /**
+   * The formatted string value presented in the input element.
+   */
+  inputValue: string;
+  /**
+   * Whether the user must enter a value before submitting a form.
+   */
+  required: boolean;
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * Whether the user should be unable to change the field value.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the user is currently scrubbing the field.
+   */
+  scrubbing: boolean;
+}
+export type NumberFieldRootChangeEventReason = typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.inputBlur | typeof REASONS.inputPaste | typeof REASONS.keyboard | typeof REASONS.incrementPress | typeof REASONS.decrementPress | typeof REASONS.wheel | typeof REASONS.scrub | typeof REASONS.none;
+export type NumberFieldRootChangeEventDetails = TaleUIChangeEventDetails<NumberFieldRootChangeEventReason, ChangeEventCustomProperties>;
+export type NumberFieldRootCommitEventReason = typeof REASONS.inputBlur | typeof REASONS.inputClear | typeof REASONS.keyboard | typeof REASONS.incrementPress | typeof REASONS.decrementPress | typeof REASONS.wheel | typeof REASONS.scrub | typeof REASONS.none;
+export type NumberFieldRootCommitEventDetails = TaleUIGenericEventDetails<NumberFieldRoot.CommitEventReason>;
+export declare namespace NumberFieldRoot {
+  type State = NumberFieldRootState;
+  type Props = NumberFieldRootProps;
+  type ChangeEventReason = NumberFieldRootChangeEventReason;
+  type ChangeEventDetails = NumberFieldRootChangeEventDetails;
+  type CommitEventReason = NumberFieldRootCommitEventReason;
+  type CommitEventDetails = NumberFieldRootCommitEventDetails;
+}