@base-ui/react 1.4.1 → 1.5.0

package/navigation-menu/backdrop/NavigationMenuBackdrop.js

@@ -24,8 +24,8 @@ const stateAttributesMapping = {
  */
 const NavigationMenuBackdrop = exports.NavigationMenuBackdrop = /*#__PURE__*/React.forwardRef(function NavigationMenuBackdrop(componentProps, forwardedRef) {
   const {
-    className,
     render,
+    className,
     style,
     ...elementProps
   } = componentProps;

package/navigation-menu/content/NavigationMenuContent.js

@@ -9,6 +9,7 @@ exports.NavigationMenuContent = void 0;
 var React = _interopRequireWildcard(require("react"));
 var ReactDOM = _interopRequireWildcard(require("react-dom"));
 var _useIsoLayoutEffect = require("@base-ui/utils/useIsoLayoutEffect");
+var _useStableCallback = require("@base-ui/utils/useStableCallback");
 var _inertValue = require("@base-ui/utils/inertValue");
 var _empty = require("@base-ui/utils/empty");
 var _floatingUiReact = require("../../floating-ui-react");
@@ -43,10 +44,10 @@ const stateAttributesMapping = {
  */
 const NavigationMenuContent = exports.NavigationMenuContent = /*#__PURE__*/React.forwardRef(function NavigationMenuContent(componentProps, forwardedRef) {
   const {
-    className,
     render,
-    keepMounted = false,
+    className,
     style,
+    keepMounted = false,
     ...elementProps
   } = componentProps;
   const {
@@ -100,11 +101,13 @@ const NavigationMenuContent = exports.NavigationMenuContent = /*#__PURE__*/React
     transitionStatus,
     activationDirection
   };
-  const handleCurrentContentRef = React.useCallback(node => {
-    if (node) {
+  const handleCurrentContentRef = (0, _useStableCallback.useStableCallback)(node => {
+    // Inactive `keepMounted` content also mounts in the viewport; only the
+    // active content can own the shared sizing observer target.
+    if (node && open) {
       currentContentRef.current = node;
     }
-  }, [currentContentRef]);
+  });
   const commonProps = {
     onFocus(event) {
       const target = (0, _utils.getTarget)(event.nativeEvent);

package/navigation-menu/icon/NavigationMenuIcon.js

@@ -18,8 +18,8 @@ var _NavigationMenuItemContext = require("../item/NavigationMenuItemContext");
  */
 const NavigationMenuIcon = exports.NavigationMenuIcon = /*#__PURE__*/React.forwardRef(function NavigationMenuIcon(componentProps, forwardedRef) {
   const {
-    className,
     render,
+    className,
     style,
     ...elementProps
   } = componentProps;

package/navigation-menu/item/NavigationMenuItem.js

@@ -19,10 +19,10 @@ var _jsxRuntime = require("react/jsx-runtime");
  */
 const NavigationMenuItem = exports.NavigationMenuItem = /*#__PURE__*/React.forwardRef(function NavigationMenuItem(componentProps, forwardedRef) {
   const {
-    className,
     render,
-    value: valueProp,
+    className,
     style,
+    value: valueProp,
     ...elementProps
   } = componentProps;
   const fallbackValue = (0, _useBaseUiId.useBaseUiId)();

package/navigation-menu/list/NavigationMenuList.js

@@ -25,8 +25,8 @@ var _jsxRuntime = require("react/jsx-runtime");
  */
 const NavigationMenuList = exports.NavigationMenuList = /*#__PURE__*/React.forwardRef(function NavigationMenuList(componentProps, forwardedRef) {
   const {
-    className,
     render,
+    className,
     style,
     ...elementProps
   } = componentProps;

package/navigation-menu/popup/NavigationMenuPopup.js

@@ -27,10 +27,10 @@ const stateAttributesMapping = {
  */
 const NavigationMenuPopup = exports.NavigationMenuPopup = /*#__PURE__*/React.forwardRef(function NavigationMenuPopup(componentProps, forwardedRef) {
   const {
-    className,
     render,
-    id: idProp,
+    className,
     style,
+    id: idProp,
     ...elementProps
   } = componentProps;
   const {

package/navigation-menu/root/NavigationMenuRoot.js

@@ -223,9 +223,7 @@ function TreeContext(props) {
   const nodeId = (0, _floatingUiReact.useFloatingNodeId)();
   const {
     rootRef,
-    nested
-  } = (0, _NavigationMenuRootContext.useNavigationMenuRootContext)();
-  const {
+    nested,
     open
   } = (0, _NavigationMenuRootContext.useNavigationMenuRootContext)();
   const state = {

package/navigation-menu/trigger/NavigationMenuTrigger.js

@@ -37,6 +37,8 @@ var _constants2 = require("../utils/constants");
 var _NavigationMenuDismissContext = require("../list/NavigationMenuDismissContext");
 var _NavigationMenuPopupCssVars = require("../popup/NavigationMenuPopupCssVars");
 var _NavigationMenuPositionerCssVars = require("../positioner/NavigationMenuPositionerCssVars");
+var _mergeProps = require("../../merge-props");
+var _DirectionContext = require("../../internals/direction-context/DirectionContext");
 var _jsxRuntime = require("react/jsx-runtime");
 const DEFAULT_SIZE = {
   width: 0,
@@ -52,11 +54,11 @@ const DEFAULT_SIZE = {
  */
 const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React.forwardRef(function NavigationMenuTrigger(componentProps, forwardedRef) {
   const {
-    className,
     render,
+    className,
+    style,
     nativeButton = true,
     disabled,
-    style,
     ...elementProps
   } = componentProps;
   const {
@@ -90,6 +92,7 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
   const nodeId = (0, _NavigationMenuRootContext.useNavigationMenuTreeContext)();
   const tree = (0, _floatingUiReact.useFloatingTree)();
   const dismissProps = (0, _NavigationMenuDismissContext.useNavigationMenuDismissContext)();
+  const direction = (0, _DirectionContext.useDirection)();
   const stickIfOpenTimeout = (0, _useTimeout.useTimeout)();
   const focusFrame = (0, _useAnimationFrame.useAnimationFrame)();
   const mutationFrame = (0, _useAnimationFrame.useAnimationFrame)();
@@ -349,7 +352,11 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
     mutationObserver.observe(observedElement, {
       childList: true,
       subtree: true,
-      characterData: true
+      characterData: true,
+      // `keepMounted` submenu switches update dimensions by toggling hidden
+      // content rather than inserting or removing content nodes.
+      attributes: true,
+      attributeFilter: ['hidden']
     });
     return () => {
       mutationObserver.disconnect();
@@ -368,14 +375,15 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
   }, [beforeOutsideRef, focusFrame, isActiveItem, open, popupElement]);
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     if (isActiveItemRef.current && open && popupElement) {
-      if (transitionStatus === 'starting') {
-        const hasNestedMenu = currentContentRef.current?.querySelector('[data-nested]') != null;
-        if (hasNestedMenu) {
-          sizeFrame.request(syncCurrentSize);
-          return () => {
-            sizeFrame.cancel();
-          };
-        }
+      const hasNestedMenu = currentContentRef.current?.querySelector('[data-nested]') != null;
+      if (transitionStatus === 'starting' && hasNestedMenu) {
+        // Inline nested menus can reveal their default content after the
+        // top-level content enters the viewport. Defer once so the opening
+        // size is measured from the final nested content, not the shell.
+        sizeFrame.request(syncCurrentSize);
+        return () => {
+          sizeFrame.cancel();
+        };
       }
       if (skipAutoSizeSyncRef.current) {
         skipAutoSizeSyncRef.current = false;
@@ -478,9 +486,7 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
     stickIfOpen,
     toggle: isActiveItem
   });
-  const {
-    getReferenceProps
-  } = (0, _floatingUiReact.useInteractions)([hover, click]);
+  const referenceProps = React.useMemo(() => (0, _mergeProps.mergeProps)(click.reference, hover?.reference), [click.reference, hover]);
   (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
     if (isActiveItem) {
       setFloatingRootContext(context);
@@ -584,8 +590,9 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
       if (nested) {
         return;
       }
+      const verticalOpenKey = direction === 'rtl' ? 'ArrowLeft' : 'ArrowRight';
       const openHorizontal = orientation === 'horizontal' && event.key === 'ArrowDown';
-      const openVertical = orientation === 'vertical' && event.key === 'ArrowRight';
+      const openVertical = orientation === 'vertical' && event.key === verticalOpenKey;
       if (openHorizontal || openVertical) {
         setValue(itemValue, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.listNavigation, event.nativeEvent));
         handleOpenEvent(event);
@@ -624,7 +631,7 @@ const NavigationMenuTrigger = exports.NavigationMenuTrigger = /*#__PURE__*/React
       state: state,
       stateAttributesMapping: _popupStateMapping.pressableTriggerOpenStateMapping,
       refs: [forwardedRef, handleTriggerElement, buttonRef],
-      props: [getReferenceProps, dismissProps?.reference || _empty.EMPTY_ARRAY, defaultProps, elementProps, getButtonProps]
+      props: [referenceProps, dismissProps?.reference || _empty.EMPTY_ARRAY, defaultProps, elementProps, getButtonProps]
     }), isActiveItem && /*#__PURE__*/(0, _jsxRuntime.jsxs)(React.Fragment, {
       children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_FocusGuard.FocusGuard, {
         ref: beforeOutsideRef,

package/navigation-menu/utils/isOutsideMenuEvent.d.ts

@@ -5,7 +5,6 @@ interface Targets {
 }
 interface Params {
   popupElement: HTMLElement | null;
-  viewportElement?: HTMLElement | null | undefined;
   rootRef: React.RefObject<HTMLDivElement | null>;
   tree: FloatingTreeType | null;
   nodeId: string | undefined;

package/navigation-menu/utils/isOutsideMenuEvent.js

@@ -11,7 +11,6 @@ function isOutsideMenuEvent({
 }, params) {
   const {
     popupElement,
-    viewportElement,
     rootRef,
     tree,
     nodeId
@@ -23,8 +22,5 @@ function isOutsideMenuEvent({
   if (!popupElement) {
     return !(0, _utils.contains)(rootRef.current, relatedTarget) && !nodeChildrenContains;
   }
-
-  // Use popupElement as the primary floating element, but fall back to viewportElement if needed
-  const floatingElement = popupElement || viewportElement;
-  return !(0, _utils.contains)(floatingElement, currentTarget) && !(0, _utils.contains)(floatingElement, relatedTarget) && !(0, _utils.contains)(rootRef.current, relatedTarget) && !nodeChildrenContains && !((0, _utils.contains)(floatingElement, relatedTarget) && relatedTarget?.hasAttribute('data-base-ui-focus-guard'));
+  return !(0, _utils.contains)(popupElement, currentTarget) && !(0, _utils.contains)(popupElement, relatedTarget) && !(0, _utils.contains)(rootRef.current, relatedTarget) && !nodeChildrenContains && !((0, _utils.contains)(popupElement, relatedTarget) && relatedTarget?.hasAttribute('data-base-ui-focus-guard'));
 }

package/navigation-menu/viewport/NavigationMenuViewport.js

@@ -64,14 +64,13 @@ function Guards({
  *
  * Documentation: [Base UI Navigation Menu](https://base-ui.com/react/components/navigation-menu)
  */
-
 const NavigationMenuViewport = exports.NavigationMenuViewport = /*#__PURE__*/React.forwardRef(function NavigationMenuViewport(componentProps, forwardedRef) {
   const {
-    className,
     render,
+    className,
+    style,
     children,
     id: idProp,
-    style,
     ...elementProps
   } = componentProps;
   const id = (0, _useId.useId)(idProp);

package/number-field/input/NumberFieldInput.js

@@ -83,10 +83,7 @@ const NumberFieldInput = exports.NumberFieldInput = /*#__PURE__*/React.forwardRe
   } = (0, _LabelableContext.useLabelableContext)();
   const hasTouchedInputRef = React.useRef(false);
   const blockRevalidationRef = React.useRef(false);
-  (0, _useRegisterFieldControl.useRegisterFieldControl)(inputRef, {
-    id,
-    value
-  });
+  (0, _useRegisterFieldControl.useRegisterFieldControl)(inputRef, id, value);
   (0, _useValueChanged.useValueChanged)(value, previousValue => {
     const validateOnChange = shouldValidateOnChange();
     clearErrors(name);
@@ -260,13 +257,14 @@ const NumberFieldInput = exports.NumberFieldInput = /*#__PURE__*/React.forwardRe
       const isAsciiDigit = event.key >= '0' && event.key <= '9';
       const isArabicNumeral = _parse.ARABIC_DETECT_RE.test(event.key);
       const isHanNumeral = _parse.HAN_DETECT_RE.test(event.key);
+      const isPersianNumeral = _parse.PERSIAN_DETECT_RE.test(event.key);
       const isFullwidthNumeral = _parse.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) {
+      event.which === 229 || event.altKey || event.ctrlKey || event.metaKey || isAllowedNonNumericKey || isAsciiDigit || isArabicNumeral || isFullwidthNumeral || isHanNumeral || isPersianNumeral || isNavigateKey) {
         return;
       }
 

package/number-field/root/NumberFieldRoot.js

@@ -286,6 +286,7 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
 
       // Prevent the default behavior to avoid scrolling the page.
       event.preventDefault();
+      allowInputSyncRef.current = true;
       const amount = getStepAmount(event) ?? _constants.DEFAULT_STEP;
       incrementValue(amount, {
         direction: event.deltaY > 0 ? -1 : 1,
@@ -294,7 +295,7 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
       });
     }
     return (0, _addEventListener.addEventListener)(element, 'wheel', handleWheel);
-  }, [allowWheelScrub, incrementValue, disabled, readOnly, largeStep, step, getStepAmount]);
+  }, [allowWheelScrub, incrementValue, disabled, readOnly, getStepAmount]);
   const state = React.useMemo(() => ({
     ...fieldState,
     disabled,
@@ -350,7 +351,9 @@ const NumberFieldRoot = exports.NumberFieldRoot = /*#__PURE__*/React.forwardRef(
         },
         onChange(event) {
           // Workaround for https://github.com/facebook/react/issues/9023
-          if (event.nativeEvent.defaultPrevented) {
+          if (event.nativeEvent.defaultPrevented || disabled || readOnly) {
+            // Outside Field.Root, the event is not wrapped by mergeProps.
+            event.preventBaseUIHandler?.();
             return;
           }
 

package/number-field/scrub-area/NumberFieldScrubArea.js

@@ -48,6 +48,7 @@ const NumberFieldScrubArea = exports.NumberFieldScrubArea = /*#__PURE__*/React.f
     readOnly,
     inputRef,
     incrementValue,
+    allowInputSyncRef,
     getStepAmount,
     onValueCommitted,
     lastChangedValueRef,
@@ -146,8 +147,10 @@ const NumberFieldScrubArea = exports.NumberFieldScrubArea = /*#__PURE__*/React.f
 
           // Manually dispatch a click event if no movement happened, since
           // preventDefault on pointerdown prevents the browser click event.
-          if (!didMoveRef.current && pointerDownTargetRef.current != null) {
-            pointerDownTargetRef.current.dispatchEvent(new MouseEvent('click', {
+          const pointerDownTarget = pointerDownTargetRef.current;
+          const input = inputRef.current;
+          if (!didMoveRef.current && pointerDownTarget != null && input) {
+            pointerDownTarget.dispatchEvent(new ((0, _owner.ownerWindow)(input).MouseEvent)('click', {
               bubbles: true,
               cancelable: true
             }));
@@ -184,6 +187,7 @@ const NumberFieldScrubArea = exports.NumberFieldScrubArea = /*#__PURE__*/React.f
         const stepAmount = getStepAmount(event) ?? _constants.DEFAULT_STEP;
         const rawAmount = dValue * stepAmount;
         if (rawAmount !== 0) {
+          allowInputSyncRef.current = true;
           incrementValue(Math.abs(rawAmount), {
             direction: rawAmount >= 0 ? 1 : -1,
             event,
@@ -198,7 +202,7 @@ const NumberFieldScrubArea = exports.NumberFieldScrubArea = /*#__PURE__*/React.f
       exitPointerLockTimeout.clear();
       unsubscribe();
     };
-  }, [disabled, readOnly, incrementValue, isScrubbing, getStepAmount, inputRef, onScrubbingChange, onScrub, direction, pixelSensitivity, lastChangedValueRef, onValueCommitted, valueRef, exitPointerLockTimeout]);
+  }, [disabled, readOnly, allowInputSyncRef, incrementValue, isScrubbing, getStepAmount, inputRef, onScrubbingChange, onScrub, direction, pixelSensitivity, lastChangedValueRef, onValueCommitted, valueRef, exitPointerLockTimeout]);
 
   // Prevent scrolling using touch input when scrubbing.
   React.useEffect(function registerScrubberTouchPreventListener() {

package/otp-field/input/OTPFieldInput.js

@@ -11,6 +11,7 @@ var _safeReact = require("@base-ui/utils/safeReact");
 var _warn = require("@base-ui/utils/warn");
 var _utils = require("../../floating-ui-react/utils");
 var _useCompositeListItem = require("../../internals/composite/list/useCompositeListItem");
+var _DirectionContext = require("../../internals/direction-context/DirectionContext");
 var _useRenderElement = require("../../internals/useRenderElement");
 var _createBaseUIEventDetails = require("../../internals/createBaseUIEventDetails");
 var _reasons = require("../../internals/reasons");
@@ -51,7 +52,7 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
     reportValueInvalid,
     readOnly,
     required,
-    sanitizeValue,
+    normalizeValue,
     setValue,
     state,
     validationType,
@@ -64,6 +65,7 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
     indexGuessBehavior: _useCompositeListItem.IndexGuessBehavior.GuessFromOrder
   });
   const inputRef = React.useRef(null);
+  const direction = (0, _DirectionContext.useDirection)();
   const slotValue = value[index] ?? '';
   const inputState = (0, _OTPFieldRootContext.getOTPFieldInputState)(state, slotValue, index);
   const slotAriaLabel = externalAriaLabel;
@@ -123,9 +125,8 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
         return;
       }
       const rawValue = event.currentTarget.value;
-      const nextDigits = (0, _otp.normalizeOTPValue)(event.currentTarget.value, length, validationType, sanitizeValue);
-      const didSanitize = (0, _otp.stripOTPWhitespace)(rawValue).length > nextDigits.length;
-      if (didSanitize) {
+      const [nextDigits, didRejectCharacters] = (0, _otp.normalizeOTPValueWithDetails)(rawValue, length, validationType, normalizeValue);
+      if (didRejectCharacters) {
         reportValueInvalid(rawValue, (0, _createBaseUIEventDetails.createGenericEventDetails)(_reasons.REASONS.inputChange, event.nativeEvent));
       }
       if (nextDigits === '') {
@@ -137,7 +138,7 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
         }
         return;
       }
-      const nextValue = (0, _otp.replaceOTPValue)(value, index, nextDigits, length, validationType, sanitizeValue);
+      const nextValue = (0, _otp.replaceOTPValue)(value, index, nextDigits, length, validationType, normalizeValue);
       const committedValue = setValue(nextValue, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.inputChange, event.nativeEvent));
       if (committedValue != null) {
         const nextInput = Math.min(index + nextDigits.length, length - 1);
@@ -148,52 +149,66 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
       if (event.defaultPrevented || disabled) {
         return;
       }
-      if (event.key === 'ArrowLeft') {
+      const firstIndex = 0;
+      const lastIndex = Math.max(length - 1, firstIndex);
+      const endTargetIndex = Math.min(value.length, lastIndex);
+      const hasBoundaryModifier = (event.ctrlKey || event.metaKey) && !event.altKey;
+      const isRtl = direction === 'rtl';
+      const previousKey = isRtl ? 'ArrowRight' : 'ArrowLeft';
+      const nextKey = isRtl ? 'ArrowLeft' : 'ArrowRight';
+      if (event.key === previousKey) {
         (0, _utils.stopEvent)(event);
-        focusInput(Math.max(0, index - 1));
+        focusInput(hasBoundaryModifier ? firstIndex : Math.max(firstIndex, index - 1));
         return;
       }
-      if (event.key === 'ArrowRight') {
+      if (event.key === nextKey) {
         (0, _utils.stopEvent)(event);
-        focusInput(Math.min(length - 1, index + 1));
+        focusInput(hasBoundaryModifier ? endTargetIndex : Math.min(lastIndex, index + 1));
         return;
       }
-      if (event.key === 'Home') {
+      if (event.key === 'Home' || event.key === 'ArrowUp') {
         (0, _utils.stopEvent)(event);
-        focusInput(0);
+        focusInput(firstIndex);
         return;
       }
-      if (event.key === 'End') {
+      if (event.key === 'End' || event.key === 'ArrowDown') {
         (0, _utils.stopEvent)(event);
-        focusInput(Math.max(value.length - 1, 0));
+        focusInput(endTargetIndex);
         return;
       }
       if (readOnly) {
         return;
       }
-      if (event.key === 'Delete') {
-        (0, _utils.stopEvent)(event);
-        const committedValue = setValue((0, _otp.removeOTPCharacter)(value, index), (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.keyboard, event.nativeEvent));
+      function setKeyboardValue(nextValue, targetIndex) {
+        const committedValue = setValue(nextValue, (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.keyboard, event.nativeEvent));
         if (committedValue != null) {
-          queueFocusInput(index, committedValue);
+          queueFocusInput(targetIndex, committedValue);
         }
+      }
+      if (event.key === 'Backspace' && hasBoundaryModifier) {
+        (0, _utils.stopEvent)(event);
+        setKeyboardValue('', firstIndex);
+        return;
+      }
+      if (event.key === 'Delete') {
+        (0, _utils.stopEvent)(event);
+        setKeyboardValue((0, _otp.removeOTPCharacter)(value, index), index);
         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) {
         (0, _utils.stopEvent)(event);
-        focusInput(Math.min(length - 1, index + 1));
+        if (index < length - 1) {
+          focusInput(index + 1);
+        }
         return;
       }
       if (event.key === 'Backspace') {
         (0, _utils.stopEvent)(event);
-        const deleteIndex = slotValue === '' ? Math.max(0, index - 1) : index;
-        const targetIndex = Math.max(0, index - 1);
-        const committedValue = setValue((0, _otp.removeOTPCharacter)(value, deleteIndex), (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.keyboard, event.nativeEvent));
-        if (committedValue != null) {
-          queueFocusInput(targetIndex, committedValue);
-        }
+        const targetIndex = Math.max(firstIndex, index - 1);
+        const deleteIndex = slotValue === '' ? targetIndex : index;
+        setKeyboardValue((0, _otp.removeOTPCharacter)(value, deleteIndex), targetIndex);
       }
     },
     onPaste(event) {
@@ -211,15 +226,14 @@ const OTPFieldInput = exports.OTPFieldInput = /*#__PURE__*/React.forwardRef(func
         return;
       }
       event.preventDefault();
-      const nextDigits = (0, _otp.normalizeOTPValue)(rawValue, length, validationType, sanitizeValue);
-      const didSanitize = (0, _otp.stripOTPWhitespace)(rawValue).length > nextDigits.length;
-      if (didSanitize) {
+      const [nextDigits, didRejectCharacters] = (0, _otp.normalizeOTPValueWithDetails)(rawValue, length, validationType, normalizeValue);
+      if (didRejectCharacters) {
         reportValueInvalid(rawValue, (0, _createBaseUIEventDetails.createGenericEventDetails)(_reasons.REASONS.inputPaste, event.nativeEvent));
       }
       if (nextDigits === '') {
         return;
       }
-      const committedValue = setValue((0, _otp.replaceOTPValue)(value, index, nextDigits, length, validationType, sanitizeValue), (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.inputPaste, event.nativeEvent));
+      const committedValue = setValue((0, _otp.replaceOTPValue)(value, index, nextDigits, length, validationType, normalizeValue), (0, _createBaseUIEventDetails.createChangeEventDetails)(_reasons.REASONS.inputPaste, event.nativeEvent));
       if (committedValue != null) {
         const nextInput = Math.min(index + nextDigits.length, length - 1);
         queueFocusInput(nextInput, committedValue);

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

@@ -57,10 +57,17 @@ export interface OTPFieldRootProps extends Omit<BaseUIComponentProps<'div', OTPF
    */
   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.
+   * Function that normalizes the OTP value after whitespace and `validationType` filtering.
+   * It runs whenever OTP Field normalizes a value, including initial/default values, controlled
+   * values, and user edits.
+   *
+   * The returned value is filtered by `validationType` again, then clamped to `length`.
+   * It should be idempotent because OTP Field may normalize the same value more than once while
+   * handling edits, storing state, and rendering controlled or uncontrolled values. Non-idempotent
+   * normalizers can compound across those normalization passes. Characters rejected while
+   * normalizing typed or pasted text are reported through `onValueInvalid`.
    */
-  sanitizeValue?: ((value: string) => string) | undefined;
+  normalizeValue?: ((value: string) => string) | undefined;
   /**
    * Whether the user must enter a value before submitting a form.
    * @default false
@@ -99,16 +106,18 @@ export interface OTPFieldRootProps extends Omit<BaseUIComponentProps<'div', OTPF
    */
   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.
+   * Callback fired when entered text contains characters that are rejected by validation or
+   * normalization before the OTP value updates.
    *
-   * The `value` argument is the attempted user-entered string before sanitization.
+   * The `value` argument is the attempted user-entered string before normalization.
    */
   onValueInvalid?: ((value: string, eventDetails: OTPFieldRoot.InvalidEventDetails) => void) | undefined;
   /**
-   * Callback function that is fired when the OTP value becomes complete.
+   * Callback function that is fired when the OTP value becomes complete, or when a complete value
+   * is pasted while the OTP is already complete.
    *
-   * It runs later than `onValueChange`, after the internal value update is applied.
+   * When the value changes, it runs later than `onValueChange`, after the internal value update is
+   * applied. If a complete pasted value matches the current value, `onValueChange` does not fire.
    *
    * If `autoSubmit` is enabled, it runs immediately before the owning form is submitted.
    */