@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/Layout/padding.stylex.ts

@@ -3,7 +3,9 @@
 /**
  * @file padding.stylex.ts
  * @input Uses @stylexjs/stylex, spacing from theme
- * @output StyleX styles for numeric padding prop on layout components
+ * @output StyleX styles for numeric padding prop on layout components, the
+ *   container padding variables, and (re-exported) paddingStyles and
+ *   overlayPaddingReset
  * @position Layout utility; used by Card, Section, and Layout sub-components
  */
 
@@ -11,6 +13,12 @@ import * as stylex from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
 import type {SpacingStep} from '../utils/types';
 
+// In their own modules so an overlay's eager code imports them without this
+// one, and a lazily loaded overlay that uses the container padding styles
+// below keeps those out of the chunk it shares with that code.
+export {paddingStyles} from './paddingStyles.stylex';
+export {overlayPaddingReset} from './overlayPaddingReset.stylex';
+
 /**
  * Maps numeric SpacingStep values to SpacingToken keys used by the container system.
  */
@@ -28,79 +36,6 @@ export const spacingStepToToken: Record<SpacingStep, string> = {
   10: 'spacing10',
 };
 
-/**
- * Padding styles for all sides using spacing tokens.
- * Each key applies uniform padding to all four sides.
- */
-export const paddingStyles = stylex.create({
-  0: {
-    paddingInlineStart: spacingVars['--spacing-0'],
-    paddingInlineEnd: spacingVars['--spacing-0'],
-    paddingBlockStart: spacingVars['--spacing-0'],
-    paddingBlockEnd: spacingVars['--spacing-0'],
-  },
-  0.5: {
-    paddingInlineStart: spacingVars['--spacing-0-5'],
-    paddingInlineEnd: spacingVars['--spacing-0-5'],
-    paddingBlockStart: spacingVars['--spacing-0-5'],
-    paddingBlockEnd: spacingVars['--spacing-0-5'],
-  },
-  1: {
-    paddingInlineStart: spacingVars['--spacing-1'],
-    paddingInlineEnd: spacingVars['--spacing-1'],
-    paddingBlockStart: spacingVars['--spacing-1'],
-    paddingBlockEnd: spacingVars['--spacing-1'],
-  },
-  1.5: {
-    paddingInlineStart: spacingVars['--spacing-1-5'],
-    paddingInlineEnd: spacingVars['--spacing-1-5'],
-    paddingBlockStart: spacingVars['--spacing-1-5'],
-    paddingBlockEnd: spacingVars['--spacing-1-5'],
-  },
-  2: {
-    paddingInlineStart: spacingVars['--spacing-2'],
-    paddingInlineEnd: spacingVars['--spacing-2'],
-    paddingBlockStart: spacingVars['--spacing-2'],
-    paddingBlockEnd: spacingVars['--spacing-2'],
-  },
-  3: {
-    paddingInlineStart: spacingVars['--spacing-3'],
-    paddingInlineEnd: spacingVars['--spacing-3'],
-    paddingBlockStart: spacingVars['--spacing-3'],
-    paddingBlockEnd: spacingVars['--spacing-3'],
-  },
-  4: {
-    paddingInlineStart: spacingVars['--spacing-4'],
-    paddingInlineEnd: spacingVars['--spacing-4'],
-    paddingBlockStart: spacingVars['--spacing-4'],
-    paddingBlockEnd: spacingVars['--spacing-4'],
-  },
-  5: {
-    paddingInlineStart: spacingVars['--spacing-5'],
-    paddingInlineEnd: spacingVars['--spacing-5'],
-    paddingBlockStart: spacingVars['--spacing-5'],
-    paddingBlockEnd: spacingVars['--spacing-5'],
-  },
-  6: {
-    paddingInlineStart: spacingVars['--spacing-6'],
-    paddingInlineEnd: spacingVars['--spacing-6'],
-    paddingBlockStart: spacingVars['--spacing-6'],
-    paddingBlockEnd: spacingVars['--spacing-6'],
-  },
-  8: {
-    paddingInlineStart: spacingVars['--spacing-8'],
-    paddingInlineEnd: spacingVars['--spacing-8'],
-    paddingBlockStart: spacingVars['--spacing-8'],
-    paddingBlockEnd: spacingVars['--spacing-8'],
-  },
-  10: {
-    paddingInlineStart: spacingVars['--spacing-10'],
-    paddingInlineEnd: spacingVars['--spacing-10'],
-    paddingBlockStart: spacingVars['--spacing-10'],
-    paddingBlockEnd: spacingVars['--spacing-10'],
-  },
-});
-
 /**
  * Container padding inline CSS variable styles for edge compensation.
  * Sets --container-padding-inline-start and --container-padding-inline-end so
@@ -474,62 +409,3 @@ export const sectionPaddingPropagationStyles = stylex.create({
   8: {'--_section-padding-propagated': spacingVars['--spacing-8']},
   10: {'--_section-padding-propagated': spacingVars['--spacing-10']},
 });
-
-/**
- * Padding-variable reset for overlay roots (Dialog, BottomSheet, Drawer,
- * MobileNav, Lightbox, and every layer surface).
- *
- * ## Why an overlay needs this
- *
- * The container padding system talks to descendants through inherited custom
- * properties: a padded container announces its padding, and children read the
- * value either to apply it or to cancel it with a negative margin
- * (`Section`, `Divider`, `Layout`, `Table`).
- *
- * Inheritance follows the DOM, but an overlay leaves its parent's visual box —
- * a fixed/top-layer `<dialog>` is a DOM descendant of the padded page while
- * being nowhere near it on screen. It inherits values describing padding that
- * is not there, and its content compensates against phantom space: a `Section`
- * inside a 640px sheet rendered 672px wide and hung off both edges (#5208).
- *
- * Two families leak, and they need opposite treatments:
- *
- * - `--container-padding-*` -> `0px`. Descendants SUBTRACT these (bleed
- *   margins). The overlay root has no padding of its own to escape, so the
- *   honest answer is zero. Nested containers that do set padding (a Dialog's
- *   content wrapper) re-announce their own values below this point, so
- *   legitimate edge-to-edge bleed inside the overlay is unaffected.
- * - `--layout-padding-*` and `--_section-padding-propagated` -> `initial`.
- *   Descendants ADD these, so zeroing them would strip padding rather than
- *   restore it. `initial` makes each guaranteed-invalid, so readers fall
- *   through their own `var(…, fallback)` chain and land on the theme default —
- *   which is what an overlay at the top of the tree should show.
- *
- * `initial` is also why propagation moved off `--astryx-section-padding`: that
- * name is public theme surface, set at the theme root, and making it invalid
- * here would blank the theme's own section padding inside every overlay.
- *
- * Apply on the overlay's outermost styled element.
- *
- * @example
- * ```
- * <dialog {...stylex.props(styles.dialog, overlayPaddingReset.reset)} />
- * ```
- */
-export const overlayPaddingReset = stylex.create({
-  reset: {
-    // Subtracted by descendants — the overlay root has no padding to escape.
-    '--container-padding-inline-start': '0px',
-    '--container-padding-inline-end': '0px',
-    '--container-padding-block-start': '0px',
-    '--container-padding-block-end': '0px',
-    // Added by descendants — fall through to each reader's own default.
-    '--layout-padding-outer-x': 'initial',
-    '--layout-padding-outer-y': 'initial',
-    '--layout-padding-own-outer-x': 'initial',
-    '--layout-padding-own-outer-y': 'initial',
-    '--layout-padding-inner-x': 'initial',
-    '--layout-padding-inner-y': 'initial',
-    '--_section-padding-propagated': 'initial',
-  },
-});

package/src/Layout/paddingStyles.stylex.ts

@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file paddingStyles.stylex.ts
+ * @input Uses @stylexjs/stylex, spacing from theme
+ * @output paddingStyles: uniform padding on all four sides by SpacingStep
+ * @position Layout utility, re-exported by padding.stylex.ts. Its own module so an
+ *   overlay's eager code (usePopover) imports it without padding.stylex.ts:
+ *   a lazily loaded overlay that uses the container padding styles there then
+ *   keeps them out of the eager chunk it shares with this module.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {spacingVars} from '../theme/tokens.stylex';
+
+/**
+ * Padding styles for all sides using spacing tokens.
+ * Each key applies uniform padding to all four sides.
+ */
+export const paddingStyles = stylex.create({
+  0: {
+    paddingInlineStart: spacingVars['--spacing-0'],
+    paddingInlineEnd: spacingVars['--spacing-0'],
+    paddingBlockStart: spacingVars['--spacing-0'],
+    paddingBlockEnd: spacingVars['--spacing-0'],
+  },
+  0.5: {
+    paddingInlineStart: spacingVars['--spacing-0-5'],
+    paddingInlineEnd: spacingVars['--spacing-0-5'],
+    paddingBlockStart: spacingVars['--spacing-0-5'],
+    paddingBlockEnd: spacingVars['--spacing-0-5'],
+  },
+  1: {
+    paddingInlineStart: spacingVars['--spacing-1'],
+    paddingInlineEnd: spacingVars['--spacing-1'],
+    paddingBlockStart: spacingVars['--spacing-1'],
+    paddingBlockEnd: spacingVars['--spacing-1'],
+  },
+  1.5: {
+    paddingInlineStart: spacingVars['--spacing-1-5'],
+    paddingInlineEnd: spacingVars['--spacing-1-5'],
+    paddingBlockStart: spacingVars['--spacing-1-5'],
+    paddingBlockEnd: spacingVars['--spacing-1-5'],
+  },
+  2: {
+    paddingInlineStart: spacingVars['--spacing-2'],
+    paddingInlineEnd: spacingVars['--spacing-2'],
+    paddingBlockStart: spacingVars['--spacing-2'],
+    paddingBlockEnd: spacingVars['--spacing-2'],
+  },
+  3: {
+    paddingInlineStart: spacingVars['--spacing-3'],
+    paddingInlineEnd: spacingVars['--spacing-3'],
+    paddingBlockStart: spacingVars['--spacing-3'],
+    paddingBlockEnd: spacingVars['--spacing-3'],
+  },
+  4: {
+    paddingInlineStart: spacingVars['--spacing-4'],
+    paddingInlineEnd: spacingVars['--spacing-4'],
+    paddingBlockStart: spacingVars['--spacing-4'],
+    paddingBlockEnd: spacingVars['--spacing-4'],
+  },
+  5: {
+    paddingInlineStart: spacingVars['--spacing-5'],
+    paddingInlineEnd: spacingVars['--spacing-5'],
+    paddingBlockStart: spacingVars['--spacing-5'],
+    paddingBlockEnd: spacingVars['--spacing-5'],
+  },
+  6: {
+    paddingInlineStart: spacingVars['--spacing-6'],
+    paddingInlineEnd: spacingVars['--spacing-6'],
+    paddingBlockStart: spacingVars['--spacing-6'],
+    paddingBlockEnd: spacingVars['--spacing-6'],
+  },
+  8: {
+    paddingInlineStart: spacingVars['--spacing-8'],
+    paddingInlineEnd: spacingVars['--spacing-8'],
+    paddingBlockStart: spacingVars['--spacing-8'],
+    paddingBlockEnd: spacingVars['--spacing-8'],
+  },
+  10: {
+    paddingInlineStart: spacingVars['--spacing-10'],
+    paddingInlineEnd: spacingVars['--spacing-10'],
+    paddingBlockStart: spacingVars['--spacing-10'],
+    paddingBlockEnd: spacingVars['--spacing-10'],
+  },
+});

package/src/Lightbox/Lightbox.tsx

@@ -43,7 +43,7 @@ import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
 import {layerClickBoundary} from '../Layer/layerClickBoundary';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
-import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {overlayPaddingReset} from '../Layout/overlayPaddingReset.stylex';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
 
@@ -55,6 +55,7 @@ import {
 } from '../i18n/useComponentTranslator';
 import english from '../i18n/generated-english/Lightbox/Lightbox.generated';
 import {isRenderable} from '../utils/isRenderable';
+import {prepareFocusReturnOnRemoval} from '../utils/focusReturn';
 
 registerEnglishFallback(english);
 /**
@@ -428,6 +429,7 @@ export function Lightbox({
   // Open/close dialog. The dialog renders only with an item, so a viewer
   // opened before its first item arrives opens when that item does.
   const hasItem = currentItem != null;
+  // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
   useIsomorphicLayoutEffect(() => {
     const dialog = dialogRef.current;
     if (!dialog || !hasItem) {
@@ -445,6 +447,23 @@ export function Lightbox({
     }
   }, [isOpen, hasItem]);
 
+  // A viewer that unmounts while open (rendered only while open, or removed
+  // with the rest of a view) never runs the close branch above. Focus the
+  // removal lost goes back to the opener while the opener is still on the
+  // page.
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog == null) {
+      return;
+    }
+    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
+    return () => {
+      if (dialog.open) {
+        returnFocusOnRemoval(triggerElementRef.current);
+      }
+    };
+  }, [hasItem]);
+
   const handleClose = useCallback(() => {
     onOpenChange(false);
   }, [onOpenChange]);

package/src/Lightbox/useLightbox.doc.mjs

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useLightbox',
+  displayName: 'useLightbox',
+  group: 'Lightbox',
+  keywords: [
+    'lightbox',
+    'gallery',
+    'viewer',
+    'image',
+    'video',
+    'media',
+    'modal',
+    'overlay',
+    'trigger',
+  ],
+  params: [
+    {
+      name: 'options',
+      type: 'UseLightboxOptions',
+      description: 'Configuration options for the lightbox.',
+      required: true,
+    },
+    {
+      name: 'options.media',
+      type: 'LightboxMedia | LightboxMedia[]',
+      description:
+        'Media to display in the lightbox. Pass a single object for one item, or an array for gallery mode.',
+      required: true,
+    },
+    {
+      name: 'options.hasZoom',
+      type: 'boolean',
+      description:
+        'Enable zoom on double-click, or Enter/Space/+/- via keyboard (images only). When zoomed, drag or use arrow keys to pan.',
+      default: 'false',
+      required: false,
+    },
+    {
+      name: 'options.hasAutoPlay',
+      type: 'boolean',
+      description: 'Whether video should autoplay when the lightbox opens.',
+      default: 'false',
+      required: false,
+    },
+  ],
+  returns: [
+    {
+      name: 'open',
+      type: '(index?: number) => void',
+      description:
+        'Open the lightbox, optionally at a specific gallery index (defaults to 0).',
+    },
+    {
+      name: 'close',
+      type: '() => void',
+      description: 'Close the lightbox.',
+    },
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description: 'Whether the lightbox is currently open.',
+    },
+    {
+      name: 'index',
+      type: 'number',
+      description: 'Current gallery index.',
+    },
+    {
+      name: 'element',
+      type: 'ReactNode',
+      description:
+        'Pre-wired Lightbox component element to render in your JSX tree.',
+    },
+    {
+      name: 'triggerProps',
+      type: "{role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void}",
+      description:
+        'Props to spread onto a single trigger element to open the lightbox at index 0 on click, Enter, or Space.',
+    },
+    {
+      name: 'getTriggerProps',
+      type: "(index: number) => {role: 'button', tabIndex: 0, 'aria-haspopup': 'dialog', onClick: () => void, onKeyDown: (e: React.KeyboardEvent) => void}",
+      description:
+        'Returns trigger props to spread onto an element to open the lightbox at a specific gallery index on click, Enter, or Space.',
+    },
+  ],
+  usage: {
+    description:
+      'State management and accessible trigger wiring for Lightbox. Eliminates boilerplate for managing open state and current index. Returns trigger props with button role, tabIndex={0}, aria-haspopup="dialog", and keyboard activation handlers, along with a pre-wired Lightbox element that handles dismissal, next/previous navigation, and focus restoration.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Spread getTriggerProps(index) onto image or thumbnail elements to give them accessible button semantics and keyboard activation.',
+      },
+      {
+        guidance: true,
+        description:
+          'Render lightbox.element once in your component JSX tree alongside the triggers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Manage separate isOpen or index state alongside useLightbox; the hook already tracks both.',
+      },
+      {
+        guidance: false,
+        description:
+          'Add custom click or keydown handlers to open the lightbox when using triggerProps or getTriggerProps.',
+      },
+    ],
+  },
+  relatedComponents: ['Lightbox', 'Grid', 'Thumbnail'],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/Lightbox',
+  category: 'interaction',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'State management and accessible trigger wiring for Lightbox. Eliminates boilerplate for open state and index. Returns trigger props and pre-wired Lightbox element.',
+  paramDescriptions: {
+    options: 'configuration options for the lightbox.',
+    'options.media':
+      'media to display (single item or array for gallery mode).',
+    'options.hasZoom':
+      'enable zoom on double-click or Enter/Space/+/- (images only).',
+    'options.hasAutoPlay': 'whether video should autoplay when opened.',
+  },
+  returnDescriptions: {
+    open: 'open the lightbox, optionally at a specific gallery index.',
+    close: 'close the lightbox.',
+    isOpen: 'whether the lightbox is currently open.',
+    index: 'current gallery index.',
+    element: 'pre-wired Lightbox element to render in JSX tree.',
+    triggerProps:
+      'trigger attributes to spread onto a single trigger element.',
+    getTriggerProps:
+      '(index) => props: returns trigger attributes for opening at index on click, Enter, or Space.',
+  },
+  usage: {
+    description:
+      'State management and trigger wiring for Lightbox. Returns trigger props and pre-wired element.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Spread getTriggerProps(index) onto image elements for accessible button semantics.',
+      },
+      {
+        guidance: true,
+        description:
+          'Render lightbox.element once in JSX alongside the triggers.',
+      },
+      {
+        guidance: false,
+        description:
+          'Manage separate isOpen or index state alongside useLightbox.',
+      },
+    ],
+  },
+};
+

package/src/MobileNav/MobileNav.tsx

@@ -18,9 +18,10 @@
  * without manual z-index management. The browser provides:
  * - Top layer promotion (no z-index needed)
  * - `::backdrop` pseudo-element
- * - Body scroll lock
  * - Focus trapping
  *
+ * The page behind takes `useScrollLock`, the same lock as every other modal.
+ *
  * Escape is owned by the shared dismissal stack (`useLayerDismissal`), so a
  * drawer opened over another layer takes the press and nothing behind it
  * closes. The native `cancel` event still handles the dismissals the browser
@@ -36,7 +37,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/MobileNav/index.ts (exports if types change)
  * - /packages/core/src/Layer/useLayerDismissal.ts (dismissal stack)
- * - /packages/core/src/hooks/scrollbarGutter.ts (shared scroll-lock gutter)
+ * - /packages/core/src/hooks/useScrollLock.ts (the page's scroll lock)
  * - /packages/cli/assets/templates/blocks/components/MobileNav/ (showcase blocks)
  */
 
@@ -62,16 +63,12 @@ import {Button} from '../Button';
 import {Icon} from '../Icon';
 import {Heading} from '../Heading/Heading';
 import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
-import {
-  holdScrollbarGutter,
-  type ScrollbarGutterHold,
-} from '../hooks/scrollbarGutter';
 import {mergeProps, composeEventHandlers} from '../utils';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
 import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
 import {LayerContentBoundary} from '../Layer/layerScopedContext';
 import {layerClickBoundary} from '../Layer/layerClickBoundary';
-import {overlayPaddingReset} from '../Layout/padding.stylex';
+import {overlayPaddingReset} from '../Layout/overlayPaddingReset.stylex';
 import {LayerDepthProvider} from '../Layer/LayerDepthContext';
 import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';
 import {useLayerDismissal} from '../Layer/useLayerDismissal';
@@ -79,6 +76,7 @@ import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useScrollLock} from '../hooks/useScrollLock';
 import {
   registerEnglishFallback,
   useComponentTranslator,
@@ -525,15 +523,10 @@ export function MobileNav({
     setWasOpen(isOpen);
     setIsCloseHeld(!isOpen);
   }
-  const gutterRef = useRef<ScrollbarGutterHold | null>(null);
-
-  // Gives back the gutter held open in place of the hidden scrollbar.
-  const releaseGutter = useCallback(() => {
-    if (gutterRef.current) {
-      gutterRef.current.release();
-      gutterRef.current = null;
-    }
-  }, []);
+  // The same page lock as every other modal. Its effect runs before the
+  // open/close effect below, so it measures the scrollbar gutter before
+  // showModal() can hide the scrollbar.
+  useScrollLock(isOpen);
   // Resolved side — computed from trigger position when side='auto'
   const [resolvedSide, setResolvedSide] = useState<'start' | 'end'>(
     side === 'auto' ? 'end' : side,
@@ -576,10 +569,6 @@ export function MobileNav({
     }
 
     if (isOpen) {
-      // Taken first: every mutation below is one that can hide the scrollbar,
-      // and the gutter has to be measured while it is still there.
-      gutterRef.current ??= holdScrollbarGutter(document.documentElement);
-
       if (!dialog.open) {
         // Capture the opener before showModal() pulls focus into the top
         // layer. Only on the transition into open: a reopen while the delayed
@@ -589,15 +578,7 @@ export function MobileNav({
           document.activeElement as HTMLElement | null;
         dialog.showModal();
       }
-      // Prevent background scrolling and iOS pull-to-refresh.
-      // overflow: clip avoids creating a scroll container (unlike hidden),
-      // so there's no scroll bounce and no need to save/restore scroll position.
-      document.documentElement.style.overflow = 'clip';
-      gutterRef.current.settle();
     } else if (dialog.open) {
-      document.documentElement.style.overflow = '';
-      releaseGutter();
-
       closeTimeoutRef.current = setTimeout(() => {
         closeAndRestoreFocus(dialog, triggerElementRef);
         setIsCloseHeld(false);
@@ -613,10 +594,8 @@ export function MobileNav({
         clearTimeout(closeTimeoutRef.current);
         closeTimeoutRef.current = null;
       }
-      document.documentElement.style.overflow = '';
-      releaseGutter();
     };
-  }, [isOpen, releaseGutter]);
+  }, [isOpen]);
 
   // Close the native dialog on unmount if it's still open. Inside AppShell the
   // drawer is mounted in an <Activity> that switches to mode="hidden" when the

package/src/MultiSelector/MultiSelector.tsx

@@ -76,6 +76,7 @@ import {
 import {useMultiCombobox} from './hooks';
 import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
+import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import {devWarn, warnOnce} from '../utils/devWarning';
 import {useInteractionModalityTracking} from '../utils/interactionModality';
 import {useAnnounce} from '../hooks/useAnnounce';
@@ -2468,13 +2469,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // A disabled trigger stays focusable but, like a natively disabled button,
   // runs no caller event handler other than focus and blur, and a press on it
   // reaches no handler at all (`spec:AST-085` FR2).
-  const callerProps = isDisabled
-    ? Object.fromEntries(
-        Object.entries(rest).filter(
-          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
-        ),
-      )
-    : rest;
+  const callerProps = withholdCallerHandlers(rest, isDisabled);
   const triggerSharedProps: React.HTMLAttributes<HTMLElement> = {
     ...callerProps,
     id: triggerId,

package/src/NumberInput/NumberInput.tsx

@@ -53,6 +53,7 @@ import {VisuallyHidden} from '../VisuallyHidden';
 import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
+import {withholdCallerHandlers} from '../utils/disabledInteraction';
 import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {usePressFeedback} from '../hooks/usePressFeedback';
 import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
@@ -633,13 +634,7 @@ export function NumberInput({
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   // A disabled field keeps its tab stop but, like a natively disabled one,
   // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
-  const fieldProps = isDisabled
-    ? Object.fromEntries(
-        Object.entries(rest).filter(
-          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
-        ),
-      )
-    : rest;
+  const fieldProps = withholdCallerHandlers(rest, isDisabled);
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
     // The container div is not naturally focusable; focusin bubbles up from

package/src/Outline/useOutlineFromDOM.ts

@@ -42,6 +42,8 @@ export function useOutlineFromDOM(
     collectOutlineItems(containerRef.current),
   );
 
+  // Syncs the outline items with the container's DOM through a
+  // MutationObserver.
   useEffect(() => {
     const container = containerRef.current;
     setItems(collectOutlineItems(container));

package/src/Outline/useScrollSpy.ts

@@ -275,6 +275,8 @@ export function useScrollSpy({
     );
   }, [rootRef, scrollContainerRef]);
 
+  // Syncs a scroll listener on the scroll root and a window resize listener
+  // with the items and offset. They choose the active outline item.
   useEffect(() => {
     if (isControlled || typeof window === 'undefined') {
       return;

package/src/OverflowList/OverflowList.tsx

@@ -350,6 +350,8 @@ export function OverflowList({
   const overflowItemsRef = useRef(overflowItems);
   overflowItemsRef.current = overflowItems;
 
+  // Reports the measured overflow to `onOverflowChange`. A ResizeObserver
+  // drives the measurement, so no event handler can report it.
   useIsomorphicLayoutEffect(() => {
     if (
       !onOverflowChange ||

package/src/Overlay/Overlay.tsx

@@ -94,8 +94,13 @@ export function Overlay({
     align,
   });
 
-  // Border radius: mirror first child's radius onto the wrapper.
-  // Only the component needs this — hook consumers have their own radius.
+  // Copies the first child's radius onto the wrapper, so the scrim clips to
+  // the media's rounded corners. This is a layout read of the mounted DOM, and
+  // no user interaction causes it. It runs again when a hidden Activity shows
+  // the wrapper, because the child can change while it is hidden. A ref
+  // callback runs again when a caller's ref changes identity, so it cannot
+  // keep this once-per-show timing. A useOverlay consumer sets the radius on
+  // its own element.
   useIsomorphicLayoutEffect(() => {
     const el = overlay.containerRef.current;
     if (!el) {