@astryxdesign/core 0.4.4 → 0.4.5-canary.1fdecb1

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -23,6 +23,7 @@ import {spacingVars, colorVars, radiusVars} from '../../../theme/tokens.stylex';
 import {Icon} from '../../../Icon';
 import {resolveContextActions} from '../../tableContextMenu';
 import {useTranslator} from '../../../i18n';
+import {rtlStyles} from '../../../utils';
 import type {
   TablePlugin,
   TableColumn,
@@ -92,8 +93,20 @@ const expansionStyles = stylex.create({
       color: colorVars['--color-icon-primary'],
     },
   },
+  // The RTL mirror is folded into each state's transform rather than living
+  // on a parent span, matching TreeListItem's chevron (both are `transform`,
+  // so on one element the later value would win).
   chevronExpanded: {
-    transform: 'rotate(90deg)',
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
+  },
+  chevronCollapsed: {
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
   },
   expandedRow: {
     backgroundColor: colorVars['--color-background-muted'],
@@ -121,7 +134,9 @@ function ExpansionChevron({
       type="button"
       {...stylex.props(
         expansionStyles.chevronButton,
-        isExpanded && expansionStyles.chevronExpanded,
+        isExpanded
+          ? expansionStyles.chevronExpanded
+          : expansionStyles.chevronCollapsed,
       )}
       onClick={e => {
         e.stopPropagation();
@@ -249,6 +264,9 @@ export function useTableRowExpansion<T extends Record<string, unknown>>(
                   icon={isExpanded ? 'chevronDown' : 'chevronRight'}
                   size="xsm"
                   aria-hidden
+                  // chevronDown needs no mirroring; chevronRight (collapsed,
+                  // pointing toward the reveal direction) does.
+                  xstyle={!isExpanded && rtlStyles.mirror}
                 />
               ),
               onSelect: () => onToggle(key),

package/src/TextArea/TextArea.tsx

@@ -52,6 +52,7 @@ import type {SizeValue} from '../utils/types';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useSize} from '../SizeContext/SizeContext';
 import {themeProps} from '../utils/themeProps';
 import {characterCount} from '../utils/characters';
@@ -394,6 +395,7 @@ export function TextArea({
 }: TextAreaProps) {
   const size = useSize(sizeProp, 'md');
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const announce = useAnnounce();
   const id = useId();
   const descriptionID = useId();
@@ -598,7 +600,7 @@ export function TextArea({
           autoFocus={hasAutoFocus}
           data-autofocus={hasAutoFocus || undefined}
           aria-describedby={ariaDescribedBy}
-          aria-required={isRequired && !isOptional ? 'true' : undefined}
+          aria-required={isEffectivelyRequired ? 'true' : undefined}
           aria-invalid={
             status?.type === 'error' ||
             (maxLength != null && valueLength > maxLength)

package/src/TextInput/TextInput.tsx

@@ -101,6 +101,7 @@ import {mergeProps, mergeRefs} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
@@ -301,6 +302,7 @@ export function TextInput({
   ...rest
 }: TextInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const size = useSize(sizeProp, 'md');
 
   const id = useId();
@@ -445,7 +447,7 @@ export function TextInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         aria-busy={isBusy || undefined}
         aria-labelledby={ariaLabelledBy}

package/src/TimeInput/TimeInput.tsx

@@ -67,6 +67,7 @@ import {useSize} from '../SizeContext/SizeContext';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {groupStyles} from '../InputGroup/groupStyles';
 import {useTooltip} from '../Tooltip';
@@ -347,6 +348,7 @@ export function TimeInput({
   ref,
 }: TimeInputProps) {
   const t = useTranslator();
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const placeholder =
     placeholderFromProps ?? t('@astryx.timeInput.placeholder');
   const size = useSize(sizeProp, 'md');
@@ -664,7 +666,7 @@ export function TimeInput({
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={ariaDescribedBy}
-        aria-required={isRequired === true ? 'true' : undefined}
+        aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={
           status?.type === 'error' || !isInputValid ? 'true' : undefined
         }

package/src/hooks/scrollbarGutter.test.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file scrollbarGutter.test.ts
+ * @input Uses vitest and a stubbed viewport + element box (jsdom does no layout)
+ * @output Unit tests for holdScrollbarGutter
+ * @position Testing; validates scrollbarGutter.ts implementation
+ *
+ * SYNC: When scrollbarGutter.ts changes, update tests to match new behavior
+ */
+
+import {afterEach, describe, expect, it} from 'vitest';
+import {holdScrollbarGutter} from './scrollbarGutter';
+
+/**
+ * jsdom does no layout, so both halves of the measurement are stubbed: the
+ * viewport (`innerWidth` vs `documentElement.clientWidth`) and the element's
+ * own box, which `widths` reads from and a test flips to simulate the lock
+ * widening it.
+ */
+function stub({
+  innerWidth,
+  clientWidth,
+  widths,
+}: {
+  innerWidth: number;
+  clientWidth: number;
+  widths?: () => number;
+}) {
+  Object.defineProperty(window, 'innerWidth', {
+    value: innerWidth,
+    configurable: true,
+    writable: true,
+  });
+  Object.defineProperty(document.documentElement, 'clientWidth', {
+    value: clientWidth,
+    configurable: true,
+  });
+  if (widths) {
+    document.body.getBoundingClientRect = () => ({width: widths()}) as DOMRect;
+  }
+}
+
+const rootGutter = () => document.documentElement.style.scrollbarGutter;
+
+describe('holdScrollbarGutter', () => {
+  afterEach(() => {
+    document.body.style.cssText = '';
+    document.documentElement.style.cssText = '';
+    // @ts-expect-error -- drop the stubs so jsdom's own values come back
+    delete document.documentElement.clientWidth;
+    // @ts-expect-error -- restore the prototype's implementation
+    delete document.body.getBoundingClientRect;
+  });
+
+  it('holds the gutter open when a space-taking scrollbar is about to be hidden', () => {
+    // A 1024px window over a 1009px layout viewport = a 15px classic scrollbar.
+    stub({innerWidth: 1024, clientWidth: 1009});
+
+    const hold = holdScrollbarGutter(document.body);
+
+    expect(rootGutter()).toBe('stable');
+
+    hold.settle();
+    hold.release();
+
+    expect(rootGutter()).toBe('');
+  });
+
+  it('leaves an overlay scrollbar alone — there is no gutter to hold', () => {
+    stub({innerWidth: 1024, clientWidth: 1024});
+
+    const hold = holdScrollbarGutter(document.body);
+    hold.settle();
+
+    expect(rootGutter()).toBe('');
+    expect(document.body.style.paddingRight).toBe('');
+
+    hold.release();
+  });
+
+  it('does not pad when holding the gutter kept the element still', () => {
+    stub({innerWidth: 1024, clientWidth: 1009, widths: () => 1009});
+
+    const hold = holdScrollbarGutter(document.body);
+    hold.settle();
+
+    expect(rootGutter()).toBe('stable');
+    expect(document.body.style.paddingRight).toBe('');
+
+    hold.release();
+  });
+
+  it('falls back to padding when the element grew anyway', () => {
+    // What an engine without scrollbar-gutter support does: the gutter request
+    // is ignored, the scrollbar goes away, and the element widens by 15px.
+    let width = 1009;
+    stub({innerWidth: 1024, clientWidth: 1009, widths: () => width});
+
+    const hold = holdScrollbarGutter(document.body);
+    width = 1024;
+    hold.settle();
+
+    expect(document.body.style.paddingRight).toBe('15px');
+
+    hold.release();
+
+    expect(document.body.style.paddingRight).toBe('');
+  });
+
+  it("adds to the page's own padding instead of replacing it", () => {
+    let width = 1009;
+    stub({innerWidth: 1024, clientWidth: 1009, widths: () => width});
+    document.body.style.paddingRight = '24px';
+
+    const hold = holdScrollbarGutter(document.body);
+    width = 1024;
+    hold.settle();
+
+    expect(document.body.style.paddingRight).toBe('39px');
+
+    hold.release();
+
+    expect(document.body.style.paddingRight).toBe('24px');
+  });
+
+  it('restores the page\u2019s own scrollbar-gutter rather than clearing it', () => {
+    stub({innerWidth: 1024, clientWidth: 1009});
+    document.documentElement.style.scrollbarGutter = 'stable both-edges';
+
+    const hold = holdScrollbarGutter(document.body);
+
+    expect(rootGutter()).toBe('stable');
+
+    hold.settle();
+    hold.release();
+
+    expect(rootGutter()).toBe('stable both-edges');
+  });
+
+  it('settles once, however many times it is called', () => {
+    let width = 1009;
+    stub({innerWidth: 1024, clientWidth: 1009, widths: () => width});
+
+    const hold = holdScrollbarGutter(document.body);
+    width = 1024;
+    hold.settle();
+    hold.settle();
+    hold.settle();
+
+    expect(document.body.style.paddingRight).toBe('15px');
+
+    hold.release();
+  });
+
+  it('does nothing where there is no layout to measure', () => {
+    stub({innerWidth: 1024, clientWidth: 0});
+
+    const hold = holdScrollbarGutter(document.body);
+    hold.settle();
+
+    expect(rootGutter()).toBe('');
+    expect(document.body.style.paddingRight).toBe('');
+
+    hold.release();
+  });
+});

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/useResolvedRequired.ts

@@ -0,0 +1,42 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useResolvedRequired.ts
+ * @input Uses React, FormLayoutContext
+ * @output Exports useResolvedRequired
+ * @position Resolves a field's effective aria-required against the form default
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/FormLayout/FormLayoutContext.ts (defaultOptionality source)
+ * - /packages/core/src/FormLayout/FormLayout.tsx (prop doc: aria-required behavior)
+ */
+
+import {use} from 'react';
+import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
+
+/**
+ * Resolve a field's effective *required* state for `aria-required`, honoring a
+ * surrounding `FormLayout`'s `defaultOptionality`.
+ *
+ * Under `defaultOptionality="required"` a field is required unless it opts out
+ * with `isOptional`. The visible indicator is suppressed for the unmarked
+ * majority, so those fields must still expose `aria-required` — otherwise a
+ * sighted user reads them as required (form-wide default, no indicator) while a
+ * screen reader hears "not required". This closes that mismatch.
+ *
+ * Semantics only: this drives `aria-required`, never the native `required`
+ * attribute, so a layout-level default can't silently switch on browser
+ * validation bubbles. `isOptional` takes precedence, matching `FieldLabel`.
+ */
+export function useResolvedRequired({
+  isRequired = false,
+  isOptional = false,
+}: {
+  isRequired?: boolean;
+  isOptional?: boolean;
+}): boolean {
+  const {defaultOptionality} = use(FormLayoutContext);
+  return !isOptional && (isRequired || defaultOptionality === 'required');
+}

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.' },

package/src/hooks/useScrollLock.test.ts

@@ -17,6 +17,9 @@ describe('useScrollLock', () => {
   afterEach(() => {
     cleanup();
     document.body.style.cssText = '';
+    document.documentElement.style.cssText = '';
+    // @ts-expect-error -- drop the viewport stub so jsdom's own value comes back
+    delete document.documentElement.clientWidth;
     vi.restoreAllMocks();
   });
 
@@ -69,4 +72,74 @@ describe('useScrollLock', () => {
     expect(document.body.style.left).toBe('');
     expect(document.body.style.right).toBe('');
   });
+
+  it('holds the page still across the scrollbar it hides', () => {
+    // A 1024px window over a 1009px layout viewport = a 15px classic
+    // scrollbar. Pinning the body hides it, which would widen the page by
+    // those 15px and reflow everything sideways.
+    Object.defineProperty(window, 'innerWidth', {
+      value: 1024,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(document.documentElement, 'clientWidth', {
+      value: 1009,
+      configurable: true,
+    });
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const lock = renderHook(() => useScrollLock(true));
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('stable');
+
+    lock.unmount();
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('');
+  });
+
+  it('leaves the page alone when the scrollbar is an overlay one', () => {
+    Object.defineProperty(window, 'innerWidth', {
+      value: 1024,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(document.documentElement, 'clientWidth', {
+      value: 1024,
+      configurable: true,
+    });
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const lock = renderHook(() => useScrollLock(true));
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('');
+    expect(document.body.style.paddingRight).toBe('');
+
+    lock.unmount();
+  });
+
+  it('holds the gutter for the outermost overlay only, and gives it back once', () => {
+    Object.defineProperty(window, 'innerWidth', {
+      value: 1024,
+      configurable: true,
+      writable: true,
+    });
+    Object.defineProperty(document.documentElement, 'clientWidth', {
+      value: 1009,
+      configurable: true,
+    });
+    vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+    const first = renderHook(() => useScrollLock(true));
+    const second = renderHook(() => useScrollLock(true));
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('stable');
+
+    first.unmount();
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('stable');
+
+    second.unmount();
+
+    expect(document.documentElement.style.scrollbarGutter).toBe('');
+  });
 });

package/src/hooks/useScrollLock.ts

@@ -13,9 +13,11 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/scrollbarGutter.ts
  */
 
 import {useEffect} from 'react';
+import {holdScrollbarGutter, type ScrollbarGutterHold} from './scrollbarGutter';
 
 interface ScrollLockSnapshot {
   scrollX: number;
@@ -25,6 +27,7 @@ interface ScrollLockSnapshot {
   top: string;
   left: string;
   right: string;
+  gutter: ScrollbarGutterHold;
 }
 
 let lockCount = 0;
@@ -38,6 +41,10 @@ let originalBodyState: ScrollLockSnapshot | null = null;
  * does not prevent body scroll behind modals. Restores scroll position
  * on unlock.
  *
+ * Pinning also hides the document's scrollbar, so the gutter that scrollbar
+ * occupied is held open for the duration of the lock — without it the page
+ * reflows sideways by ~15px the moment an overlay opens.
+ *
  * @example
  * ```
  * useScrollLock(isOpen);
@@ -55,6 +62,9 @@ export function useScrollLock(isLocked: boolean): void {
       const scrollX = window.scrollX;
       const scrollY = window.scrollY;
 
+      // Taken before the pinning styles below hide the scrollbar.
+      const gutter = holdScrollbarGutter(body);
+
       originalBodyState = {
         scrollX,
         scrollY,
@@ -63,6 +73,7 @@ export function useScrollLock(isLocked: boolean): void {
         top: body.style.top,
         left: body.style.left,
         right: body.style.right,
+        gutter,
       };
 
       body.style.overflow = 'hidden';
@@ -70,6 +81,8 @@ export function useScrollLock(isLocked: boolean): void {
       body.style.top = `-${scrollY}px`;
       body.style.left = '0';
       body.style.right = '0';
+
+      gutter.settle();
     }
 
     lockCount += 1;
@@ -89,6 +102,7 @@ export function useScrollLock(isLocked: boolean): void {
       body.style.top = state.top;
       body.style.left = state.left;
       body.style.right = state.right;
+      state.gutter.release();
       window.scrollTo(state.scrollX, state.scrollY);
     };
   }, [isLocked]);

package/src/theme/derivedVarRegistry.test.ts

@@ -85,6 +85,9 @@ const STRUCTURAL_VARS = new Set([
   '--table-row-overlay',
   '--separator-display',
   '--astryx-section-padding',
+  // Private counterpart of the public token above: one ancestor Section's
+  // padding, propagated down the tree. Structural, never authored by a theme.
+  '--_section-padding-propagated',
 ]);
 
 /**
@@ -164,9 +167,6 @@ function discoverComponents(): ComponentInfo[] {
         allVars.add(v);
       }
     }
-    if (allVars.size === 0) {
-      continue;
-    }
 
     // Only check component directories (those with a doc file named after the
     // directory). Match against the on-disk listing rather than existsSync so
@@ -188,6 +188,16 @@ function discoverComponents(): ComponentInfo[] {
       /* skip */
     }
 
+    // A directory earns a check by declaring a var OR by documenting a
+    // derived[] entry. Bailing on the var count alone (as this did) hid every
+    // component that is themeable purely through an expansion strategy —
+    // `{property: 'padding', expand: 'container'}` names no var, so such a
+    // component declares nothing and its registry↔doc consistency check
+    // silently never ran.
+    if (allVars.size === 0 && docDerived.length === 0) {
+      continue;
+    }
+
     results.push({
       dir,
       sourceVars: [...allVars],
@@ -212,6 +222,7 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
   HoverCard: 'hovercard',
+  NumberInput: 'number-input',
   Popover: 'popover',
   ProgressBar: 'progressbar-mark',
   Section: 'section',