@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

package/src/Resizable/ResizeHandle.tsx

@@ -35,11 +35,12 @@ import {
   spacingVars,
 } from '../theme/tokens.stylex';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import type {ResizableProps} from './useResizable';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 const KEYBOARD_STEP = 10;
 const KEYBOARD_LARGE_STEP = 50;
 
@@ -549,7 +550,7 @@ export function ResizeHandle({
 
   return (
     <div
-      ref={mergeRefs(ref, handleRef)}
+      ref={useMergedRefs(ref, handleRef)}
       role="separator"
       aria-orientation={isHorizontal ? 'vertical' : 'horizontal'}
       aria-valuenow={ariaValueNow}

package/src/SegmentedControl/SegmentedControl.tsx

@@ -26,11 +26,12 @@ import type {
   SegmentedControlSize,
   SegmentedControlLayout,
 } from './SegmentedControlContext';
-import {mergeProps, mergeRefs, composeEventHandlers} from '../utils';
+import {mergeProps, composeEventHandlers} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 export interface SegmentedControlProps extends Omit<
   BaseProps<HTMLDivElement>,
   'onChange'
@@ -258,7 +259,7 @@ export function SegmentedControl({
   return (
     <SegmentedControlContext value={contextValue}>
       <div
-        ref={mergeRefs(ref, listRef, disabledMessageTooltip.ref)}
+        ref={useMergedRefs(ref, listRef, disabledMessageTooltip.ref)}
         {...rest}
         role="radiogroup"
         aria-label={label}

package/src/SelectableCard/SelectableCard.tsx

@@ -40,7 +40,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import type {Elevation, SizeValue, SpacingStep} from '../utils/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {Card} from '../Card/Card';
 import type {CardVariant} from '../Card/Card';
 import {useClickableContainer} from '../hooks/useClickableContainer';
@@ -48,6 +48,7 @@ import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles — selection + interaction; Card handles the rest
 // =============================================================================
@@ -346,7 +347,7 @@ export function SelectableCard({
 
   return (
     <Card
-      ref={mergeRefs(ref, containerRef)}
+      ref={useMergedRefs(ref, containerRef)}
       width={width}
       height={height}
       maxWidth={maxWidth}

package/src/Selector/Selector.doc.mjs

@@ -171,7 +171,7 @@ export const docs = {
       name: 'renderValue',
       type: '(option: SelectorOptionData) => ReactNode',
       description:
-        'Custom render function for the selected option inside the closed trigger. The trigger is sized by padding, so it is the size token for a one-line value (28/32/36) and exactly one text line taller for a two-line one (48/52/56) — always on the 4px rhythm, always aligned with the buttons and inputs beside it. Inside an InputGroup the group owns the row height: a SelectorOption folds onto one line and ellipsizes, and any taller node is cut off at the row.',
+        'Custom render function for the selected option inside the closed trigger. The trigger is sized by padding, so it is the size token for a one-line value (28/32/36) and exactly one text line taller for a two-line one (48/52/56), always on the 4px rhythm, always aligned with the buttons and inputs beside it. Inside an InputGroup the group owns the row height: a SelectorOption folds onto one line and ellipsizes, and any taller node is cut off at the row.',
     },
     {
       name: 'indicatorPosition',
@@ -186,6 +186,17 @@ export const docs = {
       description:
         'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
+    {
+      name: 'startIcon',
+      type: 'IconType | ReactNode',
+      description: 'Icon displayed at the start of the selector trigger.',
+    },
+    {
+      name: 'isLoading',
+      type: 'boolean',
+      description: 'Shows a loading spinner in the trigger.',
+      default: 'false',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Selector/Selector.test.tsx

@@ -961,7 +961,7 @@ describe('Selector', () => {
       expect(onChange).toHaveBeenCalledWith('Banana');
     });
 
-    it('closes dropdown on Tab without preventing default focus movement', async () => {
+    it('closes the search dropdown on Tab without preventing default focus movement', async () => {
       const user = userEvent.setup();
       render(
         <>
@@ -1253,6 +1253,29 @@ describe('Selector', () => {
   });
 
   describe('keyboard accessibility', () => {
+    it('Tab from the open listbox moves focus to the next control', async () => {
+      const user = userEvent.setup();
+      render(
+        <>
+          <Selector
+            label="Fruit"
+            options={OPTIONS}
+            value="Apple"
+            onChange={() => {}}
+          />
+          <button type="button">Next</button>
+        </>,
+      );
+
+      const trigger = screen.getByRole('combobox');
+      await user.click(trigger);
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+      await user.keyboard('{Tab}');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(screen.getByRole('button', {name: 'Next'})).toHaveFocus();
+    });
+
     it('trigger is focusable via Tab when enabled', async () => {
       const user = userEvent.setup();
       render(<Selector label="Fruit" options={OPTIONS} />);
@@ -2484,6 +2507,27 @@ describe('Selector section headings', () => {
     // visible heading must not announce it a second time.
     expect(heading).toHaveAttribute('aria-hidden', 'true');
   });
+
+  it('hides a standalone divider from the accessibility tree (#4994)', async () => {
+    const user = userEvent.setup();
+    render(
+      <Selector
+        label="Fruit"
+        options={['Apple', {type: 'divider'}, 'Banana']}
+        value={undefined}
+        onChange={() => {}}
+      />,
+    );
+    await user.click(screen.getByRole('combobox'));
+
+    // role="listbox" only permits option/group children. The divider still
+    // renders role="separator" (unchanged visual/DOM), but must be excluded
+    // from the accessibility tree so it never reaches the listbox's exposed
+    // children (axe aria-required-children).
+    const divider = document.querySelector('[role="separator"]');
+    expect(divider).toBeTruthy();
+    expect(divider).toHaveAttribute('aria-hidden', 'true');
+  });
 });
 
 describe('Selector search focus ring', () => {

package/src/Selector/Selector.tsx

@@ -1344,7 +1344,17 @@ export function Selector<T extends SelectorOptionType>(
         if (isSearching) {
           continue;
         }
-        elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
+        // role="listbox" only permits option/group children; the divider
+        // carries no information the options don't, so it's hidden from the
+        // accessibility tree entirely rather than exposing role="separator"
+        // as a disallowed listbox child (axe aria-required-children).
+        elements.push(
+          <Divider
+            key={`divider-${i}`}
+            aria-hidden="true"
+            xstyle={styles.divider}
+          />,
+        );
       } else if (isSection(option)) {
         const sectionItems: ReactNode[] = [];
         for (const opt of option.options) {

package/src/SideNav/SideNav.doc.mjs

@@ -131,8 +131,8 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
-      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
-      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'Mark the current page with isSelected: it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short; they are the accessible name in both expanded and icon-only modes.'},
       {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
@@ -153,8 +153,8 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
-      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
-      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'Mark the current page with isSelected: it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short; they are the accessible name in both expanded and icon-only modes.'},
       {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},
@@ -175,8 +175,8 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Use sections to group related navigation items and help users scan for their destination.'},
       {guidance: true, description: 'Pair outline and filled icon variants so the selected state is visually distinct.'},
-      {guidance: true, description: 'Mark the current page with isSelected — it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
-      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short — they are the accessible name in both expanded and icon-only modes.'},
+      {guidance: true, description: 'Mark the current page with isSelected: it sets aria-current="page", so the current destination is announced rather than carried by color alone.'},
+      {guidance: true, description: 'SideNav renders a navigation landmark, and a collapsible item follows the WAI-ARIA APG Disclosure pattern (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/): the toggle carries aria-expanded and aria-controls, and the group it owns is inert while collapsed. Keep item labels short; they are the accessible name in both expanded and icon-only modes.'},
       {guidance: true, description: 'While the nav is collapsed, an item with children shows them in a submenu flyout. On a device that can hover, pointing at the item opens it after a short delay and moving away closes it; a flyout opened by clicking stays open until it is dismissed. On touch, it opens on tap. Do not put an action in there that has no other route to it.'},
       {guidance: false, description: 'Include a SideNavHeading when a TopNav is already providing app identity; this duplicates branding.'},
       {guidance: false, description: 'Use for filtering content; use tabs or filter buttons instead.'},

package/src/SideNav/SideNav.tsx

@@ -32,7 +32,7 @@ import type {BaseProps} from '../BaseProps';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {spacingVars} from '../theme/tokens.stylex';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import {
   SideNavCollapseContext,
   type SideNavCollapseState,
@@ -49,6 +49,7 @@ import {themeProps} from '../utils/themeProps';
 import {SizeProvider} from '../SizeContext/SizeContext';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Constants
 // =============================================================================
@@ -349,6 +350,7 @@ export function SideNav({
     useState(defaultIsCollapsed);
   const collapsed = isControlled ? controlledCollapsed : uncontrolledCollapsed;
   const navRef = useRef<HTMLElement>(null);
+  const mergedNavRef = useMergedRefs(ref, navRef);
   const collapseStateRef = useRef<SideNavCollapseState>({
     isCollapsed: collapsed,
     toggle: () => {},
@@ -517,7 +519,7 @@ export function SideNav({
 
   const navElement = (
     <nav
-      ref={mergeRefs(ref, navRef)}
+      ref={mergedNavRef}
       role="navigation"
       aria-label={t('@astryx.sideNav.label')}
       data-testid={testId}

package/src/SideNav/SideNavHeading.tsx

@@ -40,7 +40,8 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {useSideNavCollapse} from './SideNavCollapseContext';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
+import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {BaseProps} from '../BaseProps';
 import {useMenuHover} from '../hooks/useMenuHover';
 import {NavHeadingCloseContext} from '../NavMenu/NavMenuContext';
@@ -399,11 +400,18 @@ export function SideNavHeading({
   // setTriggerEl belongs on the chevron button, not this root: it is the
   // focus-restore target and a <div> cannot take focus. triggerRef stays here
   // because the panel anchors to the whole heading.
-  const setRef = mergeRefs<HTMLDivElement>(
+  const setRef = useMergedRefs<HTMLDivElement>(
     rootRef,
     ref,
     menu ? popover.triggerRef : undefined,
   );
+  const collapsedSetRef = useMergedRefs<HTMLElement>(
+    collapsedItemRef,
+    ref,
+    // Collapsed, this button is the trigger, so it takes both roles.
+    menu ? popover.triggerRef : undefined,
+    menu ? setTriggerEl : undefined,
+  );
 
   // In collapsed mode: hide if no icon, show icon-only if has icon
   if (isCollapsed && !icon) {
@@ -412,14 +420,6 @@ export function SideNavHeading({
   if (isCollapsed && icon) {
     const collapsedIcon = <span {...stylex.props(styles.icon)}>{icon}</span>;
 
-    const collapsedSetRef = mergeRefs<HTMLElement>(
-      collapsedItemRef,
-      ref,
-      // Collapsed, this button is the trigger, so it takes both roles.
-      menu ? popover.triggerRef : undefined,
-      menu ? setTriggerEl : undefined,
-    );
-
     let collapsedElement: ReactNode;
 
     if (headingHref) {

package/src/SideNav/SideNavItem.tsx

@@ -47,7 +47,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {usePopover} from '../Popover/usePopover';
 import {useMenuHover} from '../hooks/useMenuHover';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {Tooltip} from '../Tooltip';
 import {navItemStyles, type NavItemSize} from '../NavItem/navItemStyles.stylex';
@@ -61,6 +61,7 @@ import {useAppShellMobile} from '../AppShell/AppShellMobileContext';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Styles
 // =============================================================================
@@ -408,6 +409,7 @@ export function SideNavItem({
     hasCloseButton: false,
     dialogLabel: t('@astryx.sideNavItem.submenuLabel', {label}),
   });
+  const mergedTriggerRef = useMergedRefs(ref, popover.triggerRef);
 
   // Collapse state for items with children
   const itemCollapsibleConfig = useMemo(
@@ -524,7 +526,7 @@ export function SideNavItem({
       return (
         <div {...stylex.props(styles.root, xstyle)}>
           <button
-            ref={mergeRefs(ref, popover.triggerRef)}
+            ref={mergedTriggerRef}
             type="button"
             {...rest}
             {...hoverTriggerProps}

package/src/Slider/Slider.tsx

@@ -40,13 +40,14 @@ import {Tooltip} from '../Tooltip/Tooltip';
 import {useTooltip} from '../Tooltip';
 import {VisuallyHidden} from '../VisuallyHidden';
 import type {InputStatus} from '../Field/types';
-import {mergeProps, mergeRefs, rtlStyles} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
 import {isRtlElement} from '../hooks/isRtlElement';
 import type {BaseProps} from '../BaseProps';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 
+import {useMergedRefs} from '../hooks/useMergedRefs';
 // =============================================================================
 // Types
 // =============================================================================
@@ -964,7 +965,7 @@ export function Slider({ref, ...props}: SliderProps) {
             />
           ))}
         <div
-          ref={mergeRefs(ref, trackRef, disabledMessageTooltip.ref)}
+          ref={useMergedRefs(ref, trackRef, disabledMessageTooltip.ref)}
           {...(isRange
             ? {role: 'group', 'aria-labelledby': labelID}
             : undefined)}

package/src/Spinner/Spinner.test.tsx

@@ -9,10 +9,29 @@
  * SYNC: When Spinner.tsx changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Spinner} from './Spinner';
 
+/** sm/md/lg/xl, as Spinner.tsx defines them. */
+const SIZES = {
+  sm: {diameter: 10, border: 2},
+  md: {diameter: 14, border: 3},
+  lg: {diameter: 18, border: 3},
+  xl: {diameter: 28, border: 4},
+} as const;
+
+const ring = (testId = 'spinner') =>
+  screen.getByTestId(testId).querySelector('svg') as SVGSVGElement;
+
+const circles = (testId = 'spinner') => {
+  const [track, arc] = [...ring(testId).querySelectorAll('circle')];
+  return {track, arc};
+};
+
+const dashOf = (el: SVGCircleElement) =>
+  (el.getAttribute('stroke-dasharray') ?? '').split(/[\s,]+/).map(Number);
+
 describe('Spinner', () => {
   it('renders with default props', () => {
     render(<Spinner data-testid="spinner" />);
@@ -122,3 +141,130 @@ describe('Spinner', () => {
     expect(spinner.tagName.toLowerCase()).toBe('span');
   });
 });
+
+describe('Spinner ring', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('draws the ring in SVG', () => {
+    render(<Spinner data-testid="spinner" />);
+    const svg = ring();
+    expect(svg).not.toBeNull();
+    expect(svg.querySelectorAll('circle')).toHaveLength(2);
+    expect(screen.getByTestId('spinner').querySelector('canvas')).toBeNull();
+  });
+
+  it.each(Object.entries(SIZES))(
+    'sizes the %s ring from its size token',
+    (size, {diameter, border}) => {
+      render(
+        <Spinner size={size as keyof typeof SIZES} data-testid="spinner" />,
+      );
+      const frame = diameter + border * 2;
+      const svg = ring();
+      expect(svg.getAttribute('viewBox')).toBe(`0 0 ${frame} ${frame}`);
+      for (const c of [circles().track, circles().arc]) {
+        expect(Number(c.getAttribute('cx'))).toBe(frame / 2);
+        expect(Number(c.getAttribute('cy'))).toBe(frame / 2);
+        expect(Number(c.getAttribute('r'))).toBe(diameter / 2);
+        expect(Number(c.getAttribute('stroke-width'))).toBe(border);
+      }
+    },
+  );
+
+  // The canvas ring swept 135deg, not the 270deg its SPREAD comment claimed.
+  it.each(Object.entries(SIZES))(
+    'sweeps 135 degrees at %s',
+    (size, {diameter}) => {
+      render(
+        <Spinner size={size as keyof typeof SIZES} data-testid="spinner" />,
+      );
+      const {track, arc} = circles();
+      const [on, off] = dashOf(arc);
+      expect(on + off).toBeCloseTo(Math.PI * diameter, 6);
+      expect((on / (on + off)) * 360).toBeCloseTo(135, 6);
+      expect(track.getAttribute('stroke-dasharray')).toBeNull();
+    },
+  );
+
+  it('starts the arc at twelve o’clock', () => {
+    render(<Spinner data-testid="spinner" />);
+    const frame = SIZES.md.diameter + SIZES.md.border * 2;
+    expect(circles().arc.getAttribute('transform')).toBe(
+      `rotate(-90 ${frame / 2} ${frame / 2})`,
+    );
+  });
+
+  // The whole point of the SVG ring: the colours come off the cascade, so
+  // nothing has to resolve them in JS. A read reaching the paint path again
+  // fails here.
+  it.each(['default', 'subtle', 'onMedia', 'inherit'] as const)(
+    'reads no computed style to paint the %s shade',
+    shade => {
+      const spy = vi.spyOn(window, 'getComputedStyle');
+      render(<Spinner shade={shade} data-testid="spinner" />);
+      const spinner = screen.getByTestId('spinner');
+      const onSpinner = spy.mock.calls.filter(
+        ([el]) => el instanceof Element && spinner.contains(el),
+      );
+      expect(onSpinner).toEqual([]);
+    },
+  );
+
+  it('schedules no frame where the Web Animations API is absent', () => {
+    expect(SVGElement.prototype).not.toHaveProperty('getAnimations');
+    const raf = vi.spyOn(window, 'requestAnimationFrame');
+    render(<Spinner data-testid="spinner" />);
+    expect(ring()).not.toBeNull();
+    expect(raf).not.toHaveBeenCalled();
+  });
+
+  it('pins every ring to the timeline origin in a single frame', () => {
+    const animations: {startTime: number | null}[] = [];
+    const getAnimations = vi.fn(function (this: SVGElement) {
+      const a = {startTime: null as number | null};
+      animations.push(a);
+      return [a];
+    });
+    Object.defineProperty(SVGElement.prototype, 'getAnimations', {
+      value: getAnimations,
+      configurable: true,
+      writable: true,
+    });
+    const frames: FrameRequestCallback[] = [];
+    const raf = vi
+      .spyOn(window, 'requestAnimationFrame')
+      .mockImplementation(cb => {
+        frames.push(cb);
+        return frames.length;
+      });
+    const computed = vi.spyOn(window, 'getComputedStyle');
+
+    try {
+      const {container} = render(
+        <>
+          {Array.from({length: 5}, (_, i) => (
+            <Spinner key={i} />
+          ))}
+        </>,
+      );
+      // One frame for five spinners: the reads are batched, so no mount
+      // re-forces what the previous mount invalidated.
+      expect(raf).toHaveBeenCalledTimes(1);
+      frames.forEach(cb => cb(0));
+      expect(animations).toHaveLength(5);
+      expect(animations.every(a => a.startTime === 0)).toBe(true);
+      // The pin runs on the branch the other shade cases cannot reach, so the
+      // no-read assertion is made here too.
+      expect(
+        computed.mock.calls.filter(
+          ([el]) => el instanceof Element && container.contains(el),
+        ),
+      ).toEqual([]);
+    } finally {
+      // @ts-expect-error — removing the stub restores jsdom's real surface
+      delete SVGElement.prototype.getAnimations;
+    }
+  });
+});