@base-ui/react 1.2.0 → 1.4.0

package/esm/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/esm/otp-field/root/OTPFieldRootDataAttributes.js

@@ -0,0 +1,43 @@
+export let 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/esm/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/esm/otp-field/utils/otp.js

@@ -0,0 +1,66 @@
+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'
+  }
+};
+export function getOTPValidationConfig(validationType) {
+  if (validationType === 'none') {
+    return null;
+  }
+  return OTP_VALIDATION_CONFIG[validationType];
+}
+function removeWhitespace(value) {
+  return value.replace(/\s/g, '');
+}
+export 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.
+ */
+export 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.
+ */
+export 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);
+}
+export function removeOTPCharacter(currentValue, index) {
+  if (index < 0 || index >= currentValue.length) {
+    return currentValue;
+  }
+  return `${currentValue.slice(0, index)}${currentValue.slice(index + 1)}`;
+}

package/esm/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/esm/otp-field/utils/stateAttributesMapping.js

@@ -0,0 +1,11 @@
+import { fieldValidityMapping } from "../../field/utils/constants.js";
+export const rootStateAttributesMapping = {
+  value: () => null,
+  length: () => null,
+  ...fieldValidityMapping
+};
+export const inputStateAttributesMapping = {
+  value: () => null,
+  index: () => null,
+  ...fieldValidityMapping
+};

package/esm/popover/arrow/PopoverArrow.d.ts

@@ -13,11 +13,20 @@ export interface PopoverArrowState {
    * Whether the popover is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the arrow cannot be centered on the anchor.
+   */
   uncentered: boolean;
 }
-export interface PopoverArrowProps extends BaseUIComponentProps<'div', PopoverArrow.State> {}
+export interface PopoverArrowProps extends BaseUIComponentProps<'div', PopoverArrowState> {}
 export declare namespace PopoverArrow {
   type State = PopoverArrowState;
   type Props = PopoverArrowProps;

package/esm/popover/arrow/PopoverArrow.js

@@ -16,6 +16,7 @@ export const PopoverArrow = /*#__PURE__*/React.forwardRef(function PopoverArrow(
   const {
     className,
     render,
+    style,
     ...elementProps
   } = componentProps;
   const {

package/esm/popover/backdrop/PopoverBackdrop.d.ts

@@ -13,9 +13,12 @@ export interface PopoverBackdropState {
    * Whether the popover is currently open.
    */
   open: boolean;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
 }
-export interface PopoverBackdropProps extends BaseUIComponentProps<'div', PopoverBackdrop.State> {}
+export interface PopoverBackdropProps extends BaseUIComponentProps<'div', PopoverBackdropState> {}
 export declare namespace PopoverBackdrop {
   type State = PopoverBackdropState;
   type Props = PopoverBackdropProps;

package/esm/popover/backdrop/PopoverBackdrop.js

@@ -21,6 +21,7 @@ export const PopoverBackdrop = /*#__PURE__*/React.forwardRef(function PopoverBac
   const {
     className,
     render,
+    style,
     ...elementProps
   } = props;
   const {

package/esm/popover/close/PopoverClose.d.ts

@@ -8,7 +8,7 @@ import type { BaseUIComponentProps, NativeButtonProps } from "../../utils/types.
  */
 export declare const PopoverClose: React.ForwardRefExoticComponent<Omit<PopoverCloseProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 export interface PopoverCloseState {}
-export interface PopoverCloseProps extends NativeButtonProps, BaseUIComponentProps<'button', PopoverClose.State> {}
+export interface PopoverCloseProps extends NativeButtonProps, BaseUIComponentProps<'button', PopoverCloseState> {}
 export declare namespace PopoverClose {
   type State = PopoverCloseState;
   type Props = PopoverCloseProps;

package/esm/popover/close/PopoverClose.js

@@ -6,6 +6,7 @@ import { useRenderElement } from "../../utils/useRenderElement.js";
 import { useButton } from "../../use-button/index.js";
 import { createChangeEventDetails } from "../../utils/createBaseUIEventDetails.js";
 import { REASONS } from "../../utils/reasons.js";
+import { useClosePartRegistration } from "../../utils/closePart.js";
 
 /**
  * A button that closes the popover.
@@ -13,14 +14,15 @@ import { REASONS } from "../../utils/reasons.js";
  *
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */
-export const PopoverClose = /*#__PURE__*/React.forwardRef(function PopoverClose(props, forwardedRef) {
+export const PopoverClose = /*#__PURE__*/React.forwardRef(function PopoverClose(componentProps, forwardedRef) {
   const {
     render,
     className,
     disabled = false,
     nativeButton = true,
+    style,
     ...elementProps
-  } = props;
+  } = componentProps;
   const {
     buttonRef,
     getButtonProps
@@ -32,7 +34,8 @@ export const PopoverClose = /*#__PURE__*/React.forwardRef(function PopoverClose(
   const {
     store
   } = usePopoverRootContext();
-  const element = useRenderElement('button', props, {
+  useClosePartRegistration();
+  const element = useRenderElement('button', componentProps, {
     ref: [forwardedRef, buttonRef],
     props: [{
       onClick(event) {

package/esm/popover/description/PopoverDescription.d.ts

@@ -8,7 +8,7 @@ import type { BaseUIComponentProps } from "../../utils/types.js";
  */
 export declare const PopoverDescription: React.ForwardRefExoticComponent<Omit<PopoverDescriptionProps, "ref"> & React.RefAttributes<HTMLParagraphElement>>;
 export interface PopoverDescriptionState {}
-export interface PopoverDescriptionProps extends BaseUIComponentProps<'p', PopoverDescription.State> {}
+export interface PopoverDescriptionProps extends BaseUIComponentProps<'p', PopoverDescriptionState> {}
 export declare namespace PopoverDescription {
   type State = PopoverDescriptionState;
   type Props = PopoverDescriptionProps;

package/esm/popover/description/PopoverDescription.js

@@ -16,6 +16,7 @@ export const PopoverDescription = /*#__PURE__*/React.forwardRef(function Popover
   const {
     render,
     className,
+    style,
     ...elementProps
   } = componentProps;
   const {

package/esm/popover/popup/PopoverPopup.d.ts

@@ -15,12 +15,24 @@ export interface PopoverPopupState {
    * Whether the popover is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * The transition status of the component.
+   */
   transitionStatus: TransitionStatus;
+  /**
+   * Whether transitions should be skipped.
+   */
   instant: 'dismiss' | 'click' | undefined;
 }
-export interface PopoverPopupProps extends BaseUIComponentProps<'div', PopoverPopup.State> {
+export interface PopoverPopupProps extends BaseUIComponentProps<'div', PopoverPopupState> {
   /**
    * Determines the element to focus when the popover is opened.
    *
@@ -30,7 +42,7 @@ export interface PopoverPopupProps extends BaseUIComponentProps<'div', PopoverPo
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  initialFocus?: (boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null)) | undefined;
+  initialFocus?: boolean | React.RefObject<HTMLElement | null> | ((openType: InteractionType) => void | boolean | HTMLElement | null) | undefined;
   /**
    * Determines the element to focus when the popover is closed.
    *
@@ -40,7 +52,7 @@ export interface PopoverPopupProps extends BaseUIComponentProps<'div', PopoverPo
    * - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
    *   Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
    */
-  finalFocus?: (boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null)) | undefined;
+  finalFocus?: boolean | React.RefObject<HTMLElement | null> | ((closeType: InteractionType) => void | boolean | HTMLElement | null) | undefined;
 }
 export declare namespace PopoverPopup {
   type State = PopoverPopupState;

package/esm/popover/popup/PopoverPopup.js

@@ -13,6 +13,7 @@ import { REASONS } from "../../utils/reasons.js";
 import { COMPOSITE_KEYS } from "../../composite/composite.js";
 import { useToolbarRootContext } from "../../toolbar/root/ToolbarRootContext.js";
 import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
+import { ClosePartProvider, useClosePartCount } from "../../utils/closePart.js";
 import { jsx as _jsx } from "react/jsx-runtime";
 const stateAttributesMapping = {
   ...baseMapping,
@@ -31,6 +32,7 @@ export const PopoverPopup = /*#__PURE__*/React.forwardRef(function PopoverPopup(
     render,
     initialFocus,
     finalFocus,
+    style,
     ...elementProps
   } = componentProps;
   const {
@@ -38,6 +40,10 @@ export const PopoverPopup = /*#__PURE__*/React.forwardRef(function PopoverPopup(
   } = usePopoverRootContext();
   const positioner = usePopoverPositionerContext();
   const insideToolbar = useToolbarRootContext(true) != null;
+  const {
+    context: closePartContext,
+    hasClosePart
+  } = useClosePartCount();
   const open = store.useState('open');
   const openMethod = store.useState('openMethod');
   const instantType = store.useState('instantType');
@@ -84,6 +90,8 @@ export const PopoverPopup = /*#__PURE__*/React.forwardRef(function PopoverPopup(
     instant: instantType,
     transitionStatus
   };
+  const focusManagerModal = modal !== false && hasClosePart;
+  store.useSyncedValue('focusManagerModal', focusManagerModal);
   const setPopupElement = React.useCallback(element => {
     store.set('popupElement', element);
   }, [store]);
@@ -104,7 +112,7 @@ export const PopoverPopup = /*#__PURE__*/React.forwardRef(function PopoverPopup(
   return /*#__PURE__*/_jsx(FloatingFocusManager, {
     context: floatingContext,
     openInteractionType: openMethod,
-    modal: modal === 'trap-focus',
+    modal: focusManagerModal,
     disabled: !mounted || openReason === REASONS.triggerHover,
     initialFocus: resolvedInitialFocus,
     returnFocus: finalFocus,
@@ -112,7 +120,10 @@ export const PopoverPopup = /*#__PURE__*/React.forwardRef(function PopoverPopup(
     previousFocusableElement: isHTMLElement(activeTriggerElement) ? activeTriggerElement : undefined,
     nextFocusableElement: store.context.triggerFocusTargetRef,
     beforeContentFocusGuardRef: store.context.beforeContentFocusGuardRef,
-    children: element
+    children: /*#__PURE__*/_jsx(ClosePartProvider, {
+      value: closePartContext,
+      children: element
+    })
   });
 });
 if (process.env.NODE_ENV !== "production") PopoverPopup.displayName = "PopoverPopup";

package/esm/popover/portal/PopoverPortal.d.ts

@@ -8,10 +8,8 @@ import { FloatingPortal } from "../../floating-ui-react/index.js";
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */
 export declare const PopoverPortal: React.ForwardRefExoticComponent<Omit<PopoverPortalProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
-export declare namespace PopoverPortal {
-  interface State {}
-}
-export interface PopoverPortalProps extends FloatingPortal.Props<PopoverPortal.State> {
+export interface PopoverPortalState {}
+export interface PopoverPortalProps extends FloatingPortal.Props<PopoverPortalState> {
   /**
    * Whether to keep the portal mounted in the DOM while the popup is hidden.
    * @default false
@@ -19,5 +17,6 @@ export interface PopoverPortalProps extends FloatingPortal.Props<PopoverPortal.S
   keepMounted?: boolean | undefined;
 }
 export declare namespace PopoverPortal {
+  type State = PopoverPortalState;
   type Props = PopoverPortalProps;
 }

package/esm/popover/positioner/PopoverPositioner.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { useAnchorPositioning, type Side, type Align } from "../../utils/useAnchorPositioning.js";
+import { type Side, type Align, type UseAnchorPositioningSharedParameters } from "../../utils/useAnchorPositioning.js";
 import type { BaseUIComponentProps } from "../../utils/types.js";
 /**
  * Positions the popover against the trigger.
@@ -13,15 +13,24 @@ export interface PopoverPositionerState {
    * Whether the popover is currently open.
    */
   open: boolean;
+  /**
+   * The side of the anchor the component is placed on.
+   */
   side: Side;
+  /**
+   * The alignment of the component relative to the anchor.
+   */
   align: Align;
+  /**
+   * Whether the anchor element is hidden.
+   */
   anchorHidden: boolean;
   /**
    * Whether CSS transitions should be disabled.
    */
   instant: string | undefined;
 }
-export interface PopoverPositionerProps extends useAnchorPositioning.SharedParameters, BaseUIComponentProps<'div', PopoverPositioner.State> {}
+export interface PopoverPositionerProps extends UseAnchorPositioningSharedParameters, BaseUIComponentProps<'div', PopoverPositionerState> {}
 export declare namespace PopoverPositioner {
   type State = PopoverPositionerState;
   type Props = PopoverPositionerProps;

package/esm/popover/positioner/PopoverPositioner.js

@@ -7,15 +7,14 @@ import { FloatingNode, useFloatingNodeId } from "../../floating-ui-react/index.j
 import { usePopoverRootContext } from "../root/PopoverRootContext.js";
 import { PopoverPositionerContext } from "./PopoverPositionerContext.js";
 import { useAnchorPositioning } from "../../utils/useAnchorPositioning.js";
-import { popupStateMapping } from "../../utils/popupStateMapping.js";
 import { usePopoverPortalContext } from "../portal/PopoverPortalContext.js";
 import { InternalBackdrop } from "../../utils/InternalBackdrop.js";
 import { REASONS } from "../../utils/reasons.js";
-import { useRenderElement } from "../../utils/useRenderElement.js";
 import { POPUP_COLLISION_AVOIDANCE } from "../../utils/constants.js";
 import { useAnimationsFinished } from "../../utils/useAnimationsFinished.js";
 import { adaptiveOrigin } from "../../utils/adaptiveOriginMiddleware.js";
-import { getDisabledMountTransitionStyles } from "../../utils/getDisabledMountTransitionStyles.js";
+import { usePositioner } from "../../utils/usePositioner.js";
+import { useAnchoredPopupScrollLock } from "../../utils/useAnchoredPopupScrollLock.js";
 
 /**
  * Positions the popover against the trigger.
@@ -40,6 +39,7 @@ export const PopoverPositioner = /*#__PURE__*/React.forwardRef(function PopoverP
     sticky = false,
     disableAnchorTracking = false,
     collisionAvoidance = POPUP_COLLISION_AVOIDANCE,
+    style,
     ...elementProps
   } = componentProps;
   const {
@@ -53,6 +53,7 @@ export const PopoverPositioner = /*#__PURE__*/React.forwardRef(function PopoverP
   const openReason = store.useState('openChangeReason');
   const triggerElement = store.useState('activeTriggerElement');
   const modal = store.useState('modal');
+  const openMethod = store.useState('openMethod');
   const positionerElement = store.useState('positionerElement');
   const instantType = store.useState('instantType');
   const transitionStatus = store.useState('transitionStatus');
@@ -78,24 +79,6 @@ export const PopoverPositioner = /*#__PURE__*/React.forwardRef(function PopoverP
     collisionAvoidance,
     adaptiveOrigin: hasViewport ? adaptiveOrigin : undefined
   });
-  const defaultProps = React.useMemo(() => {
-    const hiddenStyles = {};
-    if (!open) {
-      hiddenStyles.pointerEvents = 'none';
-    }
-    return {
-      role: 'presentation',
-      hidden: !mounted,
-      style: {
-        ...positioning.positionerStyles,
-        ...hiddenStyles
-      }
-    };
-  }, [open, mounted, positioning.positionerStyles]);
-  const positioner = React.useMemo(() => ({
-    props: defaultProps,
-    ...positioning
-  }), [defaultProps, positioning]);
   const domReference = floatingRootContext.useState('domReferenceElement');
 
   // When the current trigger element changes, enable transitions on the
@@ -120,22 +103,25 @@ export const PopoverPositioner = /*#__PURE__*/React.forwardRef(function PopoverP
   }, [domReference, runOnceAnimationsFinish, store]);
   const state = {
     open,
-    side: positioner.side,
-    align: positioner.align,
-    anchorHidden: positioner.anchorHidden,
+    side: positioning.side,
+    align: positioning.align,
+    anchorHidden: positioning.anchorHidden,
     instant: instantType
   };
+  useAnchoredPopupScrollLock(open && modal === true && openReason !== REASONS.triggerHover, openMethod === 'touch', positionerElement, triggerElement);
   const setPositionerElement = React.useCallback(element => {
     store.set('positionerElement', element);
   }, [store]);
-  const element = useRenderElement('div', componentProps, {
-    state,
-    props: [positioner.props, getDisabledMountTransitionStyles(transitionStatus), elementProps],
-    ref: [forwardedRef, setPositionerElement],
-    stateAttributesMapping: popupStateMapping
+  const element = usePositioner(componentProps, state, {
+    styles: positioning.positionerStyles,
+    transitionStatus,
+    props: elementProps,
+    refs: [forwardedRef, setPositionerElement],
+    hidden: !mounted,
+    inert: !open
   });
   return /*#__PURE__*/_jsxs(PopoverPositionerContext.Provider, {
-    value: positioner,
+    value: positioning,
     children: [mounted && modal === true && openReason !== REASONS.triggerHover && /*#__PURE__*/_jsx(InternalBackdrop, {
       ref: store.context.internalBackdropRef,
       inert: inertValue(!open),

package/esm/popover/root/PopoverRoot.d.ts

@@ -5,7 +5,7 @@ import { REASONS } from "../../utils/reasons.js";
 import { type PayloadChildRenderFunction } from "../../utils/popups/index.js";
 /**
  * Groups all parts of the popover.
- * Doesn’t render its own HTML element.
+ * Doesn't render its own HTML element.
  *
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */
@@ -44,20 +44,27 @@ export interface PopoverRootProps<Payload = unknown> {
    * - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.
    * - `false`: user interaction with the rest of the document is allowed.
    * - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
+   *
+   * When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered
+   * inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as
+   * Tailwind's `sr-only` utility.
+   *
+   * When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch
+   * screen readers can escape the popup.
    * @default false
    */
-  modal?: (boolean | 'trap-focus') | undefined;
+  modal?: boolean | 'trap-focus' | undefined;
   /**
    * ID of the trigger that the popover is associated with.
    * This is useful in conjunction with the `open` prop to create a controlled popover.
-   * There's no need to specify this prop when the popover is uncontrolled (i.e. when the `open` prop is not set).
+   * There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).
    */
-  triggerId?: (string | null) | undefined;
+  triggerId?: string | null | undefined;
   /**
    * ID of the trigger that the popover is associated with.
    * This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
    */
-  defaultTriggerId?: (string | null) | undefined;
+  defaultTriggerId?: string | null | undefined;
   /**
    * A handle to associate the popover with a trigger.
    * If specified, allows external triggers to control the popover's open state.

package/esm/popover/root/PopoverRoot.js

@@ -1,7 +1,6 @@
 'use client';
 
 import * as React from 'react';
-import { useScrollLock } from '@base-ui/utils/useScrollLock';
 import { useOnFirstRender } from '@base-ui/utils/useOnFirstRender';
 import { useDismiss, useInteractions, useRole, FloatingTree, useFloatingParentNodeId, useSyncedFloatingRootContext } from "../../floating-ui-react/index.js";
 import { PopoverRootContext, usePopoverRootContext } from "./PopoverRootContext.js";
@@ -45,15 +44,12 @@ function PopoverRootComponent({
   store.useControlledProp('openProp', openProp);
   store.useControlledProp('triggerIdProp', triggerIdProp);
   const open = store.useState('open');
-  const positionerElement = store.useState('positionerElement');
   const payload = store.useState('payload');
-  const openReason = store.useState('openChangeReason');
   store.useContextCallback('onOpenChange', onOpenChange);
   store.useContextCallback('onOpenChangeComplete', onOpenChangeComplete);
   const {
     openMethod,
-    triggerProps: interactionTypeTriggerProps,
-    reset: resetOpenInteractionType
+    triggerProps: interactionTypeTriggerProps
   } = useOpenInteractionType(open);
   useImplicitActiveTrigger(store);
   const {
@@ -63,9 +59,7 @@ function PopoverRootComponent({
       stickIfOpen: true,
       openChangeReason: null
     });
-    resetOpenInteractionType();
   });
-  useScrollLock(open && modal === true && openReason !== REASONS.triggerHover && openMethod !== 'touch', positionerElement);
   React.useEffect(() => {
     if (!open) {
       store.context.stickIfOpenTimeout.clear();
@@ -134,7 +128,7 @@ function PopoverRootComponent({
 
 /**
  * Groups all parts of the popover.
- * Doesn’t render its own HTML element.
+ * Doesn't render its own HTML element.
  *
  * Documentation: [Base UI Popover](https://base-ui.com/react/components/popover)
  */