@astryxdesign/core 0.4.4 → 0.4.5-canary.0472ec1

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/i18n/InternationalizationContext.ts

@@ -16,6 +16,8 @@
  * - /packages/core/src/i18n/InternationalizationProvider.tsx
  * - /packages/core/src/i18n/t.client.ts
  * - /packages/core/src/i18n/useDirection.ts
+ * - /packages/core/src/i18n/useLocale.ts
+ * - /packages/core/src/i18n/useCollator.ts
  * - /packages/core/src/i18n/getLocaleDirection.ts
  * - /packages/core/src/i18n/index.ts
  */

package/src/i18n/__tests__/e2e-powersearch.test.tsx

@@ -23,7 +23,11 @@ import {describe, test, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import React, {useMemo} from 'react';
 import {PowerSearch, usePowerSearchConfig} from '../../PowerSearch';
-import type {FieldDefinition, PowerSearchFilter} from '../../PowerSearch';
+import type {
+  FieldDefinition,
+  PowerSearchConfig,
+  PowerSearchFilter,
+} from '../../PowerSearch';
 import {InternationalizationProvider} from '../InternationalizationProvider';
 import pseudoCatalog from '../../../locales/pseudo.json';
 
@@ -112,6 +116,38 @@ describe('PowerSearch × i18n — end to end', () => {
     expect(screen.getByText(/Name: contient/)).toBeInTheDocument();
   });
 
+  test('date tokens update when the provider locale changes', () => {
+    const config: PowerSearchConfig = {
+      name: 'Dates',
+      fields: [
+        {
+          key: 'created',
+          label: 'Created',
+          defaultOperator: 'is',
+          operators: [{key: 'is', label: 'is', value: {type: 'date_absolute'}}],
+        },
+      ],
+    };
+    const filters: PowerSearchFilter[] = [
+      {
+        field: 'created',
+        operator: 'is',
+        value: {type: 'date_absolute', unixSeconds: 1769342400},
+      },
+    ];
+    const search = (locale: string) => (
+      <InternationalizationProvider locale={locale}>
+        <PowerSearch config={config} filters={filters} onChange={() => {}} />
+      </InternationalizationProvider>
+    );
+
+    const {rerender} = render(search('en-US'));
+    expect(screen.getByText('Jan 25, 2026')).toBeInTheDocument();
+
+    rerender(search('de-DE'));
+    expect(screen.getByText('25. Jan. 2026')).toBeInTheDocument();
+  });
+
   test('resultCount ICU plural swaps under provider overrides', () => {
     render(
       <InternationalizationProvider

package/src/i18n/__tests__/useCollator.test.tsx

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useCollator.test.tsx
+ * @input packages/core/src/i18n/useCollator.ts, InternationalizationProvider
+ * @output Unit tests for the internal provider-aware Intl.Collator hook
+ * @position Colocated tests; targets the default (no-provider) fallback,
+ *   locale-driven comparison order, option threading, and memoization.
+ */
+
+import type {ReactNode} from 'react';
+import {describe, expect, test} from 'vitest';
+import {render, renderHook} from '@testing-library/react';
+import {useCollator} from '../useCollator';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+
+function wrapperFor(locale: string) {
+  return ({children}: {children: ReactNode}) => (
+    <InternationalizationProvider locale={locale}>
+      {children}
+    </InternationalizationProvider>
+  );
+}
+
+describe('useCollator', () => {
+  test('compares using the en fallback when rendered without a provider', () => {
+    const {result} = renderHook(() => useCollator());
+    expect(result.current.compare('a', 'b')).toBeLessThan(0);
+  });
+
+  test('orders "ä" before "z" under Swedish, and after "z" under German', () => {
+    const {result: sv} = renderHook(() => useCollator(), {
+      wrapper: wrapperFor('sv-SE'),
+    });
+    expect(['z', 'ä'].sort((a, b) => sv.current.compare(a, b))).toEqual([
+      'z',
+      'ä',
+    ]);
+
+    const {result: de} = renderHook(() => useCollator(), {
+      wrapper: wrapperFor('de-DE'),
+    });
+    expect(['z', 'ä'].sort((a, b) => de.current.compare(a, b))).toEqual([
+      'ä',
+      'z',
+    ]);
+  });
+
+  test('threads options through to the underlying Intl.Collator (numeric)', () => {
+    const {result} = renderHook(() => useCollator({numeric: true}));
+    expect(
+      ['item2', 'item10'].sort((a, b) => result.current.compare(a, b)),
+    ).toEqual(['item2', 'item10']);
+  });
+
+  test('without numeric, orders "item10" before "item2" lexicographically', () => {
+    const {result} = renderHook(() => useCollator());
+    expect(
+      ['item2', 'item10'].sort((a, b) => result.current.compare(a, b)),
+    ).toEqual(['item10', 'item2']);
+  });
+
+  test('memoizes the collator when locale and options identity are unchanged', () => {
+    const options = {numeric: true} satisfies Intl.CollatorOptions;
+    const {result, rerender} = renderHook(
+      ({collatorOptions}) => useCollator(collatorOptions),
+      {
+        initialProps: {collatorOptions: options},
+        wrapper: wrapperFor('en'),
+      },
+    );
+    const first = result.current;
+    rerender({collatorOptions: options});
+    expect(result.current).toBe(first);
+  });
+
+  test('rebuilds the collator when options identity changes', () => {
+    const {result, rerender} = renderHook(
+      ({collatorOptions}) => useCollator(collatorOptions),
+      {
+        initialProps: {
+          collatorOptions: {numeric: true} satisfies Intl.CollatorOptions,
+        },
+        wrapper: wrapperFor('en'),
+      },
+    );
+    const first = result.current;
+    rerender({collatorOptions: {numeric: true}});
+    expect(result.current).not.toBe(first);
+  });
+
+  test('re-renders with a new collator when the provider locale changes', () => {
+    let latestCollator: Intl.Collator | undefined;
+    function Probe() {
+      latestCollator = useCollator();
+      const order = ['z', 'ä'].sort((a, b) => latestCollator!.compare(a, b));
+      return <span data-testid="order">{order.join(',')}</span>;
+    }
+    const {getByTestId, rerender} = render(
+      <InternationalizationProvider locale="sv-SE">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('order').textContent).toBe('z,ä');
+    const svCollator = latestCollator;
+
+    rerender(
+      <InternationalizationProvider locale="de-DE">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('order').textContent).toBe('ä,z');
+    expect(latestCollator).not.toBe(svCollator);
+  });
+});

package/src/i18n/__tests__/useLocale.test.tsx

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useLocale.test.tsx
+ * @input packages/core/src/i18n/useLocale.ts, InternationalizationProvider
+ * @output Unit tests for the internal provider-aware locale accessor
+ * @position Colocated tests; targets the default (no-provider) fallback, the
+ *   provider locale, and re-rendering when the provider locale changes.
+ */
+
+import type {ReactNode} from 'react';
+import {describe, expect, test} from 'vitest';
+import {render, renderHook} from '@testing-library/react';
+import {useLocale} from '../useLocale';
+import {InternationalizationProvider} from '../InternationalizationProvider';
+
+describe('useLocale', () => {
+  test('returns en when rendered without a provider', () => {
+    const {result} = renderHook(() => useLocale());
+    expect(result.current).toBe('en');
+  });
+
+  test('returns the provider locale', () => {
+    const {result} = renderHook(() => useLocale(), {
+      wrapper: ({children}: {children: ReactNode}) => (
+        <InternationalizationProvider locale="fr">
+          {children}
+        </InternationalizationProvider>
+      ),
+    });
+    expect(result.current).toBe('fr');
+  });
+
+  test('re-renders with the new locale when the provider locale changes', () => {
+    function Probe() {
+      return <span data-testid="locale">{useLocale()}</span>;
+    }
+    const {getByTestId, rerender} = render(
+      <InternationalizationProvider locale="en">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('locale').textContent).toBe('en');
+
+    rerender(
+      <InternationalizationProvider locale="ja-JP">
+        <Probe />
+      </InternationalizationProvider>,
+    );
+    expect(getByTestId('locale').textContent).toBe('ja-JP');
+  });
+});

package/src/i18n/index.ts

@@ -10,12 +10,16 @@
  * The public API is deliberately small:
  *   - InternationalizationProvider — provider component
  *   - useTranslator               — hook returning a translator function
+ *   - useLocale                   — hook returning the provider locale
+ *   - useCollator                 — provider-bound locale-aware comparison
  *   - useDirection                — hook returning the ambient text direction
  *   - getLocaleDirection          — server-safe locale → direction helper
  *   - Translator                  — interface for consumer-injected runtimes
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/index.ts
+ * - /packages/core/src/i18n/useLocale.ts
+ * - /packages/core/src/i18n/useCollator.ts
  * - /packages/core/src/i18n/useDirection.ts
  * - /packages/core/src/i18n/getLocaleDirection.ts
  */
@@ -26,6 +30,8 @@ export {InternationalizationContext} from './InternationalizationContext';
 export type {InternationalizationContextValue} from './InternationalizationContext';
 export {useTranslator} from './useTranslator';
 export type {TranslatorFn} from './useTranslator';
+export {useLocale} from './useLocale';
+export {useCollator} from './useCollator';
 export {useDirection} from './useDirection';
 export {getLocaleDirection} from './getLocaleDirection';
 export type {Translator} from './translator';