@astryxdesign/core 0.7.7 → 0.7.8-canary.36cde5e

package/src/IconButton/IconButton.doc.mjs

@@ -20,7 +20,8 @@ export const docs = {
     {
       name: 'icon',
       type: 'ReactNode',
-      description: 'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
+      description:
+        'Icon element rendered inside the button. An Astryx Icon with no explicit size defaults to sm for sm/md buttons and md for lg buttons.',
       required: true,
       slotElements: [{__element: 'Icon', props: {icon: 'check'}}],
     },
@@ -46,19 +47,22 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
+      description:
+        'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
       name: 'isDisabled',
       type: 'boolean',
-      description: 'Disables the button.',
+      description:
+        'Disables the button. When a tooltip is present, uses aria-disabled instead of native disabled so the button stays focusable.',
       default: 'false',
     },
     {
       name: 'tooltip',
       type: 'string',
-      description: 'Tooltip text shown on hover.',
+      description:
+        "Tooltip text shown on hover and keyboard focus. It also describes the button, unless it repeats the button's accessible name.",
     },
     {
       name: 'onClick',
@@ -70,10 +74,69 @@ export const docs = {
       type: '(e: MouseEvent) => void | Promise<void>',
       description: 'Async click handler with automatic loading state.',
     },
+    {
+      name: 'isInterruptible',
+      type: 'boolean',
+      description:
+        'Keep the button clickable while a clickAction is pending: the spinner and aria-busy still show, but the button is not disabled and the action is not deduped, so a re-click lands and interrupts the in-flight action with a fresh one. Use it for interruptible actions, not fire-once actions (submit, save, pay).',
+      default: 'false',
+    },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the button. Numbers are treated as pixels, strings are used as-is. Without it the button keeps its icon-only aspect, square by default; with it the button takes that width.',
+    },
+    {
+      name: 'type',
+      type: "'button' | 'submit' | 'reset'",
+      description: 'HTML button type attribute.',
+      default: "'button'",
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'HTML name attribute for form submission.',
+    },
+    {
+      name: 'value',
+      type: 'string | number | readonly string[]',
+      description: 'HTML value attribute for form submission.',
+    },
+    {
+      name: 'form',
+      type: 'string',
+      description: 'Associates the button with a form element by ID.',
+    },
+    {
+      name: 'href',
+      type: 'string',
+      description:
+        'When provided, renders the button as a link element (<a> or custom link component). A disabled IconButton still renders a <button>.',
+    },
+    {
+      name: 'as',
+      type: 'ComponentType',
+      description:
+        'Custom link component to use when href is provided (e.g. Next.js Link).',
+    },
+    {
+      name: 'target',
+      type: 'string',
+      description:
+        'HTML target attribute when rendered as a link (e.g. "_blank").',
+    },
+    {
+      name: 'rel',
+      type: 'string',
+      description:
+        'HTML rel attribute when rendered as a link (e.g. "noopener noreferrer").',
+    },
   ],
 
   usage: {
-    description: 'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
+    description:
+      'A button that shows only an icon with no visible text. Use IconButton in toolbars, table rows, and compact UI where space is tight and the icon is universally understood.',
     accessibility: [
       {
         name: 'Essential icon or spinner arc',
@@ -113,26 +176,68 @@ export const docs = {
       },
     ],
     bestPractices: [
-      { guidance: true, description: 'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars and dense areas to reduce visual clutter.' },
-      { guidance: false, description: 'Use IconButton if the action isn\'t obvious from the icon alone; use Button with text.' },
-      { guidance: false, description: 'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make the aria-label specific: a trash icon labeled "Delete conversation" is clearer than just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a tooltip: even a gear icon can mean Settings, Preferences, or Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars and dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if the action isn't obvious from the icon alone; use Button with text.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip the tooltip; label only reaches screen readers, sighted users need the hover hint.',
+      },
     ],
   },
 };
 
 /** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
-  description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+  description:
+    'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
   usage: {
-    description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
+    description:
+      'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
     bestPractices: [
-      { guidance: true, description: 'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.' },
-      { guidance: true, description: 'Add tooltip: even gear icon can mean Settings/Preferences/Configure.' },
-      { guidance: true, description: 'Use ghost in toolbars + dense areas to reduce visual clutter.' },
-      { guidance: false, description: "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead." },
-      { guidance: false, description: 'Skip tooltip: label only reaches screen readers; sighted users need hover hint.' },
+      {
+        guidance: true,
+        description:
+          'Make aria-label specific: trash icon labeled "Delete conversation" > just "Delete" for screen readers.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add tooltip: even gear icon can mean Settings/Preferences/Configure.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use ghost in toolbars + dense areas to reduce visual clutter.',
+      },
+      {
+        guidance: false,
+        description:
+          "Use IconButton if action isn't obvious from icon alone; use Button w/ text instead.",
+      },
+      {
+        guidance: false,
+        description:
+          'Skip tooltip: label only reaches screen readers; sighted users need hover hint.',
+      },
     ],
   },
   propDescriptions: {
@@ -140,11 +245,26 @@ export const docsDense = {
     icon: 'icon element rendered inside button; unsized Astryx Icon defaults to sm for sm/md buttons and md for lg',
     variant: 'visual style variant',
     size: 'size variant',
-    elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
-    isDisabled: 'disables button',
-    tooltip: 'tooltip text shown on hover',
+    elevation:
+      'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
+    isLoading:
+      'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
+    isDisabled: 'disables button; uses aria-disabled when tooltip present',
+    tooltip:
+      'tooltip on hover + keyboard focus; also describes the button unless it repeats the accessible name',
     onClick: 'standard click handler',
     clickAction: 'async click handler w/ automatic loading state',
+    isInterruptible:
+      'keeps button clickable while clickAction pending; a re-click interrupts it. Not for fire-once actions (submit/save/pay)',
+    width:
+      'button width; numbers=pixels, strings=as-is; without it keeps the icon-only aspect (square by default)',
+    type: 'HTML button type; defaults to "button"',
+    name: 'HTML name for form submission',
+    value: 'HTML value for form submission',
+    form: 'associates button with form element by ID',
+    href: 'renders as a link; a disabled IconButton stays a <button>',
+    as: 'custom link component used with href',
+    target: 'HTML target when rendered as a link',
+    rel: 'HTML rel when rendered as a link',
   },
 };

package/src/Item/useSwipeAction.ts

@@ -237,6 +237,8 @@ export function useSwipeAction({
     reducedMotionRef.current = isReducedMotion;
   });
 
+  // Releases the settle timer, the animation frame and the pinch watch on
+  // unmount.
   useEffect(
     () => () => {
       if (settleTimerRef.current != null) {

package/src/Layer/modalOutlet.ts

@@ -188,6 +188,8 @@ export function useModalOutlet(
   const isLatestRef = useRef(isLatest);
   isLatestRef.current = isLatest;
   const suppliedRef = useRef<HTMLDialogElement | null>(null);
+  // Syncs the module registry of modal outlets with this dialog while it is
+  // active. It also follows the dialog's native `close` event.
   useEffect(() => {
     const element = ref.current;
     if (!isActive || element == null) {

package/src/Layer/outsidePress.ts

@@ -96,6 +96,7 @@ export function useOutsidePress(): OutsidePressWatch {
     },
     [],
   );
+  // Stops the outside-press listeners on unmount.
   useEffect(() => stop, [stop]);
   return useMemo(() => ({start, stop}), [start, stop]);
 }

package/src/Layer/useLayer.tsx

@@ -1560,6 +1560,8 @@ function useLayerImplementation(
     forgetDismissalRef.current = forget;
   }, []);
 
+  // Syncs the document's capture-phase gesture tracking with this mount.
+  // Unmount forgets the layer's dismissal.
   useEffect(() => {
     // Install capture-phase gesture tracking before the first interaction.
     currentGesture();

package/src/Layer/useLayerDismissal.ts

@@ -155,6 +155,8 @@ export function useLayerDismissal(
 
   const isRegistered = isActive && isEnabled;
 
+  // Syncs the shared dismissal stack with `isRegistered`. A registered layer
+  // gets Escape and outside presses in stack order.
   useEffect(() => {
     if (!isRegistered) {
       wasRegisteredRef.current = false;

package/src/Layer/usePressPin.ts

@@ -6,8 +6,9 @@
  * @file usePressPin.ts
  * @input A hover layer's trigger, open state, show and hide, and its
  *   `triggerBehavior` and `touchTrigger` options
- * @output usePressPin, the press toggle that pins a hover layer open;
- *   isPressPinTrigger; stopPressPinClick; the LayerTriggerBehavior type
+ * @output usePressPin, the press toggle that pins a hover layer open, and
+ *   the app hold behind useTooltip's show() and hide(); isPressPinTrigger;
+ *   stopPressPinClick; the LayerTriggerBehavior type
  * @position Core-internal: one call per hover layer, useTooltip's. It owns
  *   the layer's touch trigger, so the host makes no second touch-trigger call.
  *
@@ -103,8 +104,18 @@ export interface UsePressPinReturn {
   isHeldOpen: () => boolean;
   /** Wires the trigger element, or unwires it with `null`. */
   attach: (element: HTMLElement | null) => void;
-  /** Drops the pin: Escape, or a hide that came from elsewhere. */
+  /** Drops the pin and the app hold: Escape, or a hide from elsewhere. */
   unpin: () => void;
+  /**
+   * The app's `show()`: shows the layer and holds it open, as a pin does,
+   * until `release`, Escape, a press outside, or focus leaving the trigger
+   * and the layer. A controlled layer reports the request instead.
+   */
+  hold: () => void;
+  /** The app's `hide()`: drops the hold and hides the layer. */
+  release: () => void;
+  /** Whether the app's `show()` holds the layer open now. */
+  isAppHeld: () => boolean;
   /**
    * While pinned, focus moving onto an element outside the trigger and the
    * layer closes it. Returns whether the pin decided. The pin calls it for its
@@ -112,8 +123,9 @@ export interface UsePressPinReturn {
    */
   handleFocusLeave: (event: FocusEvent) => boolean;
   /**
-   * Whether the layer shows pinned on a wired trigger. The host then announces
-   * its rendered text, unless the layer has a `label`.
+   * Whether the layer shows pinned on a wired trigger, or held by the app's
+   * `show()`. The host then announces its rendered text, unless the layer has
+   * a `label`.
    */
   isPinShown: boolean;
   /** The layer's touch trigger (useTouchTriggerInternal), wired to the pin. */
@@ -175,8 +187,19 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     setIsPinnedState(next);
   }, []);
 
+  // The app's show() holds the layer on any trigger, in any mode.
+  const isAppHeldRef = useRef(false);
+  const [isAppHeldState, setIsAppHeldState] = useState(false);
+  const setAppHeld = useCallback((next: boolean) => {
+    isAppHeldRef.current = next;
+    setIsAppHeldState(next);
+  }, []);
+
   // The last offered element lets a `triggerBehavior` change rewire it.
   const triggerRef = useRef<HTMLElement | null>(null);
+  // Every offered trigger, in any mode, so focus leaving ends a pin or an
+  // app hold.
+  const focusTargetRef = useRef<HTMLElement | null>(null);
   const offeredRef = useRef<HTMLElement | null>(null);
   // A primitive: re-attaching the same trigger renders nothing.
   const [offeredKind, setOfferedKind] = useState<'none' | 'other' | 'button'>(
@@ -192,6 +215,13 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   // a pinned layer through the pin, so the pin drops with it.
   const hideFromTouch = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+      if (current.isOpen !== undefined) {
+        current.report(false);
+        return;
+      }
+    }
     if (current.triggerBehavior === 'toggle' && triggerRef.current != null) {
       if (current.isOpen !== undefined) {
         current.report(false);
@@ -202,7 +232,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
     }
     current.hide();
-  }, [setPinned]);
+  }, [setPinned, setAppHeld]);
 
   const {
     isTouchPointerRef,
@@ -233,13 +263,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   const close = useCallback(() => {
     const current = optionsRef.current;
     clearTapOpen();
+    setAppHeld(false);
     if (current.isOpen !== undefined) {
       current.report(false);
       return;
     }
     setPinned(false);
     current.hide();
-  }, [setPinned, clearTapOpen]);
+  }, [setPinned, setAppHeld, clearTapOpen]);
 
   const announceName = useCallback(() => {
     const current = optionsRef.current;
@@ -348,6 +379,9 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
 
   const isHeldOpen = useCallback(() => {
     const current = optionsRef.current;
+    if (isAppHeldRef.current && current.isLayerOpen) {
+      return current.isOpen !== false;
+    }
     if (current.triggerBehavior !== 'toggle' || triggerRef.current == null) {
       return false;
     }
@@ -364,7 +398,7 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         return false;
       }
       const next = event.relatedTarget;
-      const trigger = triggerRef.current;
+      const trigger = focusTargetRef.current;
       // Focus that leaves for no element is a press's to decide. The trigger
       // can sit in another document, so the check uses its own window.
       const view = trigger?.ownerDocument.defaultView;
@@ -387,6 +421,8 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
   );
 
   const unwire = useCallback(() => {
+    focusTargetRef.current?.removeEventListener('focusout', handleFocusLeave);
+    focusTargetRef.current = null;
     const previous = triggerRef.current;
     if (previous == null) {
       return;
@@ -394,7 +430,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     previous.removeEventListener('click', handlePress);
     previous.removeEventListener('keydown', handleKeyDown);
     previous.removeEventListener('keyup', handleKeyUp);
-    previous.removeEventListener('focusout', handleFocusLeave);
     const own = ownStateRef.current;
     if (own != null) {
       restoreAttribute(previous, 'aria-expanded', own.expanded);
@@ -423,10 +458,14 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
       }
       settledRef.current = {element, mode: current.triggerBehavior};
       unwire();
-      if (element == null || current.triggerBehavior !== 'toggle') {
+      if (element == null) {
         return;
       }
-      if (!isPressPinTrigger(element)) {
+      // Its own focus-leave listener, in any mode: `focusTrigger="never"`
+      // attaches none, and an app hold needs it on any trigger.
+      element.addEventListener('focusout', handleFocusLeave);
+      focusTargetRef.current = element;
+      if (current.triggerBehavior !== 'toggle' || !isPressPinTrigger(element)) {
         return;
       }
       element.addEventListener('click', handlePress);
@@ -434,8 +473,6 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
         element.addEventListener('keydown', handleKeyDown);
         element.addEventListener('keyup', handleKeyUp);
       }
-      // Its own focus-leave listener: `focusTrigger="never"` attaches none.
-      element.addEventListener('focusout', handleFocusLeave);
       ownStateRef.current = {
         expanded: element.getAttribute('aria-expanded'),
         controls: element.getAttribute('aria-controls'),
@@ -473,7 +510,31 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     if (isPinnedRef.current) {
       setPinned(false);
     }
-  }, [setPinned]);
+    if (isAppHeldRef.current) {
+      setAppHeld(false);
+    }
+  }, [setPinned, setAppHeld]);
+
+  const hold = useCallback(() => {
+    const current = optionsRef.current;
+    if (!current.isEnabled) {
+      return;
+    }
+    setAppHeld(true);
+    armOutsideDismiss();
+    announceName();
+    if (current.isOpen !== undefined) {
+      current.report(true);
+      return;
+    }
+    current.show();
+  }, [setAppHeld, armOutsideDismiss, announceName]);
+
+  const release = useCallback(() => {
+    close();
+  }, [close]);
+
+  const isAppHeld = useCallback(() => isAppHeldRef.current, []);
 
   // Each path that hides a pinned layer drops the pin itself, so a layer that
   // does not show is never reported expanded.
@@ -490,13 +551,18 @@ export function usePressPin(options: UsePressPinOptions): UsePressPinReturn {
     writeAttribute(trigger, 'aria-controls', isLayerOpen ? layerId : null);
   });
 
-  const isPinShown = isToggleMode && isWired && isExpanded;
+  const isPinShown =
+    (isToggleMode && isWired && isExpanded) ||
+    (isAppHeldState && isLayerOpen && isOpen !== false);
 
   return {
     isToggleTrigger,
     isHeldOpen,
     attach,
     unpin,
+    hold,
+    release,
+    isAppHeld,
     handleFocusLeave,
     isPinShown,
     touch: {

package/src/Layer/useTouchTrigger.ts

@@ -436,7 +436,9 @@ export function useTouchTriggerInternal(
     }
   }, [triggerRef, disarmOutsideDismiss]);
 
+  // Releases the outside-dismiss listener on unmount.
   useEffect(() => disarmOutsideDismiss, [disarmOutsideDismiss]);
+  // Releases a pending tap on unmount.
   useEffect(() => () => forgetPendingTapRef.current?.(), []);
 
   const isTouchInteraction = useCallback(

package/src/Lightbox/Lightbox.tsx

@@ -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/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,10 +63,6 @@ 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';
@@ -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/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 ||