@base-ui/react 1.3.0 → 1.4.0

package/otp-field/root/OTPFieldRoot.js

@@ -0,0 +1,413 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OTPFieldRoot = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _safeReact = require("@base-ui/utils/safeReact");
+var _useControlled = require("@base-ui/utils/useControlled");
+var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
+var _useStableCallback = require("@base-ui/utils/useStableCallback");
+var _useValueAsRef = require("@base-ui/utils/useValueAsRef");
+var _visuallyHidden = require("@base-ui/utils/visuallyHidden");
+var _warn = require("@base-ui/utils/warn");
+var _owner = require("@base-ui/utils/owner");
+var _shadowDom = require("../../floating-ui-react/utils/shadowDom");
+var _CompositeList = require("../../composite/list/CompositeList");
+var _FieldRootContext = require("../../field/root/FieldRootContext");
+var _useRegisterFieldControl = require("../../field/root/useRegisterFieldControl");
+var _FormContext = require("../../form/FormContext");
+var _LabelableContext = require("../../labelable-provider/LabelableContext");
+var _useAriaLabelledBy = require("../../labelable-provider/useAriaLabelledBy");
+var _useLabelableId = require("../../labelable-provider/useLabelableId");
+var _useRenderElement = require("../../utils/useRenderElement");
+var _useValueChanged = require("../../utils/useValueChanged");
+var _createBaseUIEventDetails = require("../../utils/createBaseUIEventDetails");
+var _reasons = require("../../utils/reasons");
+var _OTPFieldRootContext = require("./OTPFieldRootContext");
+var _stateAttributesMapping = require("../utils/stateAttributesMapping");
+var _otp = require("../utils/otp");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * 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)
+ */
+const OTPFieldRoot = exports.OTPFieldRoot = /*#__PURE__*/React.forwardRef(function OTPFieldRoot(componentProps, forwardedRef) {
+  const {
+    'aria-describedby': ariaDescribedByProp,
+    'aria-labelledby': ariaLabelledByProp,
+    id: idProp,
+    autoComplete = 'one-time-code',
+    defaultValue,
+    value: valueProp,
+    onValueChange,
+    onValueComplete: onValueCompleteProp,
+    form,
+    length,
+    autoSubmit = false,
+    mask = false,
+    inputMode: inputModeProp,
+    validationType = 'numeric',
+    sanitizeValue,
+    disabled: disabledProp = false,
+    readOnly = false,
+    required = false,
+    name: nameProp,
+    onValueInvalid,
+    render,
+    className,
+    style,
+    ...elementProps
+  } = componentProps;
+  const {
+    setDirty,
+    validityData,
+    disabled: fieldDisabled,
+    setFilled,
+    invalid,
+    name: fieldName,
+    state: fieldState,
+    validation,
+    validationMode,
+    shouldValidateOnChange,
+    setFocused,
+    setTouched
+  } = (0, _FieldRootContext.useFieldRootContext)();
+  const {
+    clearErrors
+  } = (0, _FormContext.useFormContext)();
+  const {
+    getDescriptionProps,
+    labelId
+  } = (0, _LabelableContext.useLabelableContext)();
+  const disabled = fieldDisabled || disabledProp;
+  const name = fieldName ?? nameProp;
+  const [valueUnwrapped, setValueUnwrapped] = (0, _useControlled.useControlled)({
+    controlled: valueProp,
+    default: defaultValue,
+    name: 'OTPField',
+    state: 'value'
+  });
+  const rootRef = React.useRef(null);
+  const inputRefs = React.useRef([]);
+  const pendingFocusRef = React.useRef(null);
+  const pendingCompleteValueRef = React.useRef(null);
+  const firstInputRef = React.useMemo(() => ({
+    get current() {
+      return inputRefs.current[0] ?? null;
+    }
+  }), []);
+  const id = (0, _useLabelableId.useLabelableId)({
+    id: idProp
+  });
+  const ariaLabelledBy = (0, _useAriaLabelledBy.useAriaLabelledBy)(ariaLabelledByProp, labelId, firstInputRef, true, id);
+  const inputAriaLabelledBy = ariaLabelledByProp == null ? ariaLabelledBy : undefined;
+  const fieldDescriptionProps = getDescriptionProps({});
+  const ariaDescribedBy = mergeAriaIds(fieldDescriptionProps['aria-describedby'], ariaDescribedByProp);
+  const validationConfig = (0, _otp.getOTPValidationConfig)(validationType);
+  const pattern = validationConfig?.slotPattern;
+  const hiddenInputPattern = validationConfig?.getRootPattern(length);
+  const inputMode = inputModeProp ?? validationConfig?.inputMode;
+  const value = (0, _otp.normalizeOTPValue)(valueUnwrapped, length, validationType, sanitizeValue);
+  const valueRef = (0, _useValueAsRef.useValueAsRef)(value);
+  const filled = value !== '';
+  const [inputCount, setInputCount] = React.useState(0);
+  const [focusedIndex, setFocusedIndex] = React.useState(() => Math.min(value.length, length - 1));
+  const [focused, setFocusedState] = React.useState(false);
+  const activeIndex = focused ? Math.min(focusedIndex, Math.max(length - 1, 0)) : Math.min(value.length, length - 1);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    setFilled(filled);
+  }, [filled, setFilled]);
+  if (process.env.NODE_ENV !== 'production') {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useOTPFieldRootDevWarnings({
+      inputCount,
+      length,
+      sanitizeValue,
+      validationType
+    });
+  }
+  (0, _useRegisterFieldControl.useRegisterFieldControl)(firstInputRef, {
+    id,
+    getValue: () => valueRef.current,
+    value
+  });
+  const focusInput = (0, _useStableCallback.useStableCallback)(index => {
+    const targetIndex = Math.min(Math.max(index, 0), Math.max(inputRefs.current.length - 1, 0));
+    const target = inputRefs.current[targetIndex];
+    target?.focus();
+    target?.select();
+  });
+  const queueFocusInput = (0, _useStableCallback.useStableCallback)((index, nextValue) => {
+    pendingFocusRef.current = {
+      index,
+      value: nextValue
+    };
+  });
+  function requestSubmit() {
+    let formElement = validation.inputRef.current?.form ?? inputRefs.current[0]?.form ?? null;
+    if (form) {
+      const associatedElement = (0, _owner.ownerDocument)(rootRef.current).getElementById(form);
+      if (associatedElement?.tagName === 'FORM') {
+        formElement = associatedElement;
+      }
+    }
+    if (formElement && typeof formElement.requestSubmit === 'function') {
+      formElement.requestSubmit();
+    }
+  }
+  (0, _useValueChanged.useValueChanged)(value, () => {
+    clearErrors(name);
+    setDirty(value !== validityData.initialValue);
+    if (shouldValidateOnChange()) {
+      validation.commit(value);
+    } else {
+      validation.commit(value, true);
+    }
+    const pendingCompleteValue = pendingCompleteValueRef.current;
+    if (pendingCompleteValue != null) {
+      pendingCompleteValueRef.current = null;
+      if (pendingCompleteValue.value === value) {
+        onValueCompleteProp?.(value, pendingCompleteValue.eventDetails);
+        if (autoSubmit) {
+          requestSubmit();
+        }
+      }
+    }
+    const pendingFocus = pendingFocusRef.current;
+    if (pendingFocus != null) {
+      pendingFocusRef.current = null;
+      if (pendingFocus.value === value) {
+        focusInput(pendingFocus.index);
+      }
+    }
+  });
+  const setValue = (0, _useStableCallback.useStableCallback)((nextValue, details) => {
+    const normalizedValue = (0, _otp.normalizeOTPValue)(nextValue, length, validationType, sanitizeValue);
+    if (normalizedValue === valueRef.current) {
+      return null;
+    }
+    onValueChange?.(normalizedValue, details);
+    if (details.isCanceled) {
+      return null;
+    }
+    setValueUnwrapped(normalizedValue);
+    if (normalizedValue.length === length && valueRef.current.length !== length) {
+      pendingCompleteValueRef.current = {
+        value: normalizedValue,
+        eventDetails: (0, _createBaseUIEventDetails.createGenericEventDetails)(details.reason, details.event)
+      };
+    } else if (normalizedValue.length !== length) {
+      pendingCompleteValueRef.current = null;
+    }
+    return normalizedValue;
+  });
+  const reportValueInvalid = (0, _useStableCallback.useStableCallback)((invalidValue, details) => {
+    onValueInvalid?.(invalidValue, details);
+  });
+  const handleInputFocus = (0, _useStableCallback.useStableCallback)((index, event) => {
+    if (index > valueRef.current.length) {
+      focusInput(Math.min(valueRef.current.length, length - 1));
+      return;
+    }
+    setFocusedIndex(index);
+    setFocusedState(true);
+    setFocused(true);
+    event.currentTarget.select();
+  });
+  const handleInputBlur = (0, _useStableCallback.useStableCallback)(event => {
+    if ((0, _shadowDom.contains)(rootRef.current, event.relatedTarget)) {
+      return;
+    }
+    setTouched(true);
+    setFocusedState(false);
+    setFocused(false);
+    if (validationMode === 'onBlur') {
+      validation.commit(valueRef.current);
+    }
+  });
+  const getInputId = React.useCallback(index => {
+    if (id == null) {
+      return undefined;
+    }
+    return index === 0 ? id : `${id}-${index + 1}`;
+  }, [id]);
+  const state = React.useMemo(() => ({
+    ...fieldState,
+    complete: value.length === length,
+    disabled,
+    filled,
+    focused,
+    length,
+    readOnly,
+    required,
+    value
+  }), [disabled, fieldState, filled, focused, length, readOnly, required, value]);
+  const contextValue = React.useMemo(() => ({
+    autoComplete,
+    activeIndex,
+    disabled,
+    form,
+    focusInput,
+    queueFocusInput,
+    getInputId,
+    handleInputBlur,
+    handleInputFocus,
+    inputMode,
+    inputAriaLabelledBy,
+    invalid,
+    length,
+    mask,
+    pattern,
+    reportValueInvalid,
+    readOnly,
+    required,
+    sanitizeValue,
+    setValue,
+    state,
+    validationType,
+    value
+  }), [activeIndex, autoComplete, disabled, focusInput, form, getInputId, handleInputBlur, handleInputFocus, inputMode, inputAriaLabelledBy, invalid, length, mask, pattern, queueFocusInput, readOnly, reportValueInvalid, required, sanitizeValue, setValue, state, validationType, value]);
+  const element = (0, _useRenderElement.useRenderElement)('div', componentProps, {
+    ref: [forwardedRef, rootRef],
+    state,
+    props: [{
+      role: 'group',
+      'aria-describedby': ariaDescribedBy,
+      'aria-labelledby': ariaLabelledBy
+    }, elementProps],
+    stateAttributesMapping: _stateAttributesMapping.rootStateAttributesMapping
+  });
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_CompositeList.CompositeList, {
+    elementsRef: inputRefs,
+    onMapChange: newMap => {
+      setInputCount(newMap.size);
+    },
+    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_OTPFieldRootContext.OTPFieldRootContext.Provider, {
+      value: contextValue,
+      children: [element, /*#__PURE__*/(0, _jsxRuntime.jsx)(OTPFieldHiddenInput, {
+        autoComplete: autoComplete,
+        disabled: disabled,
+        focusInput: focusInput,
+        form: form,
+        id: id,
+        inputMode: inputMode,
+        length: length,
+        name: name,
+        onValueInvalid: reportValueInvalid,
+        pattern: hiddenInputPattern,
+        queueFocusInput: queueFocusInput,
+        readOnly: readOnly,
+        sanitizeValue: sanitizeValue,
+        required: required,
+        setValue: setValue,
+        validationType: validationType,
+        validation: validation,
+        value: value
+      })]
+    })
+  });
+});
+if (process.env.NODE_ENV !== "production") OTPFieldRoot.displayName = "OTPFieldRoot";
+function OTPFieldHiddenInput(props) {
+  const {
+    autoComplete,
+    disabled,
+    focusInput,
+    form,
+    id,
+    inputMode,
+    length,
+    name,
+    onValueInvalid,
+    pattern,
+    queueFocusInput,
+    readOnly,
+    sanitizeValue,
+    required,
+    setValue,
+    validationType,
+    validation,
+    value
+  } = props;
+  if (!Number.isInteger(length) || length <= 0) {
+    return null;
+  }
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)("input", {
+    ...validation.getInputValidationProps({
+      onFocus() {
+        focusInput(0);
+      },
+      onChange(event) {
+        if (event.nativeEvent.defaultPrevented) {
+          return;
+        }
+        const rawValue = event.currentTarget.value;
+        const normalizedValue = (0, _otp.normalizeOTPValue)(rawValue, length, validationType, sanitizeValue);
+        if ((0, _otp.stripOTPWhitespace)(rawValue).length > normalizedValue.length) {
+          onValueInvalid(rawValue, (0, _createBaseUIEventDetails.createGenericEventDetails)(_reasons.REASONS.inputChange, event.nativeEvent));
+        }
+        const committedValue = setValue(normalizedValue, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.inputChange, event.nativeEvent));
+        if (committedValue != null && committedValue !== '') {
+          queueFocusInput(committedValue.length - 1, committedValue);
+        }
+      }
+    }),
+    ref: validation.inputRef,
+    type: "text",
+    id: id && name == null ? `${id}-hidden-input` : undefined,
+    form: form,
+    name: name,
+    value: value,
+    autoComplete: autoComplete,
+    inputMode: inputMode,
+    minLength: length,
+    maxLength: length,
+    pattern: pattern,
+    disabled: disabled,
+    readOnly: readOnly,
+    required: required,
+    "aria-hidden": true,
+    tabIndex: -1,
+    style: name ? _visuallyHidden.visuallyHiddenInput : _visuallyHidden.visuallyHidden
+  });
+}
+function mergeAriaIds(...values) {
+  const ids = values.flatMap(value => value?.split(/\s+/).filter(Boolean) ?? []);
+  return ids.length > 0 ? Array.from(new Set(ids)).join(' ') : undefined;
+}
+function useOTPFieldRootDevWarnings(parameters) {
+  const {
+    inputCount,
+    length,
+    sanitizeValue,
+    validationType
+  } = parameters;
+  React.useEffect(() => {
+    if (!Number.isInteger(length) || length <= 0 || inputCount === 0 || inputCount === length) {
+      return;
+    }
+    const ownerStackMessage = _safeReact.SafeReact.captureOwnerStack?.() || '';
+    const message = '<OTPField.Root> `length` must match the number of rendered ' + `<OTPField.Input /> parts. Received \`length={${length}}\` but rendered ` + `${inputCount} input${inputCount === 1 ? '' : 's'}.`;
+    (0, _warn.warn)(message, ownerStackMessage);
+  }, [inputCount, length]);
+  React.useEffect(() => {
+    if (Number.isInteger(length) && length > 0) {
+      return;
+    }
+    const ownerStackMessage = _safeReact.SafeReact.captureOwnerStack?.() || '';
+    (0, _warn.warn)(`<OTPField.Root> \`length\` must be a positive integer. Received \`length={${String(length)}}\`.`, ownerStackMessage);
+  }, [length]);
+  React.useEffect(() => {
+    if (sanitizeValue == null || validationType === 'none') {
+      return;
+    }
+    const ownerStackMessage = _safeReact.SafeReact.captureOwnerStack?.() || '';
+    (0, _warn.warn)('<OTPField.Root> `sanitizeValue` is only used when `validationType="none"`.', ownerStackMessage);
+  }, [sanitizeValue, validationType]);
+}

package/otp-field/root/OTPFieldRootContext.d.ts

@@ -0,0 +1,31 @@
+import * as React from 'react';
+import type { OTPFieldRoot, OTPFieldRootState } from "./OTPFieldRoot.js";
+import type { OTPFieldInputState } from "../input/OTPFieldInput.js";
+export interface OTPFieldRootContext {
+  activeIndex: number;
+  autoComplete: string | undefined;
+  disabled: boolean;
+  form: string | undefined;
+  focusInput: (index: number) => void;
+  queueFocusInput: (index: number, value: string) => void;
+  getInputId: (index: number) => string | undefined;
+  handleInputBlur: (event: React.FocusEvent<HTMLInputElement>) => void;
+  handleInputFocus: (index: number, event: React.FocusEvent<HTMLInputElement>) => void;
+  inputMode: React.HTMLAttributes<HTMLInputElement>['inputMode'];
+  inputAriaLabelledBy: string | undefined;
+  invalid: boolean | undefined;
+  length: number;
+  mask: boolean;
+  pattern: string | undefined;
+  reportValueInvalid: (value: string, details: OTPFieldRoot.InvalidEventDetails) => void;
+  readOnly: boolean;
+  required: boolean;
+  sanitizeValue: ((value: string) => string) | undefined;
+  setValue: (value: string, details: OTPFieldRoot.ChangeEventDetails) => string | null;
+  state: OTPFieldRootState;
+  validationType: OTPFieldRoot.ValidationType;
+  value: string;
+}
+export declare const OTPFieldRootContext: React.Context<OTPFieldRootContext | undefined>;
+export declare function useOTPFieldRootContext(): OTPFieldRootContext;
+export declare function getOTPFieldInputState(state: OTPFieldRootState, value: string, index: number): OTPFieldInputState;

package/otp-field/root/OTPFieldRootContext.js

@@ -0,0 +1,30 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OTPFieldRootContext = void 0;
+exports.getOTPFieldInputState = getOTPFieldInputState;
+exports.useOTPFieldRootContext = useOTPFieldRootContext;
+var _formatErrorMessage2 = _interopRequireDefault(require("@base-ui/utils/formatErrorMessage"));
+var React = _interopRequireWildcard(require("react"));
+const OTPFieldRootContext = exports.OTPFieldRootContext = /*#__PURE__*/React.createContext(undefined);
+if (process.env.NODE_ENV !== "production") OTPFieldRootContext.displayName = "OTPFieldRootContext";
+function useOTPFieldRootContext() {
+  const context = React.useContext(OTPFieldRootContext);
+  if (context === undefined) {
+    throw new Error(process.env.NODE_ENV !== "production" ? 'Base UI: OTPFieldRootContext is missing. OTPField parts must be placed within <OTPField.Root>.' : (0, _formatErrorMessage2.default)(98));
+  }
+  return context;
+}
+function getOTPFieldInputState(state, value, index) {
+  return {
+    ...state,
+    value,
+    index,
+    filled: value !== ''
+  };
+}

package/otp-field/root/OTPFieldRootDataAttributes.d.ts

@@ -0,0 +1,42 @@
+export declare enum OTPFieldRootDataAttributes {
+  /**
+   * Present when all slots are filled.
+   */
+  complete = "data-complete",
+  /**
+   * 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 the OTP field contains at least one character.
+   */
+  filled = "data-filled",
+  /**
+   * Present when one of the OTP field inputs is focused.
+   */
+  focused = "data-focused",
+}

package/otp-field/root/OTPFieldRootDataAttributes.js

@@ -0,0 +1,49 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.OTPFieldRootDataAttributes = void 0;
+let OTPFieldRootDataAttributes = exports.OTPFieldRootDataAttributes = /*#__PURE__*/function (OTPFieldRootDataAttributes) {
+  /**
+   * Present when all slots are filled.
+   */
+  OTPFieldRootDataAttributes["complete"] = "data-complete";
+  /**
+   * Present when the OTP field is disabled.
+   */
+  OTPFieldRootDataAttributes["disabled"] = "data-disabled";
+  /**
+   * Present when the OTP field is readonly.
+   */
+  OTPFieldRootDataAttributes["readonly"] = "data-readonly";
+  /**
+   * Present when the OTP field is required.
+   */
+  OTPFieldRootDataAttributes["required"] = "data-required";
+  /**
+   * Present when the OTP field is in valid state (when wrapped in Field.Root).
+   */
+  OTPFieldRootDataAttributes["valid"] = "data-valid";
+  /**
+   * Present when the OTP field is in invalid state (when wrapped in Field.Root).
+   */
+  OTPFieldRootDataAttributes["invalid"] = "data-invalid";
+  /**
+   * Present when the OTP field has been touched (when wrapped in Field.Root).
+   */
+  OTPFieldRootDataAttributes["touched"] = "data-touched";
+  /**
+   * Present when the OTP field's value has changed (when wrapped in Field.Root).
+   */
+  OTPFieldRootDataAttributes["dirty"] = "data-dirty";
+  /**
+   * Present when the OTP field contains at least one character.
+   */
+  OTPFieldRootDataAttributes["filled"] = "data-filled";
+  /**
+   * Present when one of the OTP field inputs is focused.
+   */
+  OTPFieldRootDataAttributes["focused"] = "data-focused";
+  return OTPFieldRootDataAttributes;
+}({});

package/otp-field/utils/otp.d.ts

@@ -0,0 +1,21 @@
+interface OTPValidationConfig {
+  slotPattern: string;
+  getRootPattern: (length: number) => string;
+  regexp: RegExp;
+  inputMode: 'numeric' | 'text';
+}
+export type OTPValidationType = 'numeric' | 'alpha' | 'alphanumeric' | 'none';
+export declare function getOTPValidationConfig(validationType: OTPValidationType): OTPValidationConfig | null;
+export declare function stripOTPWhitespace(value: string | null | undefined): string;
+/**
+ * Normalizes user-entered OTP text by stripping whitespace, applying validation or custom
+ * sanitization, and clamping the final value to the configured slot count.
+ */
+export declare function normalizeOTPValue(value: string | null | undefined, length: number, validationType: OTPValidationType, sanitizeValue?: ((value: string) => string) | undefined): string;
+/**
+ * Replaces characters starting at the provided slot index, then re-normalizes the final OTP value
+ * so paste and multi-character edits stay contiguous and length-bounded.
+ */
+export declare function replaceOTPValue(currentValue: string, index: number, nextValue: string, length: number, validationType: OTPValidationType, sanitizeValue?: ((value: string) => string) | undefined): string;
+export declare function removeOTPCharacter(currentValue: string, index: number): string;
+export {};

package/otp-field/utils/otp.js

@@ -0,0 +1,76 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getOTPValidationConfig = getOTPValidationConfig;
+exports.normalizeOTPValue = normalizeOTPValue;
+exports.removeOTPCharacter = removeOTPCharacter;
+exports.replaceOTPValue = replaceOTPValue;
+exports.stripOTPWhitespace = stripOTPWhitespace;
+const OTP_VALIDATION_CONFIG = {
+  numeric: {
+    slotPattern: '\\d{1}',
+    getRootPattern: length => `\\d{${length}}`,
+    regexp: /[^\d]/g,
+    inputMode: 'numeric'
+  },
+  alpha: {
+    slotPattern: '[a-zA-Z]{1}',
+    getRootPattern: length => `[a-zA-Z]{${length}}`,
+    regexp: /[^a-zA-Z]/g,
+    inputMode: 'text'
+  },
+  alphanumeric: {
+    slotPattern: '[a-zA-Z0-9]{1}',
+    getRootPattern: length => `[a-zA-Z0-9]{${length}}`,
+    regexp: /[^a-zA-Z0-9]/g,
+    inputMode: 'text'
+  }
+};
+function getOTPValidationConfig(validationType) {
+  if (validationType === 'none') {
+    return null;
+  }
+  return OTP_VALIDATION_CONFIG[validationType];
+}
+function removeWhitespace(value) {
+  return value.replace(/\s/g, '');
+}
+function stripOTPWhitespace(value) {
+  return removeWhitespace(value ?? '');
+}
+
+/**
+ * Normalizes user-entered OTP text by stripping whitespace, applying validation or custom
+ * sanitization, and clamping the final value to the configured slot count.
+ */
+function normalizeOTPValue(value, length, validationType, sanitizeValue) {
+  let sanitizedValue = stripOTPWhitespace(value);
+  const validation = getOTPValidationConfig(validationType);
+  if (validation) {
+    sanitizedValue = sanitizedValue.replace(validation.regexp, '');
+  } else if (sanitizeValue) {
+    sanitizedValue = sanitizeValue(sanitizedValue);
+  }
+
+  // Slice by Unicode code points so multi-byte characters do not split across OTP slots.
+  return Array.from(sanitizedValue).slice(0, Math.max(length, 0)).join('');
+}
+
+/**
+ * Replaces characters starting at the provided slot index, then re-normalizes the final OTP value
+ * so paste and multi-character edits stay contiguous and length-bounded.
+ */
+function replaceOTPValue(currentValue, index, nextValue, length, validationType, sanitizeValue) {
+  const normalizedValue = normalizeOTPValue(nextValue, length, validationType, sanitizeValue);
+  const prefix = currentValue.slice(0, index);
+  const suffix = currentValue.slice(index + normalizedValue.length);
+  return normalizeOTPValue(`${prefix}${normalizedValue}${suffix}`, length, validationType, sanitizeValue);
+}
+function removeOTPCharacter(currentValue, index) {
+  if (index < 0 || index >= currentValue.length) {
+    return currentValue;
+  }
+  return `${currentValue.slice(0, index)}${currentValue.slice(index + 1)}`;
+}

package/otp-field/utils/stateAttributesMapping.d.ts

@@ -0,0 +1,5 @@
+import type { StateAttributesMapping } from "../../utils/getStateAttributesProps.js";
+import type { OTPFieldRootState } from "../root/OTPFieldRoot.js";
+import type { OTPFieldInputState } from "../input/OTPFieldInput.js";
+export declare const rootStateAttributesMapping: StateAttributesMapping<OTPFieldRootState>;
+export declare const inputStateAttributesMapping: StateAttributesMapping<OTPFieldInputState>;

package/otp-field/utils/stateAttributesMapping.js

@@ -0,0 +1,17 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.rootStateAttributesMapping = exports.inputStateAttributesMapping = void 0;
+var _constants = require("../../field/utils/constants");
+const rootStateAttributesMapping = exports.rootStateAttributesMapping = {
+  value: () => null,
+  length: () => null,
+  ..._constants.fieldValidityMapping
+};
+const inputStateAttributesMapping = exports.inputStateAttributesMapping = {
+  value: () => null,
+  index: () => null,
+  ..._constants.fieldValidityMapping
+};