@astryxdesign/core 0.4.5 → 0.4.6-canary.cea9ecd

package/src/hooks/scrollbarGutter.ts

@@ -0,0 +1,121 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollbarGutter.ts
+ * @input The element a scroll lock pins, plus live layout measurements
+ * @output Exports holdScrollbarGutter and the ScrollbarGutterHold it returns
+ * @position Internal hook utility; used by useScrollLock and MobileNav so that
+ *   locking background scroll does not resize the layout viewport.
+ *
+ * Locking scroll hides the document's scrollbar. Where that scrollbar is a
+ * classic (space-taking) one — Windows/Linux desktop, and macOS set to
+ * "Always" show scroll bars — hiding it widens the layout viewport by the
+ * scrollbar's width and the whole page jumps sideways behind the overlay.
+ *
+ * The fix is `scrollbar-gutter: stable`, which holds the gutter open once the
+ * scrollbar goes away. Being a real layout change it holds `position: fixed`
+ * chrome (sticky headers, toast viewports) as well as in-flow content, which
+ * padding fundamentally cannot: fixed elements resolve against the viewport,
+ * not against the padded element.
+ *
+ * Padding is kept only as a fallback for engines without `scrollbar-gutter`
+ * (Safari shipped it in 18.2), and it is applied by measuring whether the
+ * element actually moved rather than by assuming it did.
+ */
+
+const NOOP: ScrollbarGutterHold = {
+  settle() {},
+  release() {},
+};
+
+export interface ScrollbarGutterHold {
+  /**
+   * Call once the lock's own styles are applied: measures whether the element
+   * grew anyway and, only then, pads the difference away.
+   */
+  settle(): void;
+  /** Call on unlock: restores everything this hold changed. */
+  release(): void;
+}
+
+/**
+ * Keeps `element`'s content box the width it is right now, across a scroll
+ * lock that is about to hide the document's scrollbar.
+ *
+ * Call it *before* applying the lock's styles, then {@link
+ * ScrollbarGutterHold.settle} immediately after, and {@link
+ * ScrollbarGutterHold.release} on unlock:
+ *
+ * ```
+ * const hold = holdScrollbarGutter(document.body);
+ * body.style.position = 'fixed';
+ * hold.settle();
+ * ```
+ *
+ * Overlay scrollbars (mobile, default macOS) take no layout space, so there is
+ * nothing to hold and nothing is touched.
+ */
+export function holdScrollbarGutter(element: HTMLElement): ScrollbarGutterHold {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return NOOP;
+  }
+
+  const root = document.documentElement;
+  const viewportWidth = root.clientWidth;
+
+  // 0 means "no layout to measure" (jsdom, and any non-visual environment),
+  // not "the scrollbar is as wide as the window".
+  if (viewportWidth === 0) {
+    return NOOP;
+  }
+
+  const previousGutter = root.style.scrollbarGutter;
+  const previousPadding = element.style.paddingRight;
+  const widthBefore = element.getBoundingClientRect().width;
+
+  let heldGutter = false;
+  let padded = false;
+  let settled = false;
+
+  // Only when a space-taking scrollbar is actually there. Holding the gutter
+  // open on a page that never had one would carve out 15px that was never
+  // reserved — the same shift, in the other direction.
+  if (window.innerWidth > viewportWidth) {
+    root.style.scrollbarGutter = 'stable';
+    heldGutter = true;
+  }
+
+  return {
+    settle() {
+      if (settled) {
+        return;
+      }
+      settled = true;
+
+      // What the lock actually did to this element, rather than what we
+      // assumed it would do. 0 on any engine where the gutter held — and on a
+      // page that already sets `scrollbar-gutter: stable` itself, where the
+      // scrollbar was never taking the space back.
+      const grew = element.getBoundingClientRect().width - widthBefore;
+      if (grew <= 0) {
+        return;
+      }
+
+      const existing =
+        Number.parseFloat(window.getComputedStyle(element).paddingRight) || 0;
+      element.style.paddingRight = `${existing + grew}px`;
+      padded = true;
+    },
+
+    release() {
+      if (padded) {
+        element.style.paddingRight = previousPadding;
+        padded = false;
+      }
+      if (heldGutter) {
+        root.style.scrollbarGutter = previousGutter;
+        heldGutter = false;
+      }
+    },
+  };
+}

package/src/hooks/useAutoMediaMode.test.ts

@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {pickMediaMode} from './useAutoMediaMode';
+import {parseColor} from '../utils/color';
+
+const rgb = (value: string) => {
+  const parsed = parseColor(value);
+  if (parsed === null) {
+    throw new Error(`bad test color ${value}`);
+  }
+  return parsed;
+};
+
+const onDark = rgb('#FFFFFF');
+const onLight = rgb('#171717');
+// The theme's --color-text-primary, per color mode.
+const ambientLight = rgb('#171717');
+const ambientDark = rgb('#FAFAFA');
+
+describe('pickMediaMode', () => {
+  it('picks dark for a dark surface under a light page', () => {
+    expect(pickMediaMode(rgb('#0A1317'), ambientLight, onDark, onLight)).toBe(
+      'dark',
+    );
+  });
+
+  it('picks light for a light surface under a dark page', () => {
+    expect(pickMediaMode(rgb('#FFFFFF'), ambientDark, onDark, onLight)).toBe(
+      'light',
+    );
+  });
+
+  // The bug this exists for: a theme whose "inverted" background is a pale
+  // grey, where a hardcoded mode="dark" paints white text at 1.25:1.
+  it('answers off for a surface a theme merely calls inverted', () => {
+    // Ambient already reads at 14.36; no media side improves on it, so a
+    // media context would churn accent and overlays for nothing.
+    expect(pickMediaMode(rgb('#E4E6EB'), ambientLight, onDark, onLight)).toBe(
+      'off',
+    );
+  });
+
+  it('answers off for a chromatic surface its ambient text already reads on', () => {
+    // The dark-mode error toast: ambient 4.50 clears the bar. Verified in
+    // Chromium that this renders identically to mode="dark" — a dark page
+    // already resolves those tokens to what the media context would install.
+    expect(pickMediaMode(rgb('#E3193B'), ambientDark, onDark, onLight)).toBe(
+      'off',
+    );
+  });
+
+  it('picks dark for a saturated surface under a light page', () => {
+    // The light-mode error toast: a deeper red, where the page's near-black
+    // text only manages 2.35 and the surface genuinely needs inverting.
+    expect(pickMediaMode(rgb('#AA071E'), ambientLight, onDark, onLight)).toBe(
+      'dark',
+    );
+  });
+
+  it('respects a theme that overrides its on-colors', () => {
+    // The decision follows the theme's own values, not an assumption that
+    // on-dark is white.
+    expect(
+      pickMediaMode(
+        rgb('#0A1317'),
+        ambientLight,
+        rgb('#101010'),
+        rgb('#F0F0F0'),
+      ),
+    ).toBe('light');
+  });
+
+  it('composites a translucent on-color before judging it', () => {
+    // Ambient (1.44) does not read, so a side must be chosen. Raw white would
+    // score 4.54 here and win; composited at 10% alpha it is 1.21 and loses.
+    expect(
+      pickMediaMode(
+        rgb('#767676'),
+        rgb('#8A8A8A'),
+        rgb('rgba(255,255,255,0.10)'),
+        rgb('#171717'),
+      ),
+    ).toBe('light');
+  });
+
+  it('picks a side when the ambient color cannot be read at all', () => {
+    // Unparseable token: it cannot conclude "no media wanted", so it inverts.
+    expect(pickMediaMode(rgb('#0A1317'), null, onDark, onLight)).toBe('dark');
+  });
+
+  it('treats the bar as a floor, not a target', () => {
+    // 3.45:1 is poor for body text but clears the bar: the theme is rendering
+    // this successfully and a media context would not make it more legible.
+    // Deliberately NOT corrected — this is not a WCAG enforcer.
+    expect(pickMediaMode(rgb('#8A8A8A'), rgb('#FFFFFF'), onDark, onLight)).toBe(
+      'off',
+    );
+  });
+
+  it('gives up when an on-color is unreadable', () => {
+    expect(
+      pickMediaMode(rgb('#0A1317'), ambientLight, null, onLight),
+    ).toBeNull();
+    expect(
+      pickMediaMode(rgb('#0A1317'), ambientLight, onDark, null),
+    ).toBeNull();
+  });
+});

package/src/hooks/useAutoMediaMode.ts

@@ -0,0 +1,233 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useAutoMediaMode.ts
+ * @input Ref to the element whose backdrop should be measured
+ * @output 'dark' | 'light' | null (not yet measurable)
+ * @position INTERNAL — powers `MediaTheme mode="auto"`. Not exported from the
+ *   package: MediaTheme is the supported surface for this behavior.
+ *   Sibling to useImageMode, which answers the same question for images.
+ *
+ * Picks the media context a surface wants by measuring what the browser
+ * actually painted, rather than trusting a token's name.
+ *
+ * The bug it exists for: `--color-background-inverted` is not required to be
+ * inverted. A theme can define it as a pale grey, and a hardcoded
+ * `mode="dark"` then paints white text on it at 1.25:1. Because the surface
+ * colour is a runtime value and the mode is a compile-time guess, no amount
+ * of care in the component can catch that.
+ *
+ * The answer can also be `'off'`: when the surface's own ambient text already
+ * reads on it, the surface is not effectively inverted and does not want a
+ * media context. Verified in Chromium that this loses nothing on a surface
+ * that is chromatic but legible — the dark-mode error toast renders
+ * identically either way, because a dark page already resolves those tokens
+ * to the values the media context would install.
+ *
+ * @example
+ * ```
+ * // Inside MediaTheme; see its `mode="auto"`.
+ * const detected = useAutoMediaMode(ref, mode === 'auto');
+ * ```
+ */
+
+import {useRef, useState} from 'react';
+import type {RefObject} from 'react';
+import type {RGBA} from '../utils/color';
+import {parseColor, formatColor} from '../utils/color';
+import {contrastRatio, compositeOver} from '../theme/contrast';
+import {useTheme} from '../theme/useTheme';
+import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
+
+/** A surface luminance context, or `"off"` when no media context is wanted. */
+export type DetectedMediaMode = 'dark' | 'light' | 'off';
+
+/**
+ * Resolve token references to the colors they actually paint, by reading them
+ * back off a hidden probe.
+ *
+ * A custom property cannot simply be read: `getPropertyValue` returns the
+ * token's *specified* text, and Astryx tokens are `light-dark(a, b)` pairs
+ * that resolve only once used in a real property. The probe assigns each
+ * token to `color` and reads the computed value back, which the browser has
+ * resolved against the host's own color-scheme and any overrides.
+ *
+ * `display: none` keeps the probe out of layout — computed color still
+ * resolves — so this costs a style recalc and no reflow.
+ */
+function resolvePaintedColors(
+  host: HTMLElement,
+  tokens: ReadonlyArray<string>,
+): (RGBA | null)[] {
+  const probe = document.createElement('span');
+  probe.style.display = 'none';
+  host.appendChild(probe);
+  try {
+    return tokens.map(token => {
+      probe.style.color = `var(${token})`;
+      return parseColor(getComputedStyle(probe).color);
+    });
+  } finally {
+    probe.remove();
+  }
+}
+
+/**
+ * The color actually behind an element: its own background if opaque,
+ * otherwise its translucent layers composited down onto the first opaque
+ * ancestor.
+ *
+ * Returns null when the paint is not knowable from CSS:
+ * - a `background-image` (gradient, photo, video poster) anywhere in the
+ *   chain — its pixels need sampling, which is `useImageMode`'s job and
+ *   needs CORS access the stylesheet cannot give us;
+ * - no opaque layer at all, where the paint is the browser canvas.
+ */
+function resolveBackdrop(element: HTMLElement): RGBA | null {
+  const layers: RGBA[] = [];
+  let node: HTMLElement | null = element;
+
+  while (node !== null) {
+    const style = getComputedStyle(node);
+    if (style.backgroundImage !== 'none') {
+      return null;
+    }
+    const color = parseColor(style.backgroundColor);
+    if (color !== null && color.a > 0) {
+      layers.push(color);
+      if (color.a >= 1) {
+        break;
+      }
+    }
+    node = node.parentElement;
+  }
+
+  const base = layers.pop();
+  if (base === undefined || base.a < 1) {
+    return null;
+  }
+  // layers is now top-first; composite downward so the topmost lands last.
+  return layers.reduceRight(
+    (backdrop, layer) => compositeOver(layer, backdrop),
+    base,
+  );
+}
+
+/**
+ * Contrast at which a surface's own ambient text counts as reading well
+ * enough that no media context is wanted.
+ *
+ * WCAG's non-text / large-text line. It is deliberately low: this decides
+ * whether a surface is *effectively inverted*, not whether its text meets a
+ * standard. A pairing that clears 3:1 is one the theme is rendering
+ * successfully, and swapping in a media context there changes accent,
+ * overlays and borders for no legibility gain.
+ */
+const AMBIENT_READS_AT = 3;
+
+/**
+ * Which media context a surface wants: `'off'` when its ambient text already
+ * reads on the surface, otherwise whichever on-color reads better. Pure — the
+ * DOM read is the caller's. Ties between the two sides go to dark, matching
+ * the convention that an inverted surface is usually the dark one.
+ *
+ * The `'off'` answer is the point of measuring at all. A surface that a theme
+ * calls inverted but paints pale does not want an inverted context; its own
+ * text is already correct for it, and forcing one is how white-on-pale-grey
+ * happens.
+ */
+export function pickMediaMode(
+  background: RGBA,
+  ambient: RGBA | null,
+  onDark: RGBA | null,
+  onLight: RGBA | null,
+): DetectedMediaMode | null {
+  if (onDark === null || onLight === null) {
+    return null;
+  }
+
+  if (
+    ambient !== null &&
+    contrastRatio(ambient, background) >= AMBIENT_READS_AT
+  ) {
+    return 'off';
+  }
+
+  return contrastRatio(onDark, background) >= contrastRatio(onLight, background)
+    ? 'dark'
+    : 'light';
+}
+
+/**
+ * Detect the media context for the element's surroundings.
+ *
+ * Measures `ref`'s PARENT, never `ref` itself: MediaTheme sets its media
+ * attribute on its own element, so measuring that would feed the decision
+ * back into its own input and let it oscillate. The parent owns the
+ * background and sits outside the media context, so both inputs stay
+ * independent of the result.
+ *
+ * Returns null until a measurement succeeds — on the server, before the
+ * layout effect runs, and whenever the backdrop is not knowable from CSS.
+ * The caller renders its fallback for those.
+ */
+export function useAutoMediaMode(
+  ref: RefObject<HTMLElement | null>,
+  isEnabled: boolean,
+): DetectedMediaMode | null {
+  const [detected, setDetected] = useState<DetectedMediaMode | null>(null);
+  // `tokens` is a stable reference unless the theme or color mode changes.
+  const {tokens} = useTheme();
+  const lastRef = useRef<{background: string; tokens: unknown} | null>(null);
+
+  // Deliberately no dependency array. A surface's color is a painted value:
+  // it changes when a prop on some ancestor changes, and no dependency this
+  // hook could name would catch that (an earlier revision took a `watch`
+  // array and silently went stale whenever a caller forgot an entry). So the
+  // measurement re-runs whenever anything re-renders, and skips its own
+  // expensive half when nothing moved — see the early return below.
+  useIsomorphicLayoutEffect(() => {
+    const surface = ref.current?.parentElement ?? null;
+    if (!isEnabled || surface === null) {
+      return;
+    }
+
+    const background = resolveBackdrop(surface);
+    if (background === null) {
+      return;
+    }
+
+    // The backdrop walk above is a couple of getComputedStyle reads; the
+    // probe below appends a node and forces another style resolution. Skip
+    // it when neither the painted backdrop nor the theme has moved, which is
+    // the overwhelmingly common render.
+    const backgroundKey = formatColor(background);
+    const last = lastRef.current;
+    if (
+      last !== null &&
+      last.background === backgroundKey &&
+      last.tokens === tokens
+    ) {
+      return;
+    }
+    lastRef.current = {background: backgroundKey, tokens};
+
+    const [ambient, onDark, onLight] = resolvePaintedColors(surface, [
+      '--color-text-primary',
+      '--color-on-dark',
+      '--color-on-light',
+    ]);
+    const next = pickMediaMode(background, ambient, onDark, onLight);
+    if (next === null) {
+      return;
+    }
+
+    // eslint-disable-next-line @eslint-react/set-state-in-effect -- the mode is derived from painted DOM colors
+    setDetected(current => (current === next ? current : next));
+  });
+
+  // A disabled hook must not answer with a value measured while it was on.
+  return isEnabled ? detected : null;
+}

package/src/hooks/useInputStatusIcon.tsx

@@ -81,7 +81,10 @@ const styles = stylex.create({
     border: 'none',
     background: 'none',
     color: 'inherit',
-    cursor: 'pointer',
+    cursor: {
+      default: 'pointer',
+      ':is(:disabled,[aria-disabled="true"])': 'default',
+    },
     // Own the interactivity so the tooltip opens on hover even when the field
     // renders this affordance inside a non-interactive trailing slot. TextArea
     // positions its end slot as an absolute overlay with `pointer-events: none`

package/src/hooks/useListFocus.doc.mjs

@@ -36,7 +36,7 @@ export const docs = {
     {
       name: 'options.onEscape',
       type: '() => void',
-      description: 'Callback when Escape key is pressed (e.g., close menu).',
+      description: 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',
       required: false,
     },
     {
@@ -144,7 +144,7 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
-    'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
+    'options.onEscape': 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
     'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',

package/src/hooks/useListFocus.test.tsx

@@ -3,14 +3,14 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping, navigation, and
- *   RTL auto-detection
+ * @output Unit tests for useListFocus disabled-item skipping, navigation,
+ *   Escape consumption, and RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
@@ -525,3 +525,65 @@ describe('useListFocus boundarySelector (nested lists)', () => {
     expect(innerProbe).toHaveAttribute('data-owns', 'false');
   });
 });
+
+// A list inside a host that dismisses on Escape. The host's guard mirrors
+// `useFocusTrap`: it acts only on a key no inner handler has consumed.
+function EscapeHost({
+  onEscape,
+  onHostEscape,
+}: {
+  onEscape?: () => void;
+  onHostEscape: () => void;
+}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({onEscape});
+  return (
+    <div
+      data-testid="host"
+      onKeyDown={e => {
+        if (e.key === 'Escape' && !e.defaultPrevented) {
+          onHostEscape();
+        }
+      }}>
+      <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+        <div role="menuitem" tabIndex={-1} data-testid="One">
+          One
+        </div>
+        <div role="menuitem" tabIndex={-1} data-testid="Two">
+          Two
+        </div>
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus Escape', () => {
+  it('leaves Escape to the host when no onEscape is supplied', () => {
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onHostEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('consumes Escape and runs onEscape when one is supplied', () => {
+    const onEscape = vi.fn();
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onEscape={onEscape} onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onHostEscape).not.toHaveBeenCalled();
+  });
+
+  it('still consumes arrow keys with no onEscape (page-scroll suppression)', () => {
+    render(<EscapeHost onHostEscape={() => {}} />);
+    screen.getByTestId('One').focus();
+
+    // fireEvent returns false when a handler cancelled the event.
+    const wasCancelled = !fireEvent.keyDown(screen.getByRole('menu'), {
+      key: 'ArrowDown',
+    });
+    expect(wasCancelled).toBe(true);
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});

package/src/hooks/useListFocus.ts

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useListFocus.doc.mjs
+ * - /packages/core/src/hooks/useListFocus.test.tsx
  */
 
 import {useCallback, useRef} from 'react';
@@ -64,7 +66,9 @@ export interface UseListFocusOptions {
   wrap?: boolean;
 
   /**
-   * Callback when Escape key is pressed.
+   * Callback when Escape key is pressed. Supplying it also makes the list
+   * consume the key (`preventDefault`); without it Escape passes through to
+   * the surrounding layer.
    */
   onEscape?: () => void;
 
@@ -277,7 +281,8 @@ function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
@@ -557,12 +562,15 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      // Escape is handled regardless of orientation. Preserve the historical
-      // behavior of always consuming Escape here (preventDefault) so consumers
-      // that relied on it are unaffected.
+      // Escape is handled regardless of orientation, but only *consumed* when
+      // a handler asked for it: a list with no dismissal to perform must leave
+      // the key to whatever host layer does have one, and those defer to
+      // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
       if (e.key === 'Escape') {
-        e.preventDefault();
-        onEscape?.();
+        if (onEscape) {
+          e.preventDefault();
+          onEscape();
+        }
         return;
       }
 

package/src/hooks/useScrollLock.doc.mjs

@@ -4,7 +4,7 @@
 export const docs = {
   name: 'useScrollLock',
   displayName: 'useScrollLock',
-  keywords: ['scroll', 'lock', 'modal', 'dialog', 'body', 'prevent', 'background', 'ios', 'safari', 'fixed'],
+  keywords: ['scroll', 'lock', 'modal', 'dialog', 'body', 'prevent', 'background', 'ios', 'safari', 'fixed', 'scrollbar', 'gutter', 'layout shift', 'reflow'],
   params: [
     {
       name: 'isLocked',
@@ -16,7 +16,7 @@ export const docs = {
   returns: [],
   usage: {
     description:
-      'Locks body scroll when active by pinning the body with position: fixed. This prevents background scrolling behind modals and dialogs, which is necessary for iOS Safari where overscroll-behavior: contain does not work. Restores the original scroll position when unlocked.',
+      'Locks body scroll when active by pinning the body with position: fixed. This prevents background scrolling behind modals and dialogs, which is necessary for iOS Safari where overscroll-behavior: contain does not work. Restores the original scroll position when unlocked. Pinning hides the document scrollbar, so where that scrollbar takes layout space (desktop) the hook holds its gutter open with scrollbar-gutter: stable for the duration of the lock. The page, including any position: fixed chrome, does not shift sideways.',
     bestPractices: [
       { guidance: true, description: 'Use when opening full-screen modals or dialogs to prevent background content from scrolling.' },
       { guidance: true, description: 'Pass the same boolean that controls dialog visibility (e.g., isOpen) as the isLocked parameter.' },
@@ -32,13 +32,13 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',
+    'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked. Holds the hidden scrollbar\'s gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.',
   paramDescriptions: {
     isLocked: 'whether body scroll should be locked.',
   },
   usage: {
     description:
-      'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked.',
+      'Locks body scroll when active by pinning body w/ position: fixed. Prevents background scrolling behind modals + dialogs, necessary for iOS Safari where overscroll-behavior: contain does not work. Restores original scroll position when unlocked. Holds the hidden scrollbar\'s gutter open (scrollbar-gutter: stable) so the page (incl. position: fixed chrome) does not shift sideways.',
     bestPractices: [
       { guidance: true, description: 'Use when opening full-screen modals / dialogs to prevent background content from scrolling.' },
       { guidance: true, description: 'Pass same boolean that controls dialog visibility (e.g. isOpen) as isLocked parameter.' },