@astryxdesign/core 0.4.7 → 0.5.0-canary.009bcb3

package/src/Slider/Slider.tsx

@@ -17,11 +17,13 @@
  */
 
 import {
+  useEffect,
   useId,
   useMemo,
   useRef,
   useState,
   useCallback,
+  type FocusEvent,
   type KeyboardEvent,
   type PointerEvent,
 } from 'react';
@@ -40,13 +42,18 @@ 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 {
+  getInteractionModality,
+  trackInteractionModality,
+} from '../utils/interactionModality';
 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
 // =============================================================================
@@ -492,6 +499,36 @@ export function Slider({ref, ...props}: SliderProps) {
   const draggingThumbRef = useRef<number | null>(null);
   const [draggingThumb, setDraggingThumb] = useState<number | null>(null);
 
+  // A thumb is a div[role="slider"], and `handlePointerDown` focuses it from
+  // script after preventDefault — which Chromium treats as focus-visible, so
+  // dragging with a mouse drew the keyboard ring (measured: `:focus-visible`
+  // true on pointerdown). Gate the ring on how the user last interacted; the
+  // CSS condition stays `:focus-visible`, this only narrows it.
+  const [keyboardFocusThumb, setKeyboardFocusThumb] = useState<number | null>(
+    null,
+  );
+
+  useEffect(() => {
+    trackInteractionModality();
+  }, []);
+
+  const handleThumbFocus = useCallback(
+    (thumbIndex: number, _e: FocusEvent<HTMLDivElement>) => {
+      // A disabled thumb draws no ring even when it stays focusable for its
+      // reason tooltip, so there is nothing to track for one.
+      setKeyboardFocusThumb(
+        !isDisabled && getInteractionModality() === 'keyboard'
+          ? thumbIndex
+          : null,
+      );
+    },
+    [isDisabled],
+  );
+
+  const handleThumbBlur = useCallback((_e: FocusEvent<HTMLDivElement>) => {
+    setKeyboardFocusThumb(null);
+  }, []);
+
   // Disabled-reason tooltip. This is a *separate* useTooltip instance from the
   // per-thumb value bubble (the `<Tooltip>` component below): it anchors to the
   // track container and fires on hover/focus of the whole control. Disabled
@@ -678,6 +715,10 @@ export function Slider({ref, ...props}: SliderProps) {
         const thumbs = track.querySelectorAll<HTMLElement>('[role="slider"]');
         thumbs[thumbIndex]?.focus();
       }
+      // Also clear it explicitly: focusing an already-focused thumb fires no
+      // focus event, so a thumb the user had tabbed to would keep its ring
+      // through the drag.
+      setKeyboardFocusThumb(null);
 
       if (
         typeof (e.currentTarget as HTMLElement).setPointerCapture === 'function'
@@ -716,6 +757,13 @@ export function Slider({ref, ...props}: SliderProps) {
       if (isDisabled) {
         return;
       }
+      // Unlike a text field, a thumb has no caret to show where input is
+      // going, so a keypress after a mouse drag must bring the ring back.
+      // Ask the utility rather than assuming: a modifier chord (⌘R, ⌃C) is
+      // not navigation and must not re-ring a thumb the mouse is holding.
+      if (getInteractionModality() === 'keyboard') {
+        setKeyboardFocusThumb(thumbIndex);
+      }
       const currentVal = values[thumbIndex];
       let newVal: number;
 
@@ -842,6 +890,8 @@ export function Slider({ref, ...props}: SliderProps) {
         aria-labelledby={!isRange ? labelID : undefined}
         aria-describedby={ariaDescribedBy}
         onKeyDown={e => handleKeyDown(thumbIndex, e)}
+        onFocus={e => handleThumbFocus(thumbIndex, e)}
+        onBlur={handleThumbBlur}
         {...mergeProps(
           themeProps('slider-thumb', {
             orientation,
@@ -853,7 +903,9 @@ export function Slider({ref, ...props}: SliderProps) {
               ? styles.thumbHorizontal
               : rtlStyles.centerInline('50%'),
             !isDisabled && styles.thumbHover,
-            !isDisabled && focusOutlineStyles.focusVisible,
+            !isDisabled &&
+              keyboardFocusThumb === thumbIndex &&
+              focusOutlineStyles.focusVisible,
             isDisabled && styles.thumbDisabled,
           ),
           undefined,
@@ -964,7 +1016,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;
+    }
+  });
+});

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],