@astryxdesign/lab 0.0.0-bootstrap.0 → 0.1.2-canary.04e71b2

package/src/ChatReasoning/ChatReasoning.tsx

@@ -0,0 +1,322 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ChatReasoning.tsx
+ * @input Uses React, StyleX, theme tokens
+ * @output Exports ChatReasoning component
+ * @position Chat component — compact collapsible reasoning/thinking display
+ *
+ * Renders model reasoning/thinking content as a compact single-line
+ * collapsed element. Expanding reveals the full reasoning text.
+ *
+ * Design: extremely compact by default. One line with ellipsis overflow.
+ * Expandable on click.
+ */
+
+import {useState, useCallback, type ReactNode} from 'react';
+import type {BaseProps} from '@astryxdesign/core';
+import * as stylex from '@stylexjs/stylex';
+import {
+  colorVars,
+  spacingVars,
+  typeScaleVars,
+  typographyVars,
+  fontWeightVars,
+  durationVars,
+  easeVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+import {mergeProps} from '@astryxdesign/core/utils';
+import {themeProps} from '@astryxdesign/core/utils';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ChatReasoningProps extends BaseProps<HTMLDivElement> {
+  /** Reasoning content. String renders as plain text; ReactNode for Markdown etc. */
+  children: ReactNode;
+  /** Header label. @default 'Thinking' */
+  label?: string;
+  /** Duration string shown after label (e.g. "12s"). */
+  duration?: string;
+  /** Whether reasoning is still streaming. Shows shimmer on label. */
+  isStreaming?: boolean;
+  /** Controlled expanded state. */
+  isExpanded?: boolean;
+  /** Default expanded state (uncontrolled). @default false */
+  defaultIsExpanded?: boolean;
+  /** Callback when expanded state changes. */
+  onExpandedChange?: (isExpanded: boolean) => void;
+}
+
+// =============================================================================
+// Animations
+// =============================================================================
+
+const shimmerKeyframes = stylex.keyframes({
+  '0%': {backgroundPosition: '200% 0'},
+  '100%': {backgroundPosition: '-200% 0'},
+});
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = stylex.create({
+  root: {
+    display: 'flex',
+    flexDirection: 'column',
+    marginBlockStart: spacingVars['--spacing-2'],
+  },
+  header: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1-5'],
+    cursor: 'pointer',
+    userSelect: 'none',
+    minHeight: '24px',
+    paddingBlock: spacingVars['--spacing-0-5'],
+  },
+  icon: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: '16px',
+    height: '16px',
+    color: colorVars['--color-text-secondary'],
+  },
+  labelRow: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+    minWidth: 0,
+    overflow: 'hidden',
+  },
+  label: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontWeight: fontWeightVars['--font-weight-medium'],
+    color: colorVars['--color-text-secondary'],
+    whiteSpace: 'nowrap',
+    flexShrink: 0,
+  },
+  duration: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+    color: colorVars['--color-text-disabled'],
+    whiteSpace: 'nowrap',
+    flexShrink: 0,
+  },
+  separator: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+    color: colorVars['--color-text-disabled'],
+    flexShrink: 0,
+  },
+  preview: {
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+    color: colorVars['--color-text-disabled'],
+    whiteSpace: 'nowrap',
+    overflow: 'hidden',
+    textOverflow: 'ellipsis',
+    minWidth: 0,
+  },
+  chevron: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    width: '14px',
+    height: '14px',
+    color: colorVars['--color-text-disabled'],
+    transition: `transform ${durationVars['--duration-fast']} ${easeVars['--ease-standard']}`,
+  },
+  chevronExpanded: {
+    transform: 'rotate(180deg)',
+  },
+  shimmer: {
+    backgroundImage: `linear-gradient(90deg, ${colorVars['--color-text-secondary']} 0%, ${colorVars['--color-text-disabled']} 50%, ${colorVars['--color-text-secondary']} 100%)`,
+    backgroundSize: '200% 100%',
+    backgroundClip: 'text',
+    color: 'transparent',
+    animationName: shimmerKeyframes,
+    animationDuration: '4s',
+    animationTimingFunction: 'linear',
+    animationIterationCount: 'infinite',
+  },
+  content: {
+    display: 'grid',
+    gridTemplateRows: '0fr',
+    transition: `grid-template-rows ${durationVars['--duration-medium']} ${easeVars['--ease-standard']}`,
+  },
+  contentExpanded: {
+    gridTemplateRows: '1fr',
+  },
+  contentInner: {
+    overflow: 'hidden',
+    minHeight: 0,
+  },
+  contentPadding: {
+    paddingBlockStart: spacingVars['--spacing-2'],
+    paddingInlineStart: `calc(16px + ${spacingVars['--spacing-1-5']})`,
+    fontSize: typeScaleVars['--text-supporting-size'],
+    lineHeight: typeScaleVars['--text-supporting-leading'],
+    fontFamily: typographyVars['--font-family-body'],
+    color: colorVars['--color-text-secondary'],
+  },
+});
+
+// =============================================================================
+// Icons
+// =============================================================================
+
+function ThinkingIcon() {
+  return (
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+      <circle
+        cx="7"
+        cy="7"
+        r="5.5"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeDasharray="3 2"
+      />
+      <circle cx="5.5" cy="7" r="0.75" fill="currentColor" />
+      <circle cx="8.5" cy="7" r="0.75" fill="currentColor" />
+    </svg>
+  );
+}
+
+function ChevronDownIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 12 12" fill="none">
+      <path
+        d="M3 4.5L6 7.5L9 4.5"
+        stroke="currentColor"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Compact collapsible display for model reasoning/thinking content.
+ *
+ * Renders as a single line: icon + label + duration + ellipsized preview.
+ * Expands to show full reasoning on click.
+ *
+ * @example
+ * ```
+ * <ChatMessage sender="assistant">
+ *   <ChatReasoning duration="12s">
+ *     Let me work through the constraints on adjacent fields...
+ *   </ChatReasoning>
+ *   <Markdown>{response}</Markdown>
+ * </ChatMessage>
+ * ```
+ */
+export function ChatReasoning(props: ChatReasoningProps) {
+  const {
+    children,
+    label = 'Thinking',
+    duration,
+    isStreaming = false,
+    isExpanded: controlledExpanded,
+    defaultIsExpanded = false,
+    onExpandedChange,
+    xstyle,
+    className,
+    style,
+    ...rest
+  } = props;
+
+  const [internalExpanded, setInternalExpanded] = useState(defaultIsExpanded);
+  const isControlled = controlledExpanded !== undefined;
+  const isExpanded = isControlled ? controlledExpanded : internalExpanded;
+
+  const toggle = useCallback(() => {
+    const next = !isExpanded;
+    if (!isControlled) {
+      setInternalExpanded(next);
+    }
+    onExpandedChange?.(next);
+  }, [isExpanded, isControlled, onExpandedChange]);
+
+  const previewText = typeof children === 'string' ? children : null;
+
+  return (
+    <div
+      {...mergeProps(
+        themeProps('chat-reasoning', {
+          expanded: isExpanded ? 'expanded' : null,
+          streaming: isStreaming ? 'streaming' : null,
+        }),
+        stylex.props(styles.root, xstyle),
+        className,
+        style,
+      )}
+      {...rest}>
+      <div
+        role="button"
+        tabIndex={0}
+        aria-expanded={isExpanded}
+        onClick={toggle}
+        onKeyDown={e => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            toggle();
+          }
+        }}
+        {...stylex.props(styles.header)}>
+        <span {...stylex.props(styles.icon)}>
+          <ThinkingIcon />
+        </span>
+        <div {...stylex.props(styles.labelRow)}>
+          <span {...stylex.props(styles.label, isStreaming && styles.shimmer)}>
+            {label}
+          </span>
+          {duration != null && !isStreaming && (
+            <>
+              <span {...stylex.props(styles.separator)}>·</span>
+              <span {...stylex.props(styles.duration)}>{duration}</span>
+            </>
+          )}
+          {!isExpanded && previewText && !isStreaming && (
+            <>
+              <span {...stylex.props(styles.separator)}>—</span>
+              <span {...stylex.props(styles.preview)}>{previewText}</span>
+            </>
+          )}
+        </div>
+        <span
+          {...stylex.props(
+            styles.chevron,
+            isExpanded && styles.chevronExpanded,
+          )}>
+          <ChevronDownIcon />
+        </span>
+      </div>
+
+      <div
+        {...stylex.props(styles.content, isExpanded && styles.contentExpanded)}>
+        <div {...stylex.props(styles.contentInner)}>
+          <div {...stylex.props(styles.contentPadding)}>{children}</div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+ChatReasoning.displayName = 'ChatReasoning';

package/src/CircularProgress/CircularProgress.doc.mjs

@@ -0,0 +1,174 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'CircularProgress',
+  displayName: 'Circular Progress',
+  category: 'Feedback & Status',
+  keywords: ["circular","progress","radial","ring","arc","determinate","indeterminate","gauge","meter","donut"],
+  props: [
+    {
+      name: 'value',
+      type: 'number',
+      description: 'Current value. When omitted, renders an indeterminate spinning animation.',
+    },
+    {
+      name: 'max',
+      type: 'number',
+      description: 'Maximum value.',
+      default: '100',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: 'Accessible label for screen readers.',
+      required: true,
+    },
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: 'Visually hide the label (remains accessible). Defaults to true since circular progress typically shows center content instead.',
+      default: 'true',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: 'Content displayed in the center of the ring: percentage, icon, or custom content.',
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: 'Diameter of the progress ring (32px, 48px, 64px).',
+      default: "'md'",
+    },
+    {
+      name: 'variant',
+      type: "'accent' | 'success' | 'warning' | 'error' | 'neutral'",
+      description: 'Semantic color variant for the progress fill.',
+      default: "'accent'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'StyleX styles for layout customization (margins, positioning). Must be a stylex.create() value.',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-circular-progress', visualProps: ['variant', 'size']},
+      {className: 'astryx-circular-progress-track'},
+      {className: 'astryx-circular-progress-fill', visualProps: ['variant']},
+    ],
+  },
+  usage: {
+    description:
+      'A circular progress indicator that shows completion as a ring or arc. Use it for upload progress, score displays, dashboard gauges, or compact progress where horizontal space is limited. Complements ProgressBar for radial layouts.',
+    bestPractices: [
+      { guidance: true, description: 'Pass a value for determinate progress; omit value for an indeterminate spinner.' },
+      { guidance: true, description: 'Provide center content (children) to give context: a percentage, icon, or short label.' },
+      { guidance: true, description: 'Always provide a label, even though it is visually hidden by default; screen readers need it.' },
+      { guidance: false, description: 'Use circular progress for long text labels; use ProgressBar instead, which has more room for label and value display.' },
+      { guidance: false, description: 'Stack multiple circular progress indicators for the same operation; use one with a value label.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').ComponentDoc} */
+export const docsZh = {
+  name: 'CircularProgress',
+  displayName: 'Circular Progress',
+  props: [
+    {
+      name: 'value',
+      type: 'number',
+      description: '当前值。省略时渲染不确定旋转动画。',
+    },
+    {
+      name: 'max',
+      type: 'number',
+      description: '最大值。',
+      default: '100',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description: '屏幕阅读器的无障碍标签（必填）。',
+      required: true,
+    },
+    {
+      name: 'isLabelHidden',
+      type: 'boolean',
+      description: '视觉上隐藏标签（仍保持无障碍可访问性）。默认为 true，因为圆形进度条通常显示中心内容。',
+      default: 'true',
+    },
+    {
+      name: 'children',
+      type: 'ReactNode',
+      description: '在环形中心显示的内容：百分比、图标或自定义内容。',
+    },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '进度环的直径（32px、48px、64px）。',
+      default: "'md'",
+    },
+    {
+      name: 'variant',
+      type: "'accent' | 'success' | 'warning' | 'error' | 'neutral'",
+      description: '进度填充的语义颜色变体。',
+      default: "'accent'",
+    },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: '用于布局自定义的 StyleX 样式。必须是 stylex.create() 的值。',
+    },
+  ],
+  theming: {
+    targets: [
+      {className: 'astryx-circular-progress', visualProps: ['variant', 'size']},
+      {className: 'astryx-circular-progress-track'},
+      {className: 'astryx-circular-progress-fill', visualProps: ['variant']},
+    ],
+  },
+  usage: {
+    description:
+      'A circular progress indicator that shows completion as a ring or arc. Use it for upload progress, score displays, dashboard gauges, or compact progress where horizontal space is limited. Complements ProgressBar for radial layouts.',
+    bestPractices: [
+      { guidance: true, description: 'Pass a value for determinate progress; omit value for an indeterminate spinner.' },
+      { guidance: true, description: 'Provide center content (children) to give context: a percentage, icon, or short label.' },
+      { guidance: true, description: 'Always provide a label, even though it is visually hidden by default; screen readers need it.' },
+      { guidance: false, description: 'Use circular progress for long text labels; use ProgressBar instead, which has more room for label and value display.' },
+      { guidance: false, description: 'Stack multiple circular progress indicators for the same operation; use one with a value label.' },
+    ],
+  },
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Circular/radial progress indicator showing completion as a ring arc.',
+  usage: {
+    description:
+      'A circular progress indicator that shows completion as a ring or arc. Use it for upload progress, score displays, dashboard gauges, or compact progress where horizontal space is limited. Complements ProgressBar for radial layouts.',
+    bestPractices: [
+      { guidance: true, description: 'Pass a value for determinate progress; omit value for an indeterminate spinner.' },
+      { guidance: true, description: 'Provide center content (children) to give context: a percentage, icon, or short label.' },
+      { guidance: true, description: 'Always provide a label, even though it is visually hidden by default; screen readers need it.' },
+      { guidance: false, description: 'Use circular progress for long text labels; use ProgressBar instead, which has more room for label and value display.' },
+      { guidance: false, description: 'Stack multiple circular progress indicators for the same operation; use one with a value label.' },
+    ],
+  },
+  propDescriptions: {
+    value: 'Current value. Omit for indeterminate spinning animation.',
+    max: 'Maximum value.',
+    label: 'Accessible label for screen readers.',
+    isLabelHidden: 'Visually hide label (remains accessible). Defaults to true.',
+    children: 'Center content: percentage, icon, or custom.',
+    size: 'Ring diameter (32px, 48px, 64px).',
+    variant: 'Semantic color variant for the fill.',
+    xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
+  },
+};

package/src/CircularProgress/CircularProgress.test.tsx

@@ -0,0 +1,157 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {CircularProgress} from './CircularProgress';
+
+describe('CircularProgress', () => {
+  it('renders with default props', () => {
+    render(<CircularProgress value={50} label="Progress" />);
+    const meter = screen.getByRole('meter');
+    expect(meter).toBeInTheDocument();
+    expect(meter).toHaveAttribute('aria-valuenow', '50');
+    expect(meter).toHaveAttribute('aria-valuemin', '0');
+    expect(meter).toHaveAttribute('aria-valuemax', '100');
+  });
+
+  it('renders label as visually hidden by default', () => {
+    render(<CircularProgress value={50} label="Upload progress" />);
+    expect(screen.getByText('Upload progress')).toBeInTheDocument();
+    const meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-labelledby');
+  });
+
+  it('shows label visually when isLabelHidden is false', () => {
+    render(
+      <CircularProgress
+        value={50}
+        label="Upload progress"
+        isLabelHidden={false}
+      />,
+    );
+    const label = screen.getByText('Upload progress');
+    expect(label).toBeInTheDocument();
+    const meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-labelledby');
+  });
+
+  it('respects custom max', () => {
+    render(<CircularProgress value={3} max={10} label="Steps" />);
+    const meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-valuenow', '3');
+    expect(meter).toHaveAttribute('aria-valuemax', '10');
+  });
+
+  it('clamps value to [0, max]', () => {
+    const {rerender} = render(
+      <CircularProgress value={150} max={100} label="Over" />,
+    );
+    let meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-valuenow', '100');
+
+    rerender(<CircularProgress value={-10} max={100} label="Under" />);
+    meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-valuenow', '0');
+  });
+
+  it('renders children in the center', () => {
+    render(
+      <CircularProgress value={75} label="Progress">
+        75%
+      </CircularProgress>,
+    );
+    expect(screen.getByText('75%')).toBeInTheDocument();
+  });
+
+  it('forwards ref to outer container', () => {
+    const ref = {current: null as HTMLDivElement | null};
+    render(<CircularProgress ref={ref} value={50} label="Test" />);
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it('passes data-testid', () => {
+    render(
+      <CircularProgress value={50} label="Test" data-testid="my-progress" />,
+    );
+    expect(screen.getByTestId('my-progress')).toBeInTheDocument();
+  });
+
+  it('renders with all variant options', () => {
+    const variants = [
+      'accent',
+      'success',
+      'warning',
+      'error',
+      'neutral',
+    ] as const;
+    for (const variant of variants) {
+      const {unmount} = render(
+        <CircularProgress value={50} label={variant} variant={variant} />,
+      );
+      expect(screen.getByRole('meter')).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it('renders with all size options', () => {
+    const sizes = ['sm', 'md', 'lg'] as const;
+    for (const size of sizes) {
+      const {unmount} = render(
+        <CircularProgress value={50} label={size} size={size} />,
+      );
+      expect(screen.getByRole('meter')).toBeInTheDocument();
+      unmount();
+    }
+  });
+
+  it('handles zero max gracefully', () => {
+    render(<CircularProgress value={0} max={0} label="Empty" />);
+    const meter = screen.getByRole('meter');
+    expect(meter).toHaveAttribute('aria-valuenow', '0');
+    expect(meter).toHaveAttribute('aria-valuemax', '0');
+  });
+
+  describe('indeterminate mode', () => {
+    it('renders indeterminate when value is omitted', () => {
+      render(<CircularProgress label="Loading" />);
+      const progressbar = screen.getByRole('progressbar');
+      expect(progressbar).toBeInTheDocument();
+    });
+
+    it('does not set aria-valuenow/min/max when indeterminate', () => {
+      render(<CircularProgress label="Loading" />);
+      const progressbar = screen.getByRole('progressbar');
+      expect(progressbar).not.toHaveAttribute('aria-valuenow');
+      expect(progressbar).not.toHaveAttribute('aria-valuemin');
+      expect(progressbar).not.toHaveAttribute('aria-valuemax');
+    });
+
+    it('is labelled via aria-labelledby when indeterminate', () => {
+      render(<CircularProgress label="Loading data" />);
+      const progressbar = screen.getByRole('progressbar');
+      expect(progressbar).toHaveAttribute('aria-labelledby');
+    });
+
+    it('renders with all variants in indeterminate mode', () => {
+      const variants = [
+        'accent',
+        'success',
+        'warning',
+        'error',
+        'neutral',
+      ] as const;
+      for (const variant of variants) {
+        const {unmount} = render(
+          <CircularProgress label={variant} variant={variant} />,
+        );
+        expect(screen.getByRole('progressbar')).toBeInTheDocument();
+        unmount();
+      }
+    });
+
+    it('renders children alongside indeterminate animation', () => {
+      render(<CircularProgress label="Loading">...</CircularProgress>);
+      expect(screen.getByText('...')).toBeInTheDocument();
+    });
+  });
+});