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

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/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',
+    },
+  },
+};