Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
30.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file Spinner.test.tsx
 * @input Uses vitest, @testing-library/react, Spinner component
 * @output Unit tests for Spinner component behavior
 * @position Testing; validates Spinner.tsx implementation
 *
 * SYNC: When Spinner.tsx changes, update tests to match new behavior
 */

import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {createRef, Profiler, StrictMode} from 'react';
import {render, screen} from '@testing-library/react';
import {SPINNER_ARC_FRACTION} from './spinnerRotor';
import {Spinner} from './Spinner';
import {SpinnerOwnerContext} from './SpinnerOwnerContext';
import {InternationalizationProvider} from '../i18n';
import {defineTheme} from '../theme/defineTheme';
import {generateThemeCSS} from '../theme/generateThemeRules';
import {getAllInjectedCss} from '../__tests__/forcedColors';
import {declaredValue} from '../__tests__/stylexDeclarations';

const {announce} = vi.hoisted(() => ({announce: vi.fn()}));
vi.mock('../hooks/useAnnounce', () => ({useAnnounce: () => announce}));

beforeEach(() => {
  announce.mockClear();
  vi.spyOn(document, 'readyState', 'get').mockReturnValue('complete');
});

afterEach(() => vi.restoreAllMocks());

/** 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;

/** The track's svg and the arc's svg, in that order. */
const rings = (testId = 'spinner') => [
  ...screen.getByTestId(testId).querySelectorAll('svg'),
];

/** The box that turns: the arc's svg sits inside it, the track's does not. */
const rotor = (testId = 'spinner') =>
  rings(testId)[1].parentElement as HTMLSpanElement;

const circles = (testId = 'spinner') => {
  const [track, arc] = [
    ...screen.getByTestId(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" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
    expect(announce).toHaveBeenCalledExactlyOnceWith('Loading', 'polite');
  });

  it('renders with size sm', () => {
    render(<Spinner size="sm" data-testid="spinner" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
  });

  it('renders with size md', () => {
    render(<Spinner size="md" data-testid="spinner" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
  });

  it('renders with size lg', () => {
    render(<Spinner size="lg" data-testid="spinner" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
  });

  it('renders with shade default', () => {
    render(<Spinner shade="default" data-testid="spinner" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
  });

  it('renders with shade onMedia', () => {
    render(<Spinner shade="onMedia" data-testid="spinner" />);
    expect(screen.getByTestId('spinner')).toBeInTheDocument();
  });

  it('renders with shade inherit', () => {
    render(<Spinner shade="inherit" data-testid="spinner" />);
    const spinner = screen.getByTestId('spinner');
    expect(spinner).toBeInTheDocument();
    expect(spinner).toHaveAttribute('data-shade', 'inherit');
  });

  it('localizes the default assistive label through the i18n catalog', () => {
    render(
      <InternationalizationProvider
        locale="fr"
        overrides={{fr: {'@astryx.spinner.loading': 'Chargement'}}}>
        <Spinner data-testid="spinner" />
      </InternationalizationProvider>,
    );
    expect(screen.getByTestId('spinner')).toHaveAttribute(
      'aria-label',
      'Chargement',
    );
    expect(announce).toHaveBeenCalledExactlyOnceWith('Chargement', 'polite');
  });

  it('keeps an explicit aria-label over the localized default', () => {
    render(
      <InternationalizationProvider
        locale="fr"
        overrides={{fr: {'@astryx.spinner.loading': 'Chargement'}}}>
        <Spinner aria-label="Veuillez patienter" data-testid="spinner" />
      </InternationalizationProvider>,
    );
    expect(screen.getByTestId('spinner')).toHaveAttribute(
      'aria-label',
      'Veuillez patienter',
    );
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Veuillez patienter',
      'polite',
    );
  });

  it('does not duplicate a visible string label as aria-label', () => {
    render(<Spinner label="Fetching data" data-testid="spinner" />);
    const image = screen.getByRole('progressbar', {name: 'Fetching data'});
    expect(image).not.toHaveAttribute('aria-label');
    expect(image).toHaveAttribute('aria-labelledby');
  });

  it('uses explicit aria-label over string label', () => {
    render(
      <Spinner
        label="Loading..."
        aria-label="Please wait"
        data-testid="spinner"
      />,
    );
    expect(screen.getByRole('progressbar')).toHaveAttribute(
      'aria-label',
      'Please wait',
    );
  });

  it('renders label content below the spinner', () => {
    render(<Spinner label="Loading..." data-testid="spinner" />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('renders ReactNode label', () => {
    render(
      <Spinner
        label={<span data-testid="custom-label">Custom content</span>}
        aria-label="Loading"
        data-testid="spinner"
      />,
    );
    expect(screen.getByTestId('custom-label')).toBeInTheDocument();
  });

  it('defaults aria-label to "Loading" for ReactNode label without explicit aria-label', () => {
    render(<Spinner label={<span>Rich content</span>} data-testid="spinner" />);
    expect(screen.getByRole('progressbar')).toHaveAttribute(
      'aria-label',
      'Loading',
    );
  });

  it('accepts data-testid', () => {
    render(<Spinner data-testid="my-spinner" />);
    expect(screen.getByTestId('my-spinner')).toBeInTheDocument();
  });

  it('renders as an inline element (span)', () => {
    render(<Spinner data-testid="spinner" />);
    const spinner = screen.getByTestId('spinner');
    expect(spinner.tagName.toLowerCase()).toBe('span');
  });

  // The box has always been sized by an inline width/height written after the
  // caller's `style`, so the component's own size wins over a `style={{width}}`
  // passed in. Making the geometry themeable changed what that value is made
  // of — a composed var rather than a number — and deliberately not where it is
  // written: moving the sizing into a rule would have handed a caller's inline
  // width a precedence over the box it has never had. This pins the precedence
  // itself, which is the part a consumer could be depending on.
  describe('box sizing', () => {
    it.each(Object.entries(SIZES))(
      'falls back to the %s frame where no stylesheet has declared the var',
      (size, {diameter, border}) => {
        render(
          <Spinner size={size as keyof typeof SIZES} data-testid="spinner" />,
        );
        const box = screen.getByTestId('spinner');
        const expected = `var(--_spinner-box-size, ${diameter + border * 2}px)`;
        expect(box.style.width).toBe(expected);
        expect(box.style.height).toBe(expected);
      },
    );

    it('keeps its own size over a width the caller passes in style', () => {
      render(
        <Spinner
          size="xl"
          style={{width: 999, height: 999, opacity: 0.5}}
          data-testid="spinner"
        />,
      );
      const box = screen.getByTestId('spinner');
      expect(box.style.width).toBe('var(--_spinner-box-size, 36px)');
      expect(box.style.height).toBe('var(--_spinner-box-size, 36px)');
      // Everything else the caller passed still applies — only the two
      // properties the box owns are taken back.
      expect(box.style.opacity).toBe('0.5');
    });
  });

  // The themed geometry resolves in the cascade — jsdom implements no layout
  // and no custom-property registration, so no test here can reach what a
  // theme actually draws; that is verified in a browser and the numbers are in
  // the PR. What IS a contract a unit test can hold is the routing: a theme
  // writes an override against the documented key, and it has to come out on
  // the selector the component reads from.
  describe('a theme reaches the spinner through its public vars', () => {
    const cssFor = (
      components: Parameters<typeof defineTheme>[0]['components'],
    ) =>
      generateThemeCSS(defineTheme({name: 'spinner-theming', components}))
        .component;

    it('scopes a themed size to that size variant', () => {
      // Asserting the whole rule, not just the declaration: the same var on
      // the bare `.astryx-spinner` would resize every size at once, which is
      // the bug a size-variant key exists to avoid.
      expect(
        cssFor({spinner: {'size:xl': {'--spinner-diameter': '2.5rem'}}}),
      ).toContain(
        '.astryx-spinner[data-size="xl"] {\n    --spinner-diameter: 2.5rem;',
      );
    });

    it('scopes a themed color to that shade variant', () => {
      expect(
        cssFor({
          spinner: {'shade:subtle': {'--spinner-track-color': 'transparent'}},
        }),
      ).toContain(
        '.astryx-spinner[data-shade="subtle"] {\n    --spinner-track-color: transparent;',
      );
    });

    it('lets the base target set a value for every size and shade', () => {
      expect(
        cssFor({spinner: {base: {'--spinner-color': 'var(--color-brand)'}}}),
      ).toContain(
        '.astryx-spinner {\n    --spinner-color: var(--color-brand);',
      );
    });

    it('scopes a themed arc fraction to that size variant (#5819)', () => {
      expect(
        cssFor({spinner: {'size:xl': {'--spinner-arc-fraction': '0.75'}}}),
      ).toContain(
        '.astryx-spinner[data-size="xl"] {\n    --spinner-arc-fraction: 0.75;',
      );
    });
  });
});

describe('Spinner ring', () => {
  it('draws the ring in SVG', () => {
    render(<Spinner data-testid="spinner" />);
    // The track and the arc each have their own svg: the track stays put and
    // the arc's svg sits in the rotor that turns.
    const [trackSvg, arcSvg] = rings();
    expect(trackSvg.querySelectorAll('circle')).toHaveLength(1);
    expect(arcSvg.querySelectorAll('circle')).toHaveLength(1);
    expect(trackSvg.parentElement).toBe(screen.getByTestId('spinner'));
    expect(rotor().parentElement).toBe(screen.getByTestId('spinner'));
    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" />,
      );
      // No viewBox: one user unit is one px, so the attributes below mean px.
      // They are the no-stylesheet fallback; CSS sizes the frame from the box.
      // The track's are zero, so without a stylesheet the arc alone fills
      // the box rather than sitting beside a second disc.
      const frame = diameter + border * 2;
      const [track, arc] = rings();
      for (const svg of [track, arc]) {
        expect(svg.getAttribute('viewBox')).toBeNull();
      }
      expect(Number(arc.getAttribute('width'))).toBe(frame);
      expect(Number(arc.getAttribute('height'))).toBe(frame);
      expect(Number(track.getAttribute('width'))).toBe(0);
      expect(Number(track.getAttribute('height'))).toBe(0);
      for (const c of [circles().track, circles().arc]) {
        expect(c.getAttribute('cx')).toBe('50%');
        expect(c.getAttribute('cy')).toBe('50%');
        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();
    },
  );

  // The regression this file could not have caught: #5214 made the RING
  // themeable and left the frame at the size's own constant, so a themed
  // diameter left the svg larger than the box it sits in. The overflowing grid
  // item then aligned to start rather than centre — measured in Chromium at
  // 1.5 to 3.3px off across the four sizes. Nothing asserted the two agreed,
  // because nothing tied them.
  it('sizes the frame from CSS, not from the size constant', () => {
    render(<Spinner data-testid="spinner" />);
    // No viewBox, and the circles centre on the box rather than on a centre
    // in user units — together that is what lets CSS size the frame from
    // `--_spinner-box-size`, the same composed var the span is sized from, so
    // a themed diameter moves both. The px attributes remain as the
    // no-stylesheet fallback and CSS outranks them whenever one is present.
    for (const svg of rings()) {
      expect(svg.getAttribute('viewBox')).toBeNull();
    }
    for (const c of [circles().track, circles().arc]) {
      expect(c.getAttribute('cx')).toBe('50%');
      expect(c.getAttribute('cy')).toBe('50%');
    }
  });

  it('starts the arc at twelve o’clock', () => {
    render(<Spinner data-testid="spinner" />);
    // A CSS rotation about the shape's own box, not an SVG transform about a
    // centre in user units — the centre is `50%`, so there is no user-unit
    // number to name, and the offset has to survive a themed diameter.
    expect(circles().arc.getAttribute('transform')).toBeNull();
  });

  // The authored dash is the size's own absolute pattern, and stays that way:
  // it is what a render with no stylesheet draws, and it is byte-for-byte the
  // pattern this component drew before the geometry became themeable. Scaling
  // with a themed diameter is the rule's job — it composes the same two
  // lengths out of the resolved diameter — and deliberately not `pathLength`'s,
  // which rescales against the path length the UA measures on its own
  // approximation of the circle and shortens the default arc by 0.64%.
  it.each(Object.entries(SIZES))(
    'leaves the %s arc its own absolute dash, with no pathLength',
    (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(arc.getAttribute('pathLength')).toBeNull();
      // The track is a full ring, so it needs neither.
      expect(track.getAttribute('pathLength')).toBeNull();
    },
  );

  // 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(HTMLElement.prototype).not.toHaveProperty('getAnimations');
    const raf = vi.spyOn(window, 'requestAnimationFrame');
    render(<Spinner data-testid="spinner" />);
    expect(ring()).not.toBeNull();
    expect(raf).not.toHaveBeenCalled();
  });

  it('draws the arc at the shared rotor fraction', () => {
    render(<Spinner size="xl" data-testid="spinner" />);
    const arc = rotor().querySelector('circle');
    const circumference = Math.PI * 28;
    expect(arc?.getAttribute('stroke-dasharray')).toBe(
      `${circumference * SPINNER_ARC_FRACTION} ${circumference * (1 - SPINNER_ARC_FRACTION)}`,
    );
  });

  // The ring turns on the compositor: only the rotor moves, and only by
  // `transform`, a property the browser animates without the main thread. A
  // paint animation such as `stroke-dashoffset` would repaint the arc on the
  // main thread every frame. It would stop while a script runs;
  // `SpinnerMotion.a11y.chromium.spec.ts` holds the frames.
  it('turns the arc by rotating the rotor, with nothing else animated', () => {
    render(<Spinner data-testid="spinner" />);
    const css = getAllInjectedCss();
    const name = declaredValue(rotor(), 'animation-name');
    expect(name).toBeTruthy();
    expect(declaredValue(rotor(), 'animation-timing-function')).toBe('linear');
    expect(declaredValue(rotor(), 'animation-iteration-count')).toBe(
      'infinite',
    );
    // Its keyframes turn it by whole turns, by transform and nothing else.
    // (jsdom's CSSOM lowercases the name in the rule but not in the at-rule.)
    const keyframes = new RegExp(
      `@keyframes ${name}\\s*\\{([\\s\\S]*?\\})\\s*\\}`,
      'i',
    ).exec(css)?.[1];
    expect(keyframes).toMatch(/rotate\(0deg\)/);
    expect(keyframes).not.toMatch(/stroke|width|height|top|left/);
    // One iteration holds many turns, and its duration is that many periods,
    // so each turn still takes one period. Chromium wakes the main thread at
    // each iteration boundary while React listens for `animationiteration`.
    const endDegrees = Math.max(
      ...[...(keyframes ?? '').matchAll(/rotate\((\d+)deg\)/g)].map(m =>
        Number(m[1]),
      ),
    );
    const turns = endDegrees / 360;
    expect(Number.isInteger(turns)).toBe(true);
    expect(turns).toBeGreaterThanOrEqual(100);
    const duration = declaredValue(rotor(), 'animation-duration') ?? '';
    expect(duration).toMatch(
      new RegExp(
        `^calc\\(var\\(--_astryx-pre-tempo-duration-slow-min,.*\\) \\* ${turns}\\)$`,
      ),
    );
    // Its own compositing layer from the first frame.
    expect(declaredValue(rotor(), 'will-change')).toBe('transform');
    // Nothing else in the spinner animates: not the arc, not the track.
    for (const el of [
      ...screen.getByTestId('spinner').querySelectorAll('svg, circle'),
    ]) {
      expect(declaredValue(el, 'animation-name')).toBeNull();
    }
    expect(css).not.toMatch(/@keyframes[^{]*\{[^}]*stroke-dashoffset/);
  });

  it('renders once and never again while the ring turns', () => {
    vi.useFakeTimers({
      toFake: ['requestAnimationFrame', 'setTimeout', 'setInterval'],
    });
    let renders = 0;
    const onRender = () => {
      renders += 1;
    };
    try {
      render(
        <Profiler id="spinner" onRender={onRender}>
          {Array.from({length: 20}, (_, i) => (
            <Spinner key={i} data-testid={`spinner-${i}`} />
          ))}
        </Profiler>,
      );
      expect(renders).toBe(1);
      // Ten seconds of frames and timers: the motion is CSS only.
      vi.advanceTimersByTime(10_000);
      expect(renders).toBe(1);
    } finally {
      vi.useRealTimers();
    }
  });

  it('keeps the track out of the rotor', () => {
    render(<Spinner data-testid="spinner" />);
    expect(rotor().contains(circles().arc)).toBe(true);
    expect(rotor().contains(circles().track)).toBe(false);
    expect(rotor().getAttribute('aria-hidden')).toBe('true');
  });

  it('pins every ring to the timeline origin in a single frame', () => {
    const animations: {startTime: number | null}[] = [];
    const getAnimations = vi.fn(function (this: HTMLElement) {
      const a = {startTime: null as number | null};
      animations.push(a);
      return [a];
    });
    Object.defineProperty(HTMLElement.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} data-testid={`spinner-${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 rotation lives on the rotor itself, the element the ref sits on.
      expect(getAnimations.mock.contexts).toEqual(
        Array.from({length: 5}, (_, i) => rotor(`spinner-${i}`)),
      );
      // 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 HTMLElement.prototype.getAnimations;
    }
  });
});

describe('geometry var registration', () => {
  /** The shape `registerSpinnerVars` passes; jsdom implements no real one. */
  type Descriptor = {
    name: string;
    syntax: string;
    inherits: boolean;
    initialValue: string;
  };
  const stubRegisterProperty = (fn: (d: Descriptor) => void) => {
    (
      CSS as unknown as {registerProperty: (d: Descriptor) => void}
    ).registerProperty = fn;
  };

  afterEach(() => {
    delete (CSS as unknown as {registerProperty?: unknown}).registerProperty;
    vi.resetModules();
  });

  it('registers when the module is imported, not when a spinner mounts', async () => {
    // Registering an inherited property with an `initial-value` invalidates
    // style for the whole document. A spinner mounts onto a page that has
    // already rendered, so paying it there is paying it on the full tree —
    // measured at 29ms against 12ms on an 11k-element page. At import the page
    // is whatever has rendered so far, which for a bundle in the head is
    // nothing. This pins the timing: it fails if the call moves back into a
    // ref callback, an effect, or the component body.
    const registerProperty = vi.fn<(d: Descriptor) => void>();
    stubRegisterProperty(registerProperty);

    vi.resetModules();
    await import('./Spinner');

    expect(registerProperty.mock.calls.map(([d]) => d.name)).toEqual([
      '--_spinner-ring-diameter',
      '--_spinner-ring-stroke',
    ]);
    // Both are `<length>` with an initial value, which is what makes a themed
    // `0` mean `0px` inside the `calc()` rather than poisoning it.
    for (const [descriptor] of registerProperty.mock.calls) {
      expect(descriptor.syntax).toBe('<length>');
      expect(descriptor.inherits).toBe(true);
      expect(descriptor.initialValue).toBe('0px');
    }
  });

  it('survives a second evaluation, and does not need the DOM', async () => {
    // Two copies of the package on one page, or a fast-refresh re-evaluation:
    // registerProperty throws on a duplicate rather than replacing, and the
    // existing registration is this same one.
    const registerProperty = vi.fn<(d: Descriptor) => void>(() => {
      throw new Error('InvalidModificationError');
    });
    stubRegisterProperty(registerProperty);

    vi.resetModules();
    await expect(import('./Spinner')).resolves.toBeDefined();
    expect(registerProperty).toHaveBeenCalledTimes(2);
  });
});

describe('shared announcement lifecycle', () => {
  it('announces once per appearance, including a new appearance with the same words', () => {
    const view = (loading: boolean) => (
      <StrictMode>{loading && <Spinner label="Loading results" />}</StrictMode>
    );
    const {rerender} = render(view(false));
    expect(announce).not.toHaveBeenCalled();

    rerender(view(true));
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Loading results',
      'polite',
    );
    rerender(view(true));
    expect(announce).toHaveBeenCalledTimes(1);

    rerender(view(false));
    rerender(view(true));
    expect(announce.mock.calls).toEqual([
      ['Loading results', 'polite'],
      ['Loading results', 'polite'],
    ]);
  });

  it('announces when the label changes', () => {
    const {rerender} = render(<Spinner label="Loading results" />);

    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Loading results',
      'polite',
    );

    rerender(<Spinner label="Saving results" />);

    expect(announce.mock.calls).toEqual([
      ['Loading results', 'polite'],
      ['Saving results', 'polite'],
    ]);
  });

  it('stays silent with a caller role other than progressbar, as it shipped (AST-017 FR53)', () => {
    const {rerender} = render(<Spinner aria-label="Searching" role="img" />);
    rerender(<Spinner aria-label="Searching again" role="img" />);
    expect(
      screen.getByRole('img', {name: 'Searching again'}),
    ).toBeInTheDocument();
    expect(announce).not.toHaveBeenCalled();

    rerender(<Spinner aria-label="Searching once more" />);
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Searching once more',
      'polite',
    );
  });

  it('stays silent inside a Core owner, and announces once it stands alone (AST-086 FR8)', () => {
    const {rerender} = render(
      <SpinnerOwnerContext value={true}>
        <Spinner aria-label="Loading results" />
      </SpinnerOwnerContext>,
    );
    expect(
      screen.getByRole('progressbar', {name: 'Loading results'}),
    ).toBeInTheDocument();
    expect(announce).not.toHaveBeenCalled();

    rerender(
      <SpinnerOwnerContext value={false}>
        <Spinner aria-label="Loading results" />
      </SpinnerOwnerContext>,
    );
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Loading results',
      'polite',
    );
  });

  it('stays silent when app code hides it with aria-hidden', () => {
    const {rerender} = render(<Spinner label="Loading events" aria-hidden />);
    rerender(<Spinner label="Loading events" aria-hidden />);
    expect(screen.queryByRole('progressbar')).toBeNull();
    expect(announce).not.toHaveBeenCalled();
  });

  it('announces a stacked rich label word by word, not run together (AST-086 FR7)', () => {
    const {rerender} = render(<div />);
    rerender(
      <Spinner
        aria-label="Fetching data"
        label={
          <div style={{display: 'flex', flexDirection: 'column'}}>
            <span>Fetching data</span>
            <span>This may take a moment</span>
          </div>
        }
      />,
    );
    expect(announce).toHaveBeenCalledWith(
      'Fetching data This may take a moment',
      'polite',
    );
  });

  it('keeps directly hidden and ancestor-hidden indicators silent', () => {
    render(
      <>
        <Spinner aria-hidden="true" role={undefined} />
        <Spinner aria-hidden="true" label="Decorative label" />
        <div aria-hidden="true">
          <Spinner />
        </div>
        <div hidden>
          <Spinner />
        </div>
      </>,
    );
    expect(announce).not.toHaveBeenCalled();
  });

  it('leaves announcements to existing live containers', () => {
    const view = (loading: boolean) => (
      <>
        <div role="log">{loading && <Spinner />}</div>
        <div aria-live="polite">{loading && <Spinner />}</div>
        <div aria-live="assertive">{loading && <Spinner />}</div>
      </>
    );
    const {rerender} = render(view(false));
    rerender(view(true));
    expect(announce).not.toHaveBeenCalled();
  });

  it('preserves refs when switching between labeled and unlabeled roots', () => {
    const ref = createRef<HTMLSpanElement>();
    const {rerender, unmount} = render(
      <Spinner ref={ref} data-testid="spinner" />,
    );
    expect(ref.current).toBe(screen.getByTestId('spinner'));
    rerender(
      <Spinner ref={ref} label="Loading results" data-testid="spinner" />,
    );
    expect(ref.current).toBe(screen.getByTestId('spinner'));
    expect(announce).toHaveBeenLastCalledWith('Loading results', 'polite');
    unmount();
    expect(ref.current).toBeNull();
  });

  it('stays silent during page load and announces a later text change', () => {
    const readyState = vi
      .spyOn(document, 'readyState', 'get')
      .mockReturnValue('loading');
    const {rerender} = render(<Spinner aria-label="Loading records" />);
    expect(announce).not.toHaveBeenCalled();
    readyState.mockReturnValue('complete');
    rerender(<Spinner aria-label="Loading records" />);
    expect(announce).not.toHaveBeenCalled();
    rerender(<Spinner aria-label="Saving records" />);
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Saving records',
      'polite',
    );
  });

  it('announces rendered ReactNode text and changes without changing the progressbar name', () => {
    function LoadingLabel() {
      return (
        <span>
          <strong>Fetch</strong>ing records
          <span aria-hidden="true"> decoration</span>
          <span hidden> hidden</span>
        </span>
      );
    }
    const {rerender} = render(
      <Spinner label={<LoadingLabel />} aria-label="Please wait" />,
    );
    expect(screen.getByRole('progressbar')).toHaveAccessibleName('Please wait');
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Fetching records',
      'polite',
    );
    rerender(<Spinner label={<LoadingLabel />} aria-label="Please wait" />);
    expect(announce).toHaveBeenCalledTimes(1);
    rerender(
      <Spinner label={<em>Saving records</em>} aria-label="Please wait" />,
    );
    expect(screen.getByRole('progressbar')).toHaveAccessibleName('Please wait');
    expect(announce.mock.calls).toEqual([
      ['Fetching records', 'polite'],
      ['Saving records', 'polite'],
    ]);
  });

  it('announces the aria-labelledby name and its updates instead of the default', () => {
    const view = (name: string) => (
      <>
        <Spinner aria-labelledby="upload-label" aria-label="Please wait" />
        <span id="upload-label">{name}</span>
      </>
    );
    const {rerender} = render(view('Uploading files'));
    expect(screen.getByRole('progressbar')).toHaveAccessibleName(
      'Uploading files',
    );
    expect(announce).toHaveBeenCalledExactlyOnceWith(
      'Uploading files',
      'polite',
    );
    rerender(view('Uploading files'));
    expect(announce).toHaveBeenCalledTimes(1);
    rerender(view('Saving files'));
    expect(screen.getByRole('progressbar')).toHaveAccessibleName(
      'Saving files',
    );
    expect(announce.mock.calls).toEqual([
      ['Uploading files', 'polite'],
      ['Saving files', 'polite'],
    ]);
  });

  it('uses the accessible-name fallback for a textless ReactNode label', () => {
    render(<Spinner label={<span aria-hidden="true">Decoration</span>} />);
    expect(announce).toHaveBeenCalledExactlyOnceWith('Loading', 'polite');
  });
});