@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

package/src/SideNav/__tests__/SideNavRailMotion.interaction.browser.spec.ts

@@ -12,7 +12,8 @@
  *   rest, the rail ends icons-only or with its labels, a second press mid-motion
  *   stays continuous, an expand whose old wrap is not copied keeps the edges
  *   together, and Reduce Motion cross-fades under a finger (DR2) and changes at
- *   once under a mouse (DR3)
+ *   once under a mouse (DR3), also on a loaded machine: those two cases read
+ *   the motion by its own start and end, never at a fixed time
  * @position Testing; the components' unit cases are
  *   SideNav/SideNavRailMotion.test.tsx
  *
@@ -216,30 +217,145 @@ function toggleButton(page: Page) {
   return page.getByRole('button', {name: /^(Collapse|Expand) sidebar$/});
 }
 
-/** Every running animation's animated properties and duration. */
-async function runningMotion(page: Page) {
-  return page.evaluate(() =>
-    document.getAnimations().map(animation => {
-      const effect = animation.effect as KeyframeEffect;
-      const properties = new Set<string>();
-      for (const frame of effect.getKeyframes()) {
-        for (const key of Object.keys(frame)) {
-          if (
-            !['offset', 'computedOffset', 'easing', 'composite'].includes(key)
-          ) {
-            properties.add(key);
+/**
+ * A loaded machine, made repeatable: Chromium's CPU throttle slows the page's
+ * main thread four times, or its animation clock runs every animation at a
+ * quarter of its speed, as when frames come late. Neither changes what the
+ * motion is; both move when it starts and ends in real time.
+ */
+const LOADS = ['idle', 'a slow CPU', 'slow frames'] as const;
+type Load = (typeof LOADS)[number];
+
+async function applyLoad(page: Page, load: Load): Promise<void> {
+  if (load === 'idle') {
+    return;
+  }
+  const cdp = await page.context().newCDPSession(page);
+  if (load === 'a slow CPU') {
+    await cdp.send('Emulation.setCPUThrottlingRate', {rate: 4});
+  } else {
+    await cdp.send('Animation.enable');
+    await cdp.send('Animation.setPlaybackRate', {playbackRate: 0.25});
+  }
+}
+
+/** The test-name suffix for a load: nothing when idle. */
+function underLoad(load: Load): string {
+  return load === 'idle' ? '' : `, with ${load}`;
+}
+
+/** One animation of the rail's motion: what it animates and when it ends. */
+interface MotionPart {
+  readonly properties: ReadonlyArray<string>;
+  /**
+   * When it ends on its own clock, in ms: its delay, every iteration and its
+   * end delay, so a delayed or repeated fade counts in full.
+   */
+  readonly endTime: number;
+  /** Whether it animates an element holding the page's main content. */
+  readonly holdsPage: boolean;
+}
+
+/** The record `recordMotion` keeps on the page, for `settledMotion`. */
+interface MotionRecord {
+  readonly seen: Map<Animation, MotionPart>;
+  readonly collect: () => void;
+  sampling: boolean;
+}
+
+/**
+ * Starts recording the motion a press of the toggle causes: every animation
+ * running on any frame from now on, described when first seen. Animations on
+ * the toggle element itself are its press feedback (its highlight's release
+ * fade runs on the button), not the rail's, so they are left out; everything
+ * inside it, its chevron included, stays in. `settledMotion` ends the record.
+ */
+async function recordMotion(page: Page): Promise<void> {
+  await toggleButton(page).evaluate(toggle => {
+    const seen = new Map<Animation, MotionPart>();
+    const collect = () => {
+      for (const animation of document.getAnimations()) {
+        const effect = animation.effect;
+        if (
+          seen.has(animation) ||
+          !(effect instanceof KeyframeEffect) ||
+          effect.target === toggle
+        ) {
+          continue;
+        }
+        const properties = new Set<string>();
+        for (const frame of effect.getKeyframes()) {
+          for (const key of Object.keys(frame)) {
+            if (
+              !['offset', 'computedOffset', 'easing', 'composite'].includes(key)
+            ) {
+              properties.add(key);
+            }
           }
         }
+        seen.set(animation, {
+          properties: [...properties],
+          endTime: Number(effect.getComputedTiming().endTime),
+          holdsPage:
+            effect.target instanceof Element &&
+            effect.target.contains(document.querySelector('[role="main"]')),
+        });
       }
-      return {
-        properties: [...properties],
-        duration: Number(effect.getTiming().duration),
-        holdsPage:
-          effect.target instanceof Element &&
-          effect.target.contains(document.querySelector('[role="main"]')),
-      };
-    }),
-  );
+    };
+    const record: MotionRecord = {seen, collect, sampling: true};
+    (window as unknown as {railMotion: MotionRecord}).railMotion = record;
+    const sample = () => {
+      if (record.sampling) {
+        collect();
+        requestAnimationFrame(sample);
+      }
+    };
+    requestAnimationFrame(sample);
+  });
+}
+
+/**
+ * Ends the record once the motion has ended on its own clock: every recorded
+ * animation has finished or been cancelled, and two more frames have passed
+ * without a new one, so what its end commits has landed. One that never ends
+ * (endless iterations) is not waited for; it is returned with an `endTime`
+ * of Infinity, for the cases to fail on. It never waits a fixed time: a loaded
+ * machine changes how long this takes, not what it reads.
+ */
+async function settledMotion(page: Page): Promise<ReadonlyArray<MotionPart>> {
+  return page.evaluate(async () => {
+    const record = (window as unknown as {railMotion: MotionRecord}).railMotion;
+    const isRunning = (animation: Animation) =>
+      animation.playState === 'running' &&
+      Number.isFinite(Number(animation.effect?.getComputedTiming().endTime));
+    const twoFrames = async () =>
+      new Promise<void>(resolve => {
+        requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+      });
+    for (;;) {
+      record.collect();
+      const running = [...record.seen.keys()].filter(isRunning);
+      if (running.length > 0) {
+        await Promise.all(
+          running.map(async animation =>
+            animation.finished.catch(() => undefined),
+          ),
+        );
+        continue;
+      }
+      const seenBefore = record.seen.size;
+      await twoFrames();
+      record.collect();
+      if (
+        record.seen.size === seenBefore &&
+        ![...record.seen.keys()].some(isRunning)
+      ) {
+        break;
+      }
+    }
+    record.sampling = false;
+    return [...record.seen.values()];
+  });
 }
 
 test.describe('component:SideNav FR6 and component:AppShell FR17 under a finger', () => {
@@ -341,25 +457,29 @@ test.describe('component:SideNav FR6 and component:AppShell FR17 under a finger'
     });
   });
 
-  test('under Reduce Motion a tap only cross-fades, in 200 ms or less, with the page surface still (design:reduced-motion DR2)', async ({
-    page,
-  }) => {
-    await page.emulateMedia({reducedMotion: 'reduce'});
-    await openStory(page, PHONE_STORY);
-    await toggleButton(page).tap();
-    const motion = await runningMotion(page);
-    expect(motion.length).toBeGreaterThan(0);
-    for (const {properties, duration, holdsPage} of motion) {
-      expect(properties).toEqual(['opacity']);
-      expect(duration).toBeLessThanOrEqual(200);
-      expect(holdsPage).toBe(false);
-    }
-    await page.waitForTimeout(400);
-    expect(await railAtRest(page)).toMatchObject({
-      labelsShown: false,
-      copies: 0,
+  for (const load of LOADS) {
+    test(`under Reduce Motion a tap only cross-fades, in 200 ms or less, with the page surface still${underLoad(load)} (design:reduced-motion DR2)`, async ({
+      page,
+    }) => {
+      await page.emulateMedia({reducedMotion: 'reduce'});
+      await openStory(page, PHONE_STORY);
+      await applyLoad(page, load);
+      await recordMotion(page);
+      await toggleButton(page).tap();
+      await expect(toggleButton(page)).toHaveAccessibleName('Expand sidebar');
+      const motion = await settledMotion(page);
+      expect(motion.length).toBeGreaterThan(0);
+      for (const {properties, endTime, holdsPage} of motion) {
+        expect(properties).toEqual(['opacity']);
+        expect(endTime).toBeLessThanOrEqual(200);
+        expect(holdsPage).toBe(false);
+      }
+      expect(await railAtRest(page)).toMatchObject({
+        labelsShown: false,
+        copies: 0,
+      });
     });
-  });
+  }
 });
 
 test.describe('component:SideNav FR6 and component:AppShell FR17 under a mouse', () => {
@@ -402,16 +522,21 @@ test.describe('component:SideNav FR6 and component:AppShell FR17 under a mouse',
     });
   });
 
-  test('under Reduce Motion a click changes the rail and the page at once (design:reduced-motion DR3)', async ({
-    page,
-  }) => {
-    await page.emulateMedia({reducedMotion: 'reduce'});
-    await openStory(page, DESKTOP_STORY);
-    await toggleButton(page).click();
-    expect(await runningMotion(page)).toEqual([]);
-    expect(await railAtRest(page)).toMatchObject({
-      labelsShown: false,
-      copies: 0,
+  for (const load of LOADS) {
+    test(`under Reduce Motion a click changes the rail and the page at once${underLoad(load)} (design:reduced-motion DR3)`, async ({
+      page,
+    }) => {
+      await page.emulateMedia({reducedMotion: 'reduce'});
+      await openStory(page, DESKTOP_STORY);
+      await applyLoad(page, load);
+      await recordMotion(page);
+      await toggleButton(page).click();
+      await expect(toggleButton(page)).toHaveAccessibleName('Expand sidebar');
+      expect(await settledMotion(page)).toEqual([]);
+      expect(await railAtRest(page)).toMatchObject({
+        labelsShown: false,
+        copies: 0,
+      });
     });
-  });
+  }
 });

package/src/Skeleton/Skeleton.tsx

@@ -97,7 +97,9 @@ const styles = stylex.create({
   },
   animate: {
     animationDirection: 'alternate',
-    animationDuration: durationVars['--duration-medium-max'],
+    // The loop reads the duration before a theme's tempo scales it
+    // (spec:AST-108 FR4).
+    animationDuration: `var(--_astryx-pre-tempo-duration-medium-max, ${durationVars['--duration-medium-max']})`,
     animationIterationCount: 'infinite',
     // Disable the pulse under reduced-motion; the static placeholder still
     // reads as loading (complex-20).

package/src/Slider/Slider.test.tsx

@@ -9,6 +9,7 @@
  * SYNC: When Slider.tsx changes, update tests to match new behavior
  */
 
+import {InternationalizationProvider} from '../i18n';
 import {useState} from 'react';
 import {describe, it, expect, vi, beforeEach} from 'vitest';
 import {render, screen, act, fireEvent, waitFor} from '@testing-library/react';
@@ -75,6 +76,24 @@ describe('Slider', () => {
     expect(sliders[1]).toHaveAccessibleName('Maximum value');
   });
 
+  it('translates the range thumb names under another locale', () => {
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.slider.minimumThumb': 'Valeur minimale',
+            '@astryx.slider.maximumThumb': 'Valeur maximale',
+          },
+        }}>
+        <Slider label="Prix" value={[20, 80] as [number, number]} />
+      </InternationalizationProvider>,
+    );
+    const sliders = screen.getAllByRole('slider');
+    expect(sliders[0]).toHaveAccessibleName('Valeur minimale');
+    expect(sliders[1]).toHaveAccessibleName('Valeur maximale');
+  });
+
   it('sets aria-valuetext with formatValue', () => {
     render(
       <Slider label="Temperature" value={72} formatValue={v => `${v}°F`} />,
@@ -337,6 +356,18 @@ describe('Slider', () => {
     expect(slider).not.toHaveAttribute('aria-required');
   });
 
+  it('conveys required state under FormLayout defaultOptionality="required" unless isOptional (FormLayout FR5)', () => {
+    render(
+      <FormLayout defaultOptionality="required">
+        <Slider label="Volume" value={50} />
+        <Slider label="Balance" value={50} isOptional />
+      </FormLayout>,
+    );
+    const [volume, balance] = screen.getAllByRole('slider');
+    expect(volume).toHaveAccessibleDescription(/Required/);
+    expect(balance).not.toHaveAccessibleDescription(/Required/);
+  });
+
   it('conveys required state on both thumbs of a range slider', () => {
     render(
       <Slider

package/src/Slider/Slider.tsx

@@ -58,6 +58,8 @@ import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import {useTranslator} from '../i18n';
 // =============================================================================
 // Types
 // =============================================================================
@@ -512,6 +514,7 @@ export function Slider({ref, ...props}: SliderProps) {
     'aria-describedby': ariaDescribedByProp,
     ...restWithRange
   } = props;
+  const t = useTranslator();
   const {minStepsBetweenThumbs: _minSteps, ...restProps} =
     restWithRange as typeof restWithRange & {minStepsBetweenThumbs?: number};
   const {rest, container} = useFieldInputStyling('Slider', restProps, {
@@ -591,7 +594,9 @@ export function Slider({ref, ...props}: SliderProps) {
   // role="slider" in WAI-ARIA 1.2, so the thumb instead points its
   // aria-describedby at a visually hidden "Required" span — mirroring the
   // Field label's visible indicator (where isOptional takes precedence).
-  const conveysRequired = isRequired && !isOptional;
+  // A surrounding FormLayout's defaultOptionality="required" makes an unmarked
+  // field required too (FormLayout FR5).
+  const conveysRequired = useResolvedRequired({isRequired, isOptional});
 
   // Build aria-describedby
   const describedByParts: string[] = [];
@@ -980,8 +985,8 @@ export function Slider({ref, ...props}: SliderProps) {
     // name from the visible label element via aria-labelledby.
     const thumbLabel = isRange
       ? thumbIndex === 0
-        ? 'Minimum value'
-        : 'Maximum value'
+        ? t('@astryx.slider.minimumThumb')
+        : t('@astryx.slider.maximumThumb')
       : undefined;
 
     // ARIA bounds must agree with the movement clamping in updateValue: in

package/src/Slider/__tests__/Slider.a11y.chromium.spec.ts

@@ -87,16 +87,28 @@ async function runState(
   });
 }
 
-test('every slider expectation is exercised by a Slider state', async ({
-  page,
-}) => {
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every slider expectation is exercised by a Slider state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of SLIDER_BINDING_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
-  expect(unmatchedKnownFailures(SLIDER_KNOWN_FAILURES, results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      SLIDER_BINDING_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+    expect(unmatchedKnownFailures(SLIDER_KNOWN_FAILURES, results)).toEqual([]);
+  });
 });
 
 for (const state of SLIDER_BINDING_STATES) {

package/src/Spinner/Spinner.tsx

@@ -21,8 +21,8 @@ import * as stylex from '@stylexjs/stylex';
 import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {Text} from '../Text/Text';
-import {mergeProps} from '../utils';
-import {useTranslator} from '../i18n';
+import {mergeProps} from '../utils/mergeProps';
+import {useTranslator} from '../i18n/useTranslator';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -334,7 +334,9 @@ const styles = stylex.create({
     // it (a frozen spinner reads as broken), matching ProgressBar's approach.
     // The role="status" + "Loading" label still convey busy state (obs-6).
     animationDuration: {
-      default: durationVars['--duration-slow-min'],
+      // The loop reads the duration before a theme's tempo scales it
+      // (spec:AST-108 FR4).
+      default: `var(--_astryx-pre-tempo-duration-slow-min, ${durationVars['--duration-slow-min']})`,
       '@media (prefers-reduced-motion: reduce)': '3s',
     },
     animationIterationCount: 'infinite',

package/src/Stack/Stack.tsx

@@ -30,7 +30,7 @@ import {
   paddingBlockStartStyles,
   paddingBlockEndStyles,
 } from '../Layout/padding.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

package/src/Stack/StackItem.tsx

@@ -19,7 +19,7 @@ import {
   type StackItemCrossAlignSelf,
   type StackItemSize,
 } from './stackItem.stylex';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 
 const overflowStyles = stylex.create({

package/src/TabList/TabList.test.tsx

@@ -9,8 +9,9 @@
  * SYNC: When TabList components change, update tests to match new behavior
  */
 
+import {useState} from 'react';
 import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
-import {render, screen, fireEvent} from '@testing-library/react';
+import {act, render, screen, fireEvent, waitFor} from '@testing-library/react';
 import {__resetMenuPressForTest} from '../hooks/useMenuPress';
 import userEvent from '@testing-library/user-event';
 import {
@@ -933,8 +934,10 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
       hidden: true,
     });
 
-    fireEvent.keyDown(menu, {key: 'ArrowDown'});
-    expect(analytics).toHaveFocus();
+    // Opening moves focus to the first item a frame later (APG menu-button
+    // focus-on-open): wait for it, since a key pressed before that frame
+    // starts from no item and one pressed after it starts from the first.
+    await waitFor(() => expect(analytics).toHaveFocus());
 
     fireEvent.keyDown(menu, {key: 'ArrowDown'});
     expect(reports).toHaveFocus();
@@ -963,7 +966,8 @@ describe('TabMenu keyboard navigation (roving tabindex)', () => {
       hidden: true,
     });
 
-    fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus analytics
+    // Focus lands on the first item a frame after opening (see above).
+    await waitFor(() => expect(analytics).toHaveFocus());
     fireEvent.keyDown(menu, {key: 'ArrowDown'}); // focus reports
 
     // The tab stop follows focus, so it is still a single stop after moving.
@@ -1237,6 +1241,56 @@ describe('TabList overflow (scroll)', () => {
     expect(scrollBy).not.toHaveBeenCalled();
   });
 
+  it('measures a pressed tab after the press, in the next frame, and still shows it whole', async () => {
+    function Controlled() {
+      const [value, setValue] = useState('a');
+      return (
+        <TabList value={value} onChange={setValue}>
+          <Tab value="a" label="Alpha" />
+          <Tab value="b" label="Beta" />
+          <Tab value="c" label="Gamma" />
+        </TabList>
+      );
+    }
+    const {container} = render(<Controlled />);
+    const strip = container.querySelector<HTMLElement>(STRIP);
+    const tab = container.querySelector<HTMLElement>('[data-tab-value="c"]');
+    if (!strip || !tab) {
+      throw new Error('no tab strip');
+    }
+    const scrollBy = vi.fn();
+    strip.scrollBy = scrollBy;
+    const stripRect = vi.fn(
+      () => ({left: 0, right: 300, width: 300}) as DOMRect,
+    );
+    strip.getBoundingClientRect = stripRect;
+    tab.getBoundingClientRect = () =>
+      ({left: 240, right: 320, width: 80}) as DOMRect;
+
+    // Pressing a tab focuses it first, and focusing it reveals it.
+    fireEvent.focus(tab);
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+    expect(scrollBy.mock.calls[0][0].left).toBe(20);
+    const readsBeforePress = stripRect.mock.calls.length;
+
+    // The selection itself reads no geometry inside the press...
+    fireEvent.click(tab);
+    expect(tab).toHaveAttribute('aria-current', 'true');
+    expect(stripRect.mock.calls.length).toBe(readsBeforePress);
+    expect(scrollBy).toHaveBeenCalledTimes(1);
+
+    // ...and the next frame measures the selected tab, now wider, so it still
+    // ends fully inside the strip.
+    tab.getBoundingClientRect = () =>
+      ({left: 220, right: 306, width: 86}) as DOMRect;
+    await act(
+      async () =>
+        new Promise<void>(resolve => requestAnimationFrame(() => resolve())),
+    );
+    expect(scrollBy).toHaveBeenCalledTimes(2);
+    expect(scrollBy.mock.calls[1][0].left).toBe(6);
+  });
+
   it('reveals on a selection change, not on an unrelated overflow change', () => {
     const {strip, rerender} = renderStrip({value: 'c', overflow: 'visible'});
     const scrollBy = vi.fn();

package/src/TabList/TabList.tsx

@@ -515,6 +515,10 @@ export function TabList({
     revealSelectedTabRef.current = revealSelectedTab;
   }, [revealSelectedTab]);
 
+  // The tab whose focus revealed it (see `handleRootFocus`), while it keeps
+  // focus.
+  const focusRevealedValueRef = useRef<string | null>(null);
+
   // The tab you are on has to be visible. Selection can move without focus —
   // on mount, or when the host sets `value` itself — and neither scrolls the
   // strip the way clicking or arrowing to a tab does. The check is what makes
@@ -525,6 +529,14 @@ export function TabList({
       return;
     }
     revealedValueRef.current = value;
+    if (value != null && focusRevealedValueRef.current === value) {
+      // A press or an arrow focused this tab first, and focusing it revealed
+      // it. Measuring now would force the new selection's style and layout
+      // inside the press, before it can paint. The next frame lays them out
+      // anyway, so finish there: the selected weight can still widen the tab.
+      const frame = requestAnimationFrame(() => revealSelectedTabRef.current());
+      return () => cancelAnimationFrame(frame);
+    }
     revealSelectedTabRef.current();
   }, [value]);
 
@@ -595,7 +607,9 @@ export function TabList({
       // The browser scrolls a focused element into view only when it is
       // entirely outside the scrollport, so arrowing onto a half-visible stop
       // leaves it cut off under the fade. Finish the job it started.
-      revealStop(e.target.closest(TAB_STOP_SELECTOR));
+      const stop = e.target.closest<HTMLElement>(TAB_STOP_SELECTOR);
+      revealStop(stop);
+      focusRevealedValueRef.current = stop?.dataset.tabValue ?? null;
     },
     [onFocusProp, onHintFocus, handleFocus, revealStop],
   );
@@ -603,6 +617,7 @@ export function TabList({
   const handleRootBlur = useCallback(
     (e: React.FocusEvent<HTMLElement>) => {
       onBlurProp?.(e);
+      focusRevealedValueRef.current = null;
       if (e.defaultPrevented) {
         return;
       }