@astryxdesign/core 0.4.7 → 0.5.0-canary.32a62fd

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;
+    }
+  });
+});

package/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>
   );
 

package/src/StatusDot/StatusDot.doc.mjs

@@ -48,7 +48,10 @@ export const docs = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-statusdot', visualProps: ['variant']},
+      {className: 'astryx-status-dot', visualProps: ['variant']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},
     ],
   },
   usage: {
@@ -105,7 +108,10 @@ export const docsZh = {
   ],
   theming: {
     targets: [
-      {className: 'astryx-statusdot', visualProps: ['variant']},
+      {className: 'astryx-status-dot', visualProps: ['variant']},
+      // Still emitted beside the names above, so themes written against
+      // them keep working. Drop in the next major.
+      {className: 'astryx-statusdot', visualProps: ['variant'], deprecatedFor: 'status-dot'},
     ],
   },
   usage: {

package/src/StatusDot/StatusDot.test.tsx

@@ -189,3 +189,12 @@ describe('StatusDot', () => {
     });
   });
 });
+
+describe('StatusDot theme target names', () => {
+  it('renders the deprecated class beside the current one', () => {
+    render(<StatusDot variant="success" label="Online" />);
+    const dot = screen.getByRole('img', {name: 'Online'});
+    expect(dot).toHaveClass('astryx-status-dot');
+    expect(dot).toHaveClass('astryx-statusdot');
+  });
+});

package/src/StatusDot/StatusDot.tsx

@@ -200,7 +200,13 @@ export function StatusDot({
       role="img"
       aria-label={label}
       {...mergeProps(
-        themeProps('statusdot', {variant}),
+        themeProps(
+          'status-dot',
+          {variant},
+          // `statusdot` ran the compound name together; themes styling it keep
+          // working until the next major.
+          {legacyNames: ['statusdot']},
+        ),
         stylex.props(
           styles.base,
           variants[variant],

package/src/Stepper/Step.doc.mjs

@@ -0,0 +1,98 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+  name: 'Step',
+  subComponentOf: 'Stepper',
+  displayName: 'Step',
+  group: 'Stepper',
+  category: 'Navigation',
+  isHiddenFromOverview: true,
+  description:
+    'Individual step within a Stepper. Renders a progress-bar segment, an indicator, and a label with optional description. Progress (completed/active/not-started) is derived from the parent Stepper\u2019s activeStep and this step\u2019s step index.',
+  props: [
+    {
+      name: 'step',
+      type: 'number',
+      description:
+        'Zero-based index of this step. Used to derive progress (completed/active/not-started) relative to the parent activeStep.',
+      required: true,
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Step label text.',
+      required: true,
+    },
+    {
+      name: 'description',
+      type: 'string',
+      description:
+        'Optional description shown below the label for additional context.',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description:
+        'Content rendered below the label and description. Useful in vertical steppers for form fields or detailed step content.',
+    },
+    {
+      name: 'status',
+      type: "'accent' | 'success' | 'warning' | 'error'",
+      description:
+        'Semantic color for the step. Controls color only and maps to the global Astryx semantic tokens. Leave unset for the progress-derived default coloring.',
+    },
+    {
+      name: 'indicator',
+      type: "'auto' | 'number' | 'none' | ReactNode",
+      description:
+        "What to show as the step indicator. 'auto' shows a number until completed then a check, 'number' always shows a numbered badge, 'none' hides it, or pass any ReactNode (e.g. an Icon) for a fully custom indicator.",
+      slotElements: [{__element: 'Icon', props: {icon: 'check', size: 'sm'}}],
+      default: "'auto'",
+    },
+    {
+      name: 'isDisabled',
+      type: 'boolean',
+      description:
+        'Disables interaction and dims the step indicator and label.',
+      default: 'false',
+    },
+    {
+      name: 'isOptional',
+      type: 'boolean',
+      description:
+        'Marks the step as optional, appending an "Optional" affordance after the label.',
+      default: 'false',
+    },
+    {
+      name: 'endContent',
+      type: 'ReactNode',
+      description: 'Trailing content rendered at the end of the label row.',
+    },
+    {
+      name: 'density',
+      type: "'compact' | 'balanced' | 'spacious'",
+      description:
+        'Controls vertical padding of the step. Falls back to the stepper-level density when unset.',
+    },
+  ],
+  // A Step reads its progress from the parent Stepper's context and throws
+  // without one, so the preview needs a real Stepper around it. Without this
+  // block Step inherits Stepper's playground, which renders it bare and hands
+  // it the parent's `activeStep`. The wrapper is vertical because that is the
+  // orientation where one step shows its whole anatomy — indicator, label, and
+  // description stacked — and `step` matches the wrapper's `activeStep` so the
+  // preview opens on the current step rather than an inert upcoming one.
+  playground: {
+    wrapper: {
+      component: 'Stepper',
+      props: {activeStep: 1, orientation: 'vertical'},
+    },
+    defaults: {
+      step: 1,
+      label: 'Billing address',
+      description: 'Used for invoices and tax',
+    },
+  },
+};