Skip to content

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

TypeScript

refactor(core): draw the Spinner ring in SVG instead of canvas (#5408)

Cindy Zhang5da424d845b9
diff --git a/.changeset/spinner-svg-ring.md b/.changeset/spinner-svg-ring.md
new file mode 100644
index 0000000000..a4aa0d2f3c
--- /dev/null
+++ b/.changeset/spinner-svg-ring.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[refactor] Spinner: the ring is drawn in SVG instead of `<canvas>`. The arc and track take their colours from the cascade (`currentColor` for `shade="inherit"`), so nothing resolves a colour in JS: a colour change after mount now repaints the ring instead of leaving it stale until it remounts, and mounting spinners no longer costs a `getComputedStyle` each. Rings are pinned to the document timeline's origin, so spinners mounted at different times turn in phase. No API, geometry or theme-target change.
+
+@cixzhang
diff --git a/packages/core/src/Spinner/Spinner.test.tsx b/packages/core/src/Spinner/Spinner.test.tsx
index aa52bd4a86..52a8b86d01 100644
--- a/packages/core/src/Spinner/Spinner.test.tsx
+++ b/packages/core/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;
+ }
+ });
+});
diff --git a/packages/core/src/Spinner/Spinner.tsx b/packages/core/src/Spinner/Spinner.tsx
index b542a1d570..2809df2b10 100644
--- a/packages/core/src/Spinner/Spinner.tsx
+++ b/packages/core/src/Spinner/Spinner.tsx
@@ -4,7 +4,7 @@
/**
* @file Spinner.tsx
- * @input Uses React, StyleX, canvas rendering
+ * @input Uses React, StyleX, SVG rendering
* @output Exports Spinner component, SpinnerProps, SpinnerSize, SpinnerShade types
* @position Core implementation of spinner loading indicator
*
@@ -16,10 +16,9 @@
* - /packages/cli/assets/templates/blocks/components/Spinner/ (showcase blocks)
*/
-import {useEffect, useId, useRef, type ReactNode} from 'react';
+import {useId, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
-import {durationVars, spacingVars} from '../theme/tokens.stylex';
-import {useTheme} from '../theme/useTheme';
+import {colorVars, durationVars, spacingVars} from '../theme/tokens.stylex';
import type {BaseProps} from '../BaseProps';
import {Text} from '../Text/Text';
import {mergeProps} from '../utils';
@@ -29,10 +28,11 @@ import {themeProps} from '../utils/themeProps';
// Constants
// =============================================================================
-/** How much of the circle the active arc covers (as a fraction of 2π) */
-const SPREAD = 0.75;
-/** Where the active arc starts (as a fraction of 2π) */
-const START_POINT = 1.5;
+/**
+ * Fraction of the ring the moving arc covers. The canvas ring this replaces
+ * swept 135deg, not the 270deg its constant's comment claimed.
+ */
+const ARC_FRACTION = 0.375;
const SIZES = {
sm: {diameter: 10, border: 2},
@@ -41,6 +41,61 @@ const SIZES = {
xl: {diameter: 28, border: 4},
};
+/** `onMedia` keeps the 77/255 its token's `4D` hex suffix used to encode. */
+const TRACK_OPACITY = {
+ default: 1,
+ subtle: 1,
+ onMedia: 77 / 255,
+ inherit: 0.3,
+};
+
+/**
+ * Pin every ring's rotation to the document timeline's origin instead of its
+ * own start time, so spinners mounted seconds apart turn in phase.
+ *
+ * Setting `startTime` is exact where arithmetic on a clock read is not: a
+ * negative `animation-delay` computed at mount is only as good as the gap
+ * between reading the clock and the frame the animation starts in, which at
+ * 10x CPU throttling measured 116deg of drift.
+ *
+ * Rings are collected and pinned in one frame because `getAnimations()`
+ * resolves style and `startTime` dirties it again, so pinning them one at a
+ * time makes each mount re-force what the previous one invalidated — 53 style
+ * recalcs for 38 spinners against 19 batched.
+ */
+const pendingRings = new Set<SVGSVGElement>();
+let flushScheduled = false;
+
+function pinRingsToTimelineOrigin(): void {
+ flushScheduled = false;
+ const animations: Animation[] = [];
+ for (const svg of pendingRings) {
+ animations.push(...svg.getAnimations());
+ }
+ pendingRings.clear();
+ for (const animation of animations) {
+ animation.startTime = 0;
+ }
+}
+
+function syncRotationPhase(
+ svg: SVGSVGElement | null,
+): (() => void) | undefined {
+ // jsdom implements no Web Animations, and this runs in every consumer's
+ // component tests.
+ if (svg == null || typeof svg.getAnimations !== 'function') {
+ return undefined;
+ }
+ pendingRings.add(svg);
+ if (!flushScheduled) {
+ flushScheduled = true;
+ requestAnimationFrame(pinRingsToTimelineOrigin);
+ }
+ return () => {
+ pendingRings.delete(svg);
+ };
+}
+
// =============================================================================
// Animation
// =============================================================================
@@ -67,7 +122,7 @@ const styles = stylex.create({
overflow: 'hidden',
verticalAlign: 'middle',
},
- canvas: {
+ ring: {
backfaceVisibility: 'hidden',
display: 'block',
willChange: 'transform',
@@ -82,6 +137,33 @@ const styles = stylex.create({
animationName: rotation,
animationTimingFunction: 'linear',
},
+ circle: {
+ fill: 'none',
+ strokeLinecap: 'round',
+ },
+});
+
+const arcStyles = stylex.create({
+ default: {stroke: colorVars['--color-accent']},
+ subtle: {stroke: colorVars['--color-text-secondary']},
+ onMedia: {stroke: colorVars['--color-on-dark']},
+ inherit: {stroke: 'currentColor'},
+});
+
+const trackStyles = stylex.create({
+ default: {
+ stroke: colorVars['--color-track'],
+ strokeOpacity: TRACK_OPACITY.default,
+ },
+ subtle: {
+ stroke: colorVars['--color-track'],
+ strokeOpacity: TRACK_OPACITY.subtle,
+ },
+ onMedia: {
+ stroke: colorVars['--color-on-dark'],
+ strokeOpacity: TRACK_OPACITY.onMedia,
+ },
+ inherit: {stroke: 'currentColor', strokeOpacity: TRACK_OPACITY.inherit},
});
// =============================================================================
@@ -100,7 +182,7 @@ export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
* - 'sm': 10px diameter
* - 'md': 14px diameter
* - 'lg': 18px diameter
- * - 'xl': 36px diameter
+ * - 'xl': 28px diameter
* @default 'md'
*/
size?: SpinnerSize;
@@ -141,7 +223,7 @@ export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
// =============================================================================
/**
- * An animated loading indicator. Available in three sizes and two color shades.
+ * An animated loading indicator. Available in four sizes and four color shades.
*
* @example
* ```
@@ -164,97 +246,11 @@ export function Spinner({
ref,
...restProps
}: SpinnerProps) {
- const canvasRef = useRef<HTMLCanvasElement>(null);
- const {tokens: themeTokens} = useTheme();
-
- useEffect(() => {
- const canvas = canvasRef.current;
- if (canvas == null) {
- return;
- }
-
- const context = canvas.getContext('2d');
- if (!context) {
- return;
- }
-
- const {border, diameter} = SIZES[size];
- const pixelRatio = window.devicePixelRatio || 1;
-
- // Resolve colors from theme tokens (useTheme handles light/dark resolution).
- // - default → accent ring on a track tuned to body luminance
- // - subtle → secondary text color, less prominent
- // - onMedia → on-dark color, with a translucent track for photos/video
- // - inherit → the inherited currentColor, so the ring matches the parent's
- // resolved foreground (e.g. a button's variant text color)
- const inheritedColor =
- shade === 'inherit' ? getComputedStyle(canvas).color : null;
- const activeColor =
- shade === 'inherit'
- ? (inheritedColor as string)
- : shade === 'onMedia'
- ? themeTokens['--color-on-dark']
- : shade === 'subtle'
- ? themeTokens['--color-text-secondary']
- : themeTokens['--color-accent'];
- // Track derives from --color-on-dark for onMedia (with a 30% alpha so the
- // ring reads against arbitrary backgrounds) and from --color-track for the
- // body-luminance shades. For inherit, the track is the same currentColor
- // drawn at reduced alpha via globalAlpha (see below). All branches are
- // fully theme-driven.
- const backgroundColor =
- shade === 'inherit'
- ? (inheritedColor as string)
- : shade === 'onMedia'
- ? `${themeTokens['--color-on-dark']}4D`
- : themeTokens['--color-track'];
-
- const cssSize = diameter + border * 2;
-
- // Round to an even number of device pixels so the center stays on a whole
- // pixel (avoids rotation jitter); keep CSS size pinned to cssSize (#2732).
- const rawFrameSize = Math.round(cssSize * pixelRatio);
- const frameSize = rawFrameSize + (rawFrameSize % 2);
-
- const scale = frameSize / cssSize;
- const radius = (diameter / 2) * scale;
- const lineWidth = border * scale;
-
- canvas.height = canvas.width = frameSize;
- canvas.style.width = canvas.style.height = cssSize + 'px';
-
- context.lineCap = 'round';
- context.lineWidth = lineWidth;
-
- const center = frameSize / 2;
-
- // Background circle (full ring, faded). For the inherit shade the track is
- // the same currentColor as the arc, so fade it via globalAlpha (the
- // computed color is an opaque rgb() string with no alpha channel to tweak).
- context.beginPath();
- context.arc(center, center, radius, 0, 2 * Math.PI);
- context.strokeStyle = backgroundColor;
- if (shade === 'inherit') {
- context.globalAlpha = 0.3;
- }
- context.stroke();
- context.globalAlpha = 1;
-
- // Active arc (partial ring, colored)
- context.beginPath();
- context.arc(
- center,
- center,
- radius,
- START_POINT * Math.PI,
- ((START_POINT + SPREAD) % 2) * Math.PI,
- );
- context.strokeStyle = activeColor;
- context.stroke();
- }, [shade, size, themeTokens]);
-
const {border, diameter} = SIZES[size];
const frameSize = diameter + border * 2;
+ const center = frameSize / 2;
+ const circumference = Math.PI * diameter;
+ const arcLength = circumference * ARC_FRACTION;
const hasLabel = label != null;
const labelId = useId();
@@ -283,7 +279,30 @@ export function Spinner({
hasLabel ? undefined : className,
{...(hasLabel ? {} : style), width: frameSize, height: frameSize},
)}>
- <canvas ref={canvasRef} {...stylex.props(styles.canvas)} />
+ <svg
+ ref={syncRotationPhase}
+ width={frameSize}
+ height={frameSize}
+ viewBox={`0 0 ${frameSize} ${frameSize}`}
+ aria-hidden="true"
+ {...stylex.props(styles.ring)}>
+ <circle
+ cx={center}
+ cy={center}
+ r={diameter / 2}
+ strokeWidth={border}
+ {...stylex.props(styles.circle, trackStyles[shade])}
+ />
+ <circle
+ cx={center}
+ cy={center}
+ r={diameter / 2}
+ strokeWidth={border}
+ strokeDasharray={`${arcLength} ${circumference - arcLength}`}
+ transform={`rotate(-90 ${center} ${center})`}
+ {...stylex.props(styles.circle, arcStyles[shade])}
+ />
+ </svg>
</span>
);