@base-ui/react 1.3.0 → 1.4.0

package/esm/otp-field/input/OTPFieldInput.js

@@ -0,0 +1,237 @@
+'use client';
+
+import * as React from 'react';
+import { SafeReact } from '@base-ui/utils/safeReact';
+import { warn } from '@base-ui/utils/warn';
+import { stopEvent } from "../../floating-ui-react/utils.js";
+import { IndexGuessBehavior, useCompositeListItem } from "../../composite/list/useCompositeListItem.js";
+import { useRenderElement } from "../../utils/useRenderElement.js";
+import { createChangeEventDetails, createGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+import { useOTPFieldRootContext, getOTPFieldInputState } from "../root/OTPFieldRootContext.js";
+import { inputStateAttributesMapping } from "../utils/stateAttributesMapping.js";
+import { normalizeOTPValue, removeOTPCharacter, replaceOTPValue, stripOTPWhitespace } from "../utils/otp.js";
+
+/**
+ * An individual OTP character input.
+ * Renders an `<input>` element.
+ *
+ * Documentation: [Base UI OTP Field](https://base-ui.com/react/components/otp-field)
+ */
+export const OTPFieldInput = /*#__PURE__*/React.forwardRef(function OTPFieldInput(componentProps, forwardedRef) {
+  const {
+    'aria-label': externalAriaLabel,
+    'aria-labelledby': externalAriaLabelledBy,
+    render,
+    className,
+    style,
+    ...elementProps
+  } = componentProps;
+  const {
+    activeIndex,
+    autoComplete,
+    disabled,
+    form,
+    focusInput,
+    queueFocusInput,
+    getInputId,
+    handleInputBlur,
+    handleInputFocus,
+    inputMode,
+    inputAriaLabelledBy,
+    invalid,
+    length,
+    mask,
+    pattern,
+    reportValueInvalid,
+    readOnly,
+    required,
+    sanitizeValue,
+    setValue,
+    state,
+    validationType,
+    value
+  } = useOTPFieldRootContext();
+  const {
+    ref: listItemRef,
+    index
+  } = useCompositeListItem({
+    indexGuessBehavior: IndexGuessBehavior.GuessFromOrder
+  });
+  const inputRef = React.useRef(null);
+  const slotValue = value[index] ?? '';
+  const inputState = getOTPFieldInputState(state, slotValue, index);
+  const slotAriaLabel = externalAriaLabel;
+  const inheritedLabel = externalAriaLabelledBy ?? inputAriaLabelledBy;
+  const ariaLabel = index === 0 ? undefined : slotAriaLabel;
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    React.useEffect(() => {
+      if (index !== 0 || slotAriaLabel == null || inputRef.current?.labels?.length) {
+        return;
+      }
+      const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+      warn('<OTPField.Input> ignores `aria-label` on the first input. Use a `<label>` or `<Field.Label>` to label the OTP field.', ownerStackMessage);
+    }, [index, slotAriaLabel]);
+  }
+  const inputProps = {
+    id: getInputId(index),
+    value: slotValue,
+    type: mask ? 'password' : 'text',
+    inputMode,
+    autoComplete: index === 0 ? autoComplete : 'off',
+    autoCorrect: 'off',
+    spellCheck: 'false',
+    enterKeyHint: index === length - 1 ? 'done' : 'next',
+    // Allow the first slot to accept a full code so browser paste/autofill can target it directly.
+    maxLength: index === 0 ? length : 1,
+    tabIndex: activeIndex === index ? 0 : -1,
+    disabled,
+    form,
+    pattern,
+    readOnly,
+    required,
+    'aria-labelledby': ariaLabel == null ? inheritedLabel : undefined,
+    'aria-invalid': invalid || undefined,
+    'aria-label': ariaLabel,
+    onMouseDown(event) {
+      if (event.defaultPrevented || disabled) {
+        return;
+      }
+      event.preventDefault();
+      focusInput(index);
+    },
+    onFocus(event) {
+      if (event.defaultPrevented || disabled) {
+        return;
+      }
+      if (index > value.length) {
+        const nextIndex = Math.min(value.length, length - 1);
+        focusInput(nextIndex);
+        return;
+      }
+      handleInputFocus(index, event);
+    },
+    onBlur(event) {
+      if (event.defaultPrevented) {
+        return;
+      }
+      handleInputBlur(event);
+    },
+    onChange(event) {
+      if (event.defaultPrevented || disabled || readOnly) {
+        return;
+      }
+      const rawValue = event.currentTarget.value;
+      const nextDigits = normalizeOTPValue(event.currentTarget.value, length, validationType, sanitizeValue);
+      const didSanitize = stripOTPWhitespace(rawValue).length > nextDigits.length;
+      if (didSanitize) {
+        reportValueInvalid(rawValue, createGenericEventDetails(REASONS.inputChange, event.nativeEvent));
+      }
+      if (nextDigits === '') {
+        if (rawValue === '') {
+          setValue(removeOTPCharacter(value, index), createChangeEventDetails(REASONS.inputClear, event.nativeEvent));
+        } else if (slotValue !== '') {
+          event.currentTarget.value = slotValue;
+          event.currentTarget.select();
+        }
+        return;
+      }
+      const nextValue = replaceOTPValue(value, index, nextDigits, length, validationType, sanitizeValue);
+      const committedValue = setValue(nextValue, createChangeEventDetails(REASONS.inputChange, event.nativeEvent));
+      if (committedValue != null) {
+        const nextInput = Math.min(index + nextDigits.length, length - 1);
+        queueFocusInput(nextInput, committedValue);
+      }
+    },
+    onKeyDown(event) {
+      if (event.defaultPrevented || disabled) {
+        return;
+      }
+      if (event.key === 'ArrowLeft') {
+        stopEvent(event);
+        focusInput(Math.max(0, index - 1));
+        return;
+      }
+      if (event.key === 'ArrowRight') {
+        stopEvent(event);
+        focusInput(Math.min(length - 1, index + 1));
+        return;
+      }
+      if (event.key === 'Home') {
+        stopEvent(event);
+        focusInput(0);
+        return;
+      }
+      if (event.key === 'End') {
+        stopEvent(event);
+        focusInput(Math.max(value.length - 1, 0));
+        return;
+      }
+      if (readOnly) {
+        return;
+      }
+      if (event.key === 'Delete') {
+        stopEvent(event);
+        const committedValue = setValue(removeOTPCharacter(value, index), createChangeEventDetails(REASONS.keyboard, event.nativeEvent));
+        if (committedValue != null) {
+          queueFocusInput(index, committedValue);
+        }
+        return;
+      }
+      const inputValue = event.currentTarget.value;
+      const fullSelection = event.currentTarget.selectionStart === 0 && event.currentTarget.selectionEnd === inputValue.length;
+      if (event.key.length === 1 && fullSelection && slotValue === event.key) {
+        stopEvent(event);
+        focusInput(Math.min(length - 1, index + 1));
+        return;
+      }
+      if (event.key === 'Backspace') {
+        stopEvent(event);
+        const deleteIndex = slotValue === '' ? Math.max(0, index - 1) : index;
+        const targetIndex = Math.max(0, index - 1);
+        const committedValue = setValue(removeOTPCharacter(value, deleteIndex), createChangeEventDetails(REASONS.keyboard, event.nativeEvent));
+        if (committedValue != null) {
+          queueFocusInput(targetIndex, committedValue);
+        }
+      }
+    },
+    onPaste(event) {
+      if (event.defaultPrevented || disabled || readOnly) {
+        return;
+      }
+      let rawValue = '';
+      try {
+        rawValue = event.clipboardData?.getData('text/plain') ?? '';
+      } catch {
+        if (process.env.NODE_ENV !== 'production') {
+          const ownerStackMessage = SafeReact.captureOwnerStack?.() || '';
+          warn('<OTPField.Input> could not read clipboard text during paste handling.', ownerStackMessage);
+        }
+        return;
+      }
+      event.preventDefault();
+      const nextDigits = normalizeOTPValue(rawValue, length, validationType, sanitizeValue);
+      const didSanitize = stripOTPWhitespace(rawValue).length > nextDigits.length;
+      if (didSanitize) {
+        reportValueInvalid(rawValue, createGenericEventDetails(REASONS.inputPaste, event.nativeEvent));
+      }
+      if (nextDigits === '') {
+        return;
+      }
+      const committedValue = setValue(replaceOTPValue(value, index, nextDigits, length, validationType, sanitizeValue), createChangeEventDetails(REASONS.inputPaste, event.nativeEvent));
+      if (committedValue != null) {
+        const nextInput = Math.min(index + nextDigits.length, length - 1);
+        queueFocusInput(nextInput, committedValue);
+      }
+    }
+  };
+  const element = useRenderElement('input', componentProps, {
+    ref: [forwardedRef, listItemRef, inputRef],
+    state: inputState,
+    props: [inputProps, elementProps],
+    stateAttributesMapping: inputStateAttributesMapping
+  });
+  return element;
+});
+if (process.env.NODE_ENV !== "production") OTPFieldInput.displayName = "OTPFieldInput";

package/esm/otp-field/input/OTPFieldInputDataAttributes.d.ts

@@ -0,0 +1,42 @@
+export declare enum OTPFieldInputDataAttributes {
+  /**
+   * Present when all slots are filled.
+   */
+  complete = "data-complete",
+  /**
+   * Present when the input contains a character.
+   */
+  filled = "data-filled",
+  /**
+   * Present when the OTP field is disabled.
+   */
+  disabled = "data-disabled",
+  /**
+   * Present when the OTP field is readonly.
+   */
+  readonly = "data-readonly",
+  /**
+   * Present when the OTP field is required.
+   */
+  required = "data-required",
+  /**
+   * Present when the OTP field is in valid state (when wrapped in Field.Root).
+   */
+  valid = "data-valid",
+  /**
+   * Present when the OTP field is in invalid state (when wrapped in Field.Root).
+   */
+  invalid = "data-invalid",
+  /**
+   * Present when the OTP field has been touched (when wrapped in Field.Root).
+   */
+  touched = "data-touched",
+  /**
+   * Present when the OTP field's value has changed (when wrapped in Field.Root).
+   */
+  dirty = "data-dirty",
+  /**
+   * Present when any OTP field input is focused.
+   */
+  focused = "data-focused",
+}

package/esm/otp-field/input/OTPFieldInputDataAttributes.js

@@ -0,0 +1,43 @@
+export let OTPFieldInputDataAttributes = /*#__PURE__*/function (OTPFieldInputDataAttributes) {
+  /**
+   * Present when all slots are filled.
+   */
+  OTPFieldInputDataAttributes["complete"] = "data-complete";
+  /**
+   * Present when the input contains a character.
+   */
+  OTPFieldInputDataAttributes["filled"] = "data-filled";
+  /**
+   * Present when the OTP field is disabled.
+   */
+  OTPFieldInputDataAttributes["disabled"] = "data-disabled";
+  /**
+   * Present when the OTP field is readonly.
+   */
+  OTPFieldInputDataAttributes["readonly"] = "data-readonly";
+  /**
+   * Present when the OTP field is required.
+   */
+  OTPFieldInputDataAttributes["required"] = "data-required";
+  /**
+   * Present when the OTP field is in valid state (when wrapped in Field.Root).
+   */
+  OTPFieldInputDataAttributes["valid"] = "data-valid";
+  /**
+   * Present when the OTP field is in invalid state (when wrapped in Field.Root).
+   */
+  OTPFieldInputDataAttributes["invalid"] = "data-invalid";
+  /**
+   * Present when the OTP field has been touched (when wrapped in Field.Root).
+   */
+  OTPFieldInputDataAttributes["touched"] = "data-touched";
+  /**
+   * Present when the OTP field's value has changed (when wrapped in Field.Root).
+   */
+  OTPFieldInputDataAttributes["dirty"] = "data-dirty";
+  /**
+   * Present when any OTP field input is focused.
+   */
+  OTPFieldInputDataAttributes["focused"] = "data-focused";
+  return OTPFieldInputDataAttributes;
+}({});

package/esm/otp-field/root/OTPFieldRoot.d.ts

@@ -0,0 +1,159 @@
+import * as React from 'react';
+import type { FieldRootState } from "../../field/root/FieldRoot.js";
+import type { BaseUIComponentProps } from "../../utils/types.js";
+import { type BaseUIChangeEventDetails, type BaseUIGenericEventDetails } from "../../utils/createBaseUIEventDetails.js";
+import { REASONS } from "../../utils/reasons.js";
+import { type OTPValidationType } from "../utils/otp.js";
+/**
+ * Groups all OTP field parts and manages their state.
+ * Renders a `<div>` element.
+ *
+ * Documentation: [Base UI OTP Field](https://base-ui.com/react/components/otp-field)
+ */
+export declare const OTPFieldRoot: React.ForwardRefExoticComponent<Omit<OTPFieldRootProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export interface OTPFieldRootProps extends Omit<BaseUIComponentProps<'div', OTPFieldRootState>, 'onChange'> {
+  /**
+   * The id of the first input element.
+   * Subsequent inputs derive their ids from it (`{id}-2`, `{id}-3`, and so on).
+   */
+  id?: string | undefined;
+  /**
+   * The input autocomplete attribute. Applied to the first slot and hidden validation input.
+   * @default 'one-time-code'
+   */
+  autoComplete?: string | undefined;
+  /**
+   * A string specifying the `form` element with which the hidden input is associated.
+   * This string's value must match the id of a `form` element in the same document.
+   */
+  form?: string | undefined;
+  /**
+   * The number of OTP input slots.
+   * Required so the root can clamp values, detect completion, and generate
+   * consistent validation markup before all slots hydrate.
+   */
+  length: number;
+  /**
+   * Whether to submit the owning form when the OTP becomes complete.
+   * @default false
+   */
+  autoSubmit?: boolean | undefined;
+  /**
+   * Whether the slot inputs should mask entered characters.
+   * Pass `type` directly to individual `<OTPField.Input>` parts to use a custom
+   * input type.
+   * @default false
+   */
+  mask?: boolean | undefined;
+  /**
+   * The virtual keyboard hint applied to the slot inputs and hidden validation input.
+   *
+   * Built-in validation modes provide sensible defaults, but you can override them when needed.
+   */
+  inputMode?: React.HTMLAttributes<HTMLInputElement>['inputMode'] | undefined;
+  /**
+   * The type of input validation to apply to the OTP value.
+   * @default 'numeric'
+   */
+  validationType?: OTPFieldRoot.ValidationType | undefined;
+  /**
+   * Function for custom sanitization when `validationType` is set to `'none'`.
+   * This function runs before updating the OTP value from user interactions.
+   */
+  sanitizeValue?: ((value: string) => string) | 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 OTP value.
+   */
+  value?: string | undefined;
+  /**
+   * The uncontrolled OTP value when the component is initially rendered.
+   */
+  defaultValue?: string | undefined;
+  /**
+   * Callback fired when the OTP value changes.
+   *
+   * The `eventDetails.reason` indicates what triggered the change:
+   * - `'input-change'` for typing or autofill
+   * - `'input-clear'` when a character is removed by text input
+   * - `'input-paste'` for paste interactions
+   * - `'keyboard'` for keyboard interactions that change the value
+   */
+  onValueChange?: ((value: string, eventDetails: OTPFieldRoot.ChangeEventDetails) => void) | undefined;
+  /**
+   * Callback fired when entered text contains characters that are rejected by sanitization,
+   * before the OTP value updates.
+   *
+   * The `value` argument is the attempted user-entered string before sanitization.
+   */
+  onValueInvalid?: ((value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void) | undefined;
+  /**
+   * Callback function that is fired when the OTP value becomes complete.
+   *
+   * It runs later than `onValueChange`, after the internal value update is applied.
+   *
+   * If `autoSubmit` is enabled, it runs immediately before the owning form is submitted.
+   */
+  onValueComplete?: ((value: string, eventDetails: OTPFieldRoot.CompleteEventDetails) => void) | undefined;
+}
+export interface OTPFieldRootState extends FieldRootState {
+  /**
+   * Whether all slots are filled.
+   */
+  complete: boolean;
+  /**
+   * Whether the component should ignore user interaction.
+   */
+  disabled: boolean;
+  /**
+   * The number of OTP input slots.
+   */
+  length: number;
+  /**
+   * Whether the user should be unable to change the field value.
+   */
+  readOnly: boolean;
+  /**
+   * Whether the user must enter a value before submitting a form.
+   */
+  required: boolean;
+  /**
+   * The OTP value.
+   */
+  value: string;
+}
+export type OTPFieldRootChangeEventReason = typeof REASONS.inputChange | typeof REASONS.inputClear | typeof REASONS.inputPaste | typeof REASONS.keyboard;
+export type OTPFieldRootChangeEventDetails = BaseUIChangeEventDetails<OTPFieldRoot.ChangeEventReason>;
+export type OTPFieldRootInvalidEventReason = typeof REASONS.inputChange | typeof REASONS.inputPaste;
+export type OTPFieldRootInvalidEventDetails = BaseUIGenericEventDetails<OTPFieldRoot.InvalidEventReason>;
+export type OTPFieldRootCompleteEventReason = typeof REASONS.inputChange | typeof REASONS.inputPaste;
+export type OTPFieldRootCompleteEventDetails = BaseUIGenericEventDetails<OTPFieldRoot.CompleteEventReason>;
+export declare namespace OTPFieldRoot {
+  type State = OTPFieldRootState;
+  type Props = OTPFieldRootProps;
+  type ValidationType = OTPValidationType;
+  type ChangeEventReason = OTPFieldRootChangeEventReason;
+  type ChangeEventDetails = OTPFieldRootChangeEventDetails;
+  type InvalidEventReason = OTPFieldRootInvalidEventReason;
+  type InvalidEventDetails = OTPFieldRootInvalidEventDetails;
+  type CompleteEventReason = OTPFieldRootCompleteEventReason;
+  type CompleteEventDetails = OTPFieldRootCompleteEventDetails;
+}