@astryxdesign/core 0.0.0-bootstrap.0 → 0.1.0-canary.08d4cf4

package/src/Slider/index.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from Slider component files
+ * @output Exports Slider and its types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/Slider/Slider.doc.mjs
+ */
+
+export {Slider} from './Slider';
+export type {
+  SliderProps,
+  SliderBaseProps,
+  SliderSingleProps,
+  SliderRangeProps,
+} from './Slider';

package/src/Spinner/Spinner.doc.mjs

@@ -0,0 +1,130 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'Spinner',
+  displayName: 'Spinner',
+  category: 'Feedback & Status',
+  keywords: ["spinner","loader","loading","circular","progress","spin","activity","busy","indeterminate"],
+  props: [
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: 'Spinner size (10px, 14px, 18px).',
+      default: "'md'",
+    },
+    {
+      name: 'shade',
+      type: "'default' | 'onMedia' | 'subtle' | 'inherit'",
+      description: 'Color shade for light or dark backgrounds.',
+      default: "'default'",
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description:
+        'Visible content below the spinner. String labels auto-set aria-label.',
+    },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description:
+        'Accessible name for screen readers. Defaults to label (if string) or "Loading".',
+      default: "'Loading'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}.',
+    },
+  ],  theming: {
+    targets: [
+      {className: 'astryx-spinner', visualProps: ['size', 'shade']},
+    ],
+  },
+  usage: {
+    description:
+      'An animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.',
+    bestPractices: [
+      {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+      {guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
+      {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+      {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'Spinner',
+  displayName: 'Spinner',
+  props: [
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '旋转器尺寸（10px、14px、18px）。',
+      default: "'md'",
+    },
+    {
+      name: 'shade',
+      type: "'default' | 'onMedia' | 'subtle' | 'inherit'",
+      description: '浅色或深色背景的颜色色调。',
+      default: "'default'",
+    },
+    {
+      name: 'label',
+      type: 'ReactNode',
+      description: '旋转器下方的可见内容。字符串标签自动设置 aria-label。',
+    },
+    {
+      name: 'aria-label',
+      type: 'string',
+      description: '屏幕阅读器的无障碍名称。默认为 label（如果是字符串）或 "Loading"。',
+      default: "'Loading'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX 样式，用于布局自定义（边距、定位、尺寸）。必须是 stylex.create() 的值，而非内联样式对象如 style={{}}。',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-spinner', visualProps: ['size', 'shade']},
+    ],
+  },
+  usage: {
+    description:
+      'An animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.',
+    bestPractices: [
+      {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+      {guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
+      {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+      {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  usage: {
+    description:
+      'An animated loading indicator for processes with unknown duration, such as data fetching or form submission. Supports visible labels, multiple sizes, and a dark background variant. For content with known dimensions, use Skeleton instead.',
+    bestPractices: [
+      {guidance: true, description: 'Provide a meaningful label to describe what is loading for screen reader users.'},
+      {guidance: true, description: 'Use the "onMedia" shade when placed on dark or accent-colored backgrounds.'},
+      {guidance: false, description: 'Use for content areas with known dimensions; use Skeleton to preserve layout instead.'},
+      {guidance: false, description: 'Stack multiple spinners in the same view; use one to represent the overall loading state.'},
+    ],
+  },
+  propDescriptions: {
+    size: 'Spinner size (10px, 14px, 18px).',
+    shade: 'Color shade for light or dark backgrounds.',
+    label: 'Visible content below spinner. String auto-sets aria-label.',
+    'aria-label': 'A11y name for screen readers. Defaults to label or "Loading".',
+    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value, not inline style.',
+  },
+};

package/src/Spinner/Spinner.test.tsx

@@ -0,0 +1,122 @@
+// 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} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Spinner} from './Spinner';
+
+describe('Spinner', () => {
+  it('renders with default props', () => {
+    render(<Spinner data-testid="spinner" />);
+    expect(screen.getByTestId('spinner')).toBeInTheDocument();
+  });
+
+  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('has role="status"', () => {
+    render(<Spinner data-testid="spinner" />);
+    expect(screen.getByRole('status')).toBeInTheDocument();
+  });
+
+  it('has aria-label="Loading" by default', () => {
+    render(<Spinner data-testid="spinner" />);
+    expect(screen.getByTestId('spinner')).toHaveAttribute(
+      'aria-label',
+      'Loading',
+    );
+  });
+
+  it('uses string label as aria-label automatically', () => {
+    render(<Spinner label="Fetching data" data-testid="spinner" />);
+    expect(screen.getByRole('status')).toHaveAttribute(
+      'aria-label',
+      'Fetching data',
+    );
+  });
+
+  it('uses explicit aria-label over string label', () => {
+    render(
+      <Spinner
+        label="Loading..."
+        aria-label="Please wait"
+        data-testid="spinner"
+      />,
+    );
+    expect(screen.getByRole('status')).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('status')).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');
+  });
+});

package/src/Spinner/Spinner.tsx

@@ -0,0 +1,300 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file Spinner.tsx
+ * @input Uses React, StyleX, canvas rendering
+ * @output Exports Spinner component, SpinnerProps, SpinnerSize, SpinnerShade types
+ * @position Core implementation of spinner loading indicator
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Spinner/Spinner.doc.mjs
+ * - /packages/core/src/Spinner/Spinner.test.tsx
+ * - /packages/core/src/Spinner/index.ts
+ * - /apps/storybook/stories/Spinner.stories.tsx
+ * - /packages/cli/templates/blocks/components/Spinner/ (showcase blocks)
+ */
+
+import {useEffect, useRef, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {durationVars, spacingVars} from '../theme/tokens.stylex';
+import {useTheme} from '../theme/useTheme';
+import type {BaseProps} from '../BaseProps';
+import {Text} from '../Text/Text';
+import {mergeProps} from '../utils';
+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;
+
+const SIZES = {
+  sm: {diameter: 10, border: 2},
+  md: {diameter: 14, border: 3},
+  lg: {diameter: 18, border: 3},
+  xl: {diameter: 28, border: 4},
+};
+
+// =============================================================================
+// Animation
+// =============================================================================
+
+const rotation = stylex.keyframes({
+  '0%': {transform: 'rotate(0deg)'},
+  '100%': {transform: 'rotate(360deg)'},
+});
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  wrapper: {
+    display: 'inline-flex',
+    flexDirection: 'column',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+  },
+  spinner: {
+    display: 'inline-grid',
+    placeItems: 'center',
+    overflow: 'hidden',
+    verticalAlign: 'middle',
+  },
+  canvas: {
+    backfaceVisibility: 'hidden',
+    display: 'block',
+    animationDuration: durationVars['--duration-slow-min'],
+    animationIterationCount: 'infinite',
+    animationName: rotation,
+    animationTimingFunction: 'linear',
+  },
+});
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type SpinnerSize = keyof typeof SIZES;
+
+export type SpinnerShade = 'default' | 'onMedia' | 'subtle' | 'inherit';
+
+export interface SpinnerProps extends BaseProps<HTMLSpanElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLSpanElement>;
+  /**
+   * Spinner size.
+   * - 'sm': 10px diameter
+   * - 'md': 14px diameter
+   * - 'lg': 18px diameter
+   * - 'xl': 36px diameter
+   * @default 'md'
+   */
+  size?: SpinnerSize;
+  /**
+   * Color shade.
+   * - 'default': accent color on light backgrounds
+   * - 'onMedia': white on dark/accent backgrounds
+   * - 'subtle': secondary text color, less prominent — for inline use in lists
+   * - 'inherit': inherits the parent's `currentColor` (with a translucent
+   *   track) — use inside colored elements like buttons so the ring matches
+   *   the resolved foreground regardless of theme/variant
+   * @default 'default'
+   */
+  shade?: SpinnerShade;
+  /**
+   * Visible content displayed below the spinner.
+   * Accepts a string or ReactNode for rich content.
+   *
+   * When `label` is a string, it is also used as the accessible name
+   * (aria-label) unless `aria-label` is explicitly set.
+   *
+   * @example
+   * ```
+   * <Spinner label="Loading..." />
+   * <Spinner label={<><strong>Fetching data</strong><br/>This may take a moment</>} aria-label="Fetching data" />
+   * ```
+   */
+  label?: ReactNode;
+  /**
+   * Test ID for the root element.
+   */
+  'data-testid'?: string;
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * An animated loading indicator. Available in three sizes and two color shades.
+ *
+ * @example
+ * ```
+ * <Spinner />
+ * <Spinner size="sm" />
+ * <Spinner size="lg" shade="onMedia" />
+ * <Spinner label="Loading..." />
+ * <Spinner aria-label="Loading data" />
+ * ```
+ */
+export function Spinner({
+  size = 'md',
+  shade = 'default',
+  label,
+  xstyle,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  'data-testid': testId,
+  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 hasLabel = label != null;
+
+  // Resolve accessible name: explicit aria-label > string label > "Loading"
+  const resolvedAriaLabel =
+    ariaLabel ?? (typeof label === 'string' ? label : undefined) ?? 'Loading';
+
+  const spinner = (
+    <span
+      ref={hasLabel ? undefined : ref}
+      role="status"
+      aria-label={resolvedAriaLabel}
+      data-testid={hasLabel ? undefined : testId}
+      {...(hasLabel ? {} : restProps)}
+      {...mergeProps(
+        hasLabel ? '' : themeProps('spinner', {size, shade}),
+        stylex.props(styles.spinner, !hasLabel && xstyle),
+        hasLabel ? undefined : className,
+        {...(hasLabel ? {} : style), width: frameSize, height: frameSize},
+      )}>
+      <canvas ref={canvasRef} {...stylex.props(styles.canvas)} />
+    </span>
+  );
+
+  if (!hasLabel) {
+    return spinner;
+  }
+
+  return (
+    <div
+      ref={ref as React.Ref<HTMLDivElement>}
+      data-testid={testId}
+      {...restProps}
+      {...mergeProps(
+        themeProps('spinner', {size, shade}),
+        stylex.props(styles.wrapper, xstyle),
+        className,
+        style,
+      )}>
+      {spinner}
+      {typeof label === 'string' ? (
+        <Text type="body" weight="bold">
+          {label}
+        </Text>
+      ) : (
+        label
+      )}
+    </div>
+  );
+}
+
+Spinner.displayName = 'Spinner';

package/src/Spinner/index.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @input Imports from Spinner component
+ * @output Exports Spinner component and related types
+ * @position Entry point for Spinner; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header and /packages/core/src/Spinner/Spinner.doc.mjs
+ */
+
+export {Spinner} from './Spinner';
+export type {
+  SpinnerProps,
+  SpinnerSize,
+  SpinnerShade,
+} from './Spinner';