An open source design system that's fully customizable and agent ready
TypeScript
feat(lab): CircularProgress API parity with ProgressBar (#4150)
AKa82ad5b71cd2
diff --git a/apps/storybook/stories/CircularProgress.stories.tsx b/apps/storybook/stories/CircularProgress.stories.tsxindex aceb0786b9..931e21edc4 100644--- a/apps/storybook/stories/CircularProgress.stories.tsx+++ b/apps/storybook/stories/CircularProgress.stories.tsx@@ -35,6 +35,18 @@ const meta: Meta<typeof CircularProgress> = {control: 'boolean',description: 'Visually hide the label',},+ hasValueLabel: {+ control: 'boolean',+ description: 'Show the formatted value in the ring center',+ },+ isIndeterminate: {+ control: 'boolean',+ description: 'Animated indicator for unknown progress',+ },+ isDisabled: {+ control: 'boolean',+ description: 'Visually disabled ring and text',+ },},};@@ -116,8 +128,45 @@ export const Full: Story = {},};+export const WithValueLabel: Story = {+ args: {+ value: 75,+ label: 'Upload progress',+ size: 'lg',+ hasValueLabel: true,+ },+};++export const CustomValueFormat: Story = {+ args: {+ value: 3,+ max: 5,+ label: 'Steps completed',+ size: 'lg',+ hasValueLabel: true,+ formatValueLabel: (value, max) => `${value}/${max}`,+ },+};++export const Disabled: Story = {+ render: () => (+ <div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>+ <CircularProgress value={30} label="Canceled" isDisabled />+ <CircularProgress+ value={30}+ label="Canceled with value"+ size="lg"+ isDisabled+ hasValueLabel+ />+ <CircularProgress isIndeterminate label="Canceled loading" isDisabled />+ </div>+ ),+};+export const Indeterminate: Story = {args: {+ isIndeterminate: true,label: 'Loading...',},};@@ -125,9 +174,9 @@ export const Indeterminate: Story = {export const IndeterminateSizes: Story = {render: () => (<div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>- <CircularProgress size="sm" label="Loading small" />- <CircularProgress size="md" label="Loading medium" />- <CircularProgress size="lg" label="Loading large" />+ <CircularProgress isIndeterminate size="sm" label="Loading small" />+ <CircularProgress isIndeterminate size="md" label="Loading medium" />+ <CircularProgress isIndeterminate size="lg" label="Loading large" /></div>),};@@ -135,10 +184,11 @@ export const IndeterminateSizes: Story = {export const IndeterminateVariants: Story = {render: () => (<div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>- <CircularProgress label="Accent" variant="accent" />- <CircularProgress label="Positive" variant="success" />- <CircularProgress label="Warning" variant="warning" />- <CircularProgress label="Negative" variant="error" />+ <CircularProgress isIndeterminate label="Accent" variant="accent" />+ <CircularProgress isIndeterminate label="Positive" variant="success" />+ <CircularProgress isIndeterminate label="Warning" variant="warning" />+ <CircularProgress isIndeterminate label="Negative" variant="error" />+ <CircularProgress isIndeterminate label="Neutral" variant="neutral" /></div>),};diff --git a/packages/lab/src/CircularProgress/CircularProgress.doc.mjs b/packages/lab/src/CircularProgress/CircularProgress.doc.mjsindex a2ddaf49b4..f98eba19d6 100644--- a/packages/lab/src/CircularProgress/CircularProgress.doc.mjs+++ b/packages/lab/src/CircularProgress/CircularProgress.doc.mjs@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-/** @type {import('../docs-types').ComponentDoc} */+/** @type {import('../../../core/src/docs-types').ComponentDoc} */export const docs = {name: 'CircularProgress',@@ -11,7 +11,8 @@ export const docs = {{name: 'value',type: 'number',- description: 'Current value. When omitted, renders an indeterminate spinning animation.',+ description: 'Current value. Ignored when isIndeterminate is true.',+ default: '0',},{name: 'max',@@ -31,10 +32,21 @@ export const docs = {description: 'Visually hide the label (remains accessible). Defaults to true since circular progress typically shows center content instead.',default: 'true',},+ {+ name: 'hasValueLabel',+ type: 'boolean',+ description: 'Show the formatted value (e.g. "75%") in the center of the ring. Ignored when isIndeterminate is true or when children provide custom center content.',+ default: 'false',+ },+ {+ name: 'formatValueLabel',+ type: '(value: number, max: number) => string',+ description: 'Custom value label formatter; defaults to a percentage string.',+ },{name: 'children',type: 'ReactNode',- description: 'Content displayed in the center of the ring: percentage, icon, or custom content.',+ description: 'Content displayed in the center of the ring: percentage, icon, or custom content. Takes precedence over hasValueLabel.',},{name: 'size',@@ -48,6 +60,18 @@ export const docs = {description: 'Semantic color variant for the progress fill.',default: "'accent'",},+ {+ name: 'isIndeterminate',+ type: 'boolean',+ description: 'Animated spinning indicator for unknown progress. Respects prefers-reduced-motion by slowing the animation.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Visually disabled: grays out the ring and text. Use for canceled or inactive operations.',+ default: 'false',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -66,16 +90,34 @@ export const docs = {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: 'Pass a value for determinate progress; set isIndeterminate when the duration is unknown.' },+ { guidance: true, description: 'Show the value with hasValueLabel, or pass children for custom center content: an 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.' },+ { guidance: false, description: 'Use an indeterminate CircularProgress for small inline loading states; Spinner is the inline indicator.' },],},+ examples: [+ {+ label: 'Determinate with value label',+ code: '<CircularProgress value={75} label="Upload progress" hasValueLabel />',+ },+ {+ label: 'Indeterminate',+ code: '<CircularProgress isIndeterminate label="Loading..." />',+ },+ {+ label: 'Custom value format',+ code: '<CircularProgress value={3.2} max={5} label="Disk usage" hasValueLabel formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />',+ },+ {+ label: 'Disabled',+ code: '<CircularProgress value={30} label="Canceled" isDisabled hasValueLabel />',+ },+ ],};-/** @type {import('../docs-types').ComponentDoc} */+/** @type {import('../../../core/src/docs-types').ComponentDoc} */export const docsZh = {name: 'CircularProgress',displayName: 'Circular Progress',@@ -83,7 +125,8 @@ export const docsZh = {{name: 'value',type: 'number',- description: '当前值。省略时渲染不确定旋转动画。',+ description: '当前值。当 isIndeterminate 为 true 时忽略。',+ default: '0',},{name: 'max',@@ -103,10 +146,21 @@ export const docsZh = {description: '视觉上隐藏标签(仍保持无障碍可访问性)。默认为 true,因为圆形进度条通常显示中心内容。',default: 'true',},+ {+ name: 'hasValueLabel',+ type: 'boolean',+ description: '在环形中心显示格式化的值(如 "75%")。当 isIndeterminate 为 true 或提供了 children 自定义中心内容时忽略。',+ default: 'false',+ },+ {+ name: 'formatValueLabel',+ type: '(value: number, max: number) => string',+ description: '自定义值标签格式化函数;默认为百分比字符串。',+ },{name: 'children',type: 'ReactNode',- description: '在环形中心显示的内容:百分比、图标或自定义内容。',+ description: '在环形中心显示的内容:百分比、图标或自定义内容。优先于 hasValueLabel。',},{name: 'size',@@ -120,6 +174,18 @@ export const docsZh = {description: '进度填充的语义颜色变体。',default: "'accent'",},+ {+ name: 'isIndeterminate',+ type: 'boolean',+ description: '用于未知进度的旋转动画指示器。遵循 prefers-reduced-motion,减速播放动画。',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: '视觉禁用:环形和文本变灰。用于已取消或非活动的操作。',+ default: 'false',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -137,16 +203,16 @@ export const docsZh = {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: 'Pass a value for determinate progress; set isIndeterminate when the duration is unknown.' },+ { guidance: true, description: 'Show the value with hasValueLabel, or pass children for custom center content: an 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.' },+ { guidance: false, description: 'Use an indeterminate CircularProgress for small inline loading states; Spinner is the inline indicator.' },],},};-/** @type {import('../docs-types').TranslationDoc} */+/** @type {import('../../../core/src/docs-types').TranslationDoc} */export const docsDense = {description:'Circular/radial progress indicator showing completion as a ring arc.',@@ -154,21 +220,25 @@ export const docsDense = {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: 'Pass a value for determinate progress; set isIndeterminate when the duration is unknown.' },+ { guidance: true, description: 'Show the value with hasValueLabel, or pass children for custom center content: an 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.' },+ { guidance: false, description: 'Use an indeterminate CircularProgress for small inline loading states; Spinner is the inline indicator.' },],},propDescriptions: {- value: 'Current value. Omit for indeterminate spinning animation.',+ value: 'Current value. Ignored when indeterminate.',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.',+ hasValueLabel: 'Show formatted value in the ring center (ignored when indeterminate or children given).',+ formatValueLabel: 'Custom value label formatter; defaults to percentage string.',+ children: 'Center content: percentage, icon, or custom. Wins over hasValueLabel.',size: 'Ring diameter (32px, 48px, 64px).',variant: 'Semantic color variant for the fill.',+ isIndeterminate: 'Animated spinning indicator for unknown progress.',+ isDisabled: 'Visually disabled: grays out ring and text.',xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',},};diff --git a/packages/lab/src/CircularProgress/CircularProgress.test.tsx b/packages/lab/src/CircularProgress/CircularProgress.test.tsxindex 64c516b33c..31d2c43f45 100644--- a/packages/lab/src/CircularProgress/CircularProgress.test.tsx+++ b/packages/lab/src/CircularProgress/CircularProgress.test.tsx@@ -7,18 +7,36 @@ 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');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toBeInTheDocument();+ expect(progressbar).toHaveAttribute('aria-valuenow', '50');+ expect(progressbar).toHaveAttribute('aria-valuemin', '0');+ expect(progressbar).toHaveAttribute('aria-valuemax', '100');+ });++ it('uses role="progressbar" (not "meter") for determinate progress', () => {+ // progressbar covers both determinate and indeterminate progress of a+ // task; meter describes a static measurement within a known range.+ // Matches core ProgressBar so both progress primitives announce alike.+ render(<CircularProgress value={50} label="Progress" />);+ expect(screen.queryByRole('meter')).not.toBeInTheDocument();+ expect(screen.getByRole('progressbar')).toBeInTheDocument();+ });++ it('renders an empty determinate ring when value is omitted', () => {+ // Parity with core ProgressBar: value defaults to 0 and indeterminate+ // mode is opt-in via isIndeterminate, never implied by an omitted value.+ render(<CircularProgress label="Progress" />);+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '0');+ expect(progressbar).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');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-labelledby');});it('shows label visually when isLabelHidden is false', () => {@@ -31,27 +49,70 @@ describe('CircularProgress', () => {);const label = screen.getByText('Upload progress');expect(label).toBeInTheDocument();- const meter = screen.getByRole('meter');- expect(meter).toHaveAttribute('aria-labelledby');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-labelledby');+ });++ it('links the label to the progressbar via aria-labelledby', () => {+ render(<CircularProgress value={50} label="Upload progress" />);+ const label = screen.getByText('Upload progress');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar.getAttribute('aria-labelledby')).toBe(label.id);});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');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '3');+ expect(progressbar).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');+ let progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '100');rerender(<CircularProgress value={-10} max={100} label="Under" />);- meter = screen.getByRole('meter');- expect(meter).toHaveAttribute('aria-valuenow', '0');+ progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '0');+ });++ it('sets aria-valuetext from formatValueLabel', () => {+ render(<CircularProgress value={50} label="Progress" />);+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuetext', '50%');+ });++ it('shows the formatted value in the ring center when hasValueLabel', () => {+ render(<CircularProgress value={75} label="Progress" hasValueLabel />);+ expect(screen.getByText('75%')).toBeInTheDocument();+ });++ it('uses custom formatValueLabel', () => {+ render(+ <CircularProgress+ value={3}+ max={10}+ label="Steps"+ hasValueLabel+ formatValueLabel={(value, max) => `${value} of ${max}`}+ />,+ );+ expect(screen.getByText('3 of 10')).toBeInTheDocument();+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuetext', '3 of 10');+ });++ it('lets children take precedence over the value label', () => {+ render(+ <CircularProgress value={75} label="Progress" hasValueLabel>+ Almost there+ </CircularProgress>,+ );+ expect(screen.getByText('Almost there')).toBeInTheDocument();+ expect(screen.queryByText('75%')).not.toBeInTheDocument();});it('renders children in the center', () => {@@ -88,7 +149,7 @@ describe('CircularProgress', () => {const {unmount} = render(<CircularProgress value={50} label={variant} variant={variant} />,);- expect(screen.getByRole('meter')).toBeInTheDocument();+ expect(screen.getByRole('progressbar')).toBeInTheDocument();unmount();}});@@ -99,39 +160,138 @@ describe('CircularProgress', () => {const {unmount} = render(<CircularProgress value={50} label={size} size={size} />,);- expect(screen.getByRole('meter')).toBeInTheDocument();+ expect(screen.getByRole('progressbar')).toBeInTheDocument();unmount();}});+ it('sets ring geometry from size', () => {+ const {container} = render(+ <CircularProgress value={50} size="md" label="Progress" />,+ );+ const svg = container.querySelector('svg');+ expect(svg).toHaveAttribute('width', '48');+ expect(svg).toHaveAttribute('height', '48');+ expect(svg).toHaveAttribute('viewBox', '0 0 48 48');+ // radius = (diameter - strokeWidth) / 2 = (48 - 4) / 2+ for (const circle of container.querySelectorAll('circle')) {+ expect(circle).toHaveAttribute('r', '22');+ expect(circle).toHaveAttribute('stroke-width', '4');+ }+ });++ it('computes stroke-dashoffset from value', () => {+ const {container} = render(+ <CircularProgress value={25} max={100} size="md" label="Progress" />,+ );+ // circumference = 2π * 22 ≈ 138.23; offset = circumference * (1 - 0.25)+ const fill = container.querySelector('.astryx-circular-progress-fill');+ expect(fill).not.toBeNull();+ expect(+ parseFloat(fill!.getAttribute('stroke-dasharray') ?? ''),+ ).toBeCloseTo(138.23, 1);+ expect(+ parseFloat(fill!.getAttribute('stroke-dashoffset') ?? ''),+ ).toBeCloseTo(103.67, 1);+ });+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');+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '0');+ expect(progressbar).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('treats a NaN value as empty progress instead of leaking "NaN"', () => {+ render(+ <CircularProgress value={NaN} label="Broken upload" hasValueLabel />,+ );+ expect(screen.queryByText(/NaN/)).not.toBeInTheDocument();+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '0');+ });++ it('treats a NaN max as an empty range instead of leaking "NaN"', () => {+ render(+ <CircularProgress value={50} max={NaN} label="Broken" hasValueLabel />,+ );+ expect(screen.queryByText(/NaN/)).not.toBeInTheDocument();+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toHaveAttribute('aria-valuenow', '0');+ expect(progressbar).toHaveAttribute('aria-valuemax', '0');+ });++ it('does not render NaN in the value label when max is zero', () => {+ render(<CircularProgress value={5} max={0} label="Empty" hasValueLabel />);+ const progressbar = screen.getByRole('progressbar');+ expect(screen.queryByText(/NaN|Infinity/)).not.toBeInTheDocument();+ expect(progressbar.getAttribute('aria-valuetext') ?? '').not.toMatch(+ /NaN|Infinity/,+ );+ expect(screen.getByText('0%')).toBeInTheDocument();+ });++ describe('disabled state', () => {+ it('swaps the fill to the disabled variant', () => {+ const {container} = render(+ <CircularProgress value={50} label="Canceled" isDisabled />,+ );+ const fill = container.querySelector('.astryx-circular-progress-fill');+ expect(fill).toHaveAttribute('data-variant', 'disabled');+ // The root keeps the original variant for theme targeting.+ const root = container.querySelector('.astryx-circular-progress');+ expect(root).toHaveAttribute('data-variant', 'accent');+ });++ it('still renders label and value label when disabled', () => {+ render(+ <CircularProgress+ value={50}+ label="Canceled"+ isDisabled+ hasValueLabel+ isLabelHidden={false}+ />,+ );+ expect(screen.getByText('Canceled')).toBeInTheDocument();+ expect(screen.getByText('50%')).toBeInTheDocument();});+ });- it('does not set aria-valuenow/min/max when indeterminate', () => {- render(<CircularProgress label="Loading" />);+ describe('indeterminate mode', () => {+ it('renders indeterminate when isIndeterminate is true', () => {+ render(<CircularProgress isIndeterminate value={50} label="Loading" />);const progressbar = screen.getByRole('progressbar');+ expect(progressbar).toBeInTheDocument();expect(progressbar).not.toHaveAttribute('aria-valuenow');expect(progressbar).not.toHaveAttribute('aria-valuemin');expect(progressbar).not.toHaveAttribute('aria-valuemax');});+ it('does not set aria-valuetext when indeterminate', () => {+ render(<CircularProgress isIndeterminate label="Loading" />);+ const progressbar = screen.getByRole('progressbar');+ expect(progressbar).not.toHaveAttribute('aria-valuetext');+ });+it('is labelled via aria-labelledby when indeterminate', () => {- render(<CircularProgress label="Loading data" />);+ render(<CircularProgress isIndeterminate label="Loading data" />);const progressbar = screen.getByRole('progressbar');expect(progressbar).toHaveAttribute('aria-labelledby');});+ it('suppresses the value label when indeterminate', () => {+ render(+ <CircularProgress+ isIndeterminate+ value={50}+ label="Loading"+ hasValueLabel+ />,+ );+ expect(screen.queryByText('50%')).not.toBeInTheDocument();+ });+it('renders with all variants in indeterminate mode', () => {const variants = ['accent',@@ -142,7 +302,22 @@ describe('CircularProgress', () => {] as const;for (const variant of variants) {const {unmount} = render(- <CircularProgress label={variant} variant={variant} />,+ <CircularProgress+ isIndeterminate+ label={variant}+ variant={variant}+ />,+ );+ expect(screen.getByRole('progressbar')).toBeInTheDocument();+ unmount();+ }+ });++ it('renders with all sizes in indeterminate mode', () => {+ const sizes = ['sm', 'md', 'lg'] as const;+ for (const size of sizes) {+ const {unmount} = render(+ <CircularProgress isIndeterminate label={size} size={size} />,);expect(screen.getByRole('progressbar')).toBeInTheDocument();unmount();@@ -150,7 +325,11 @@ describe('CircularProgress', () => {});it('renders children alongside indeterminate animation', () => {- render(<CircularProgress label="Loading">...</CircularProgress>);+ render(+ <CircularProgress isIndeterminate label="Loading">+ ...+ </CircularProgress>,+ );expect(screen.getByText('...')).toBeInTheDocument();});});diff --git a/packages/lab/src/CircularProgress/CircularProgress.tsx b/packages/lab/src/CircularProgress/CircularProgress.tsxindex c4f52f00ac..bfbf492b5d 100644--- a/packages/lab/src/CircularProgress/CircularProgress.tsx+++ b/packages/lab/src/CircularProgress/CircularProgress.tsx@@ -9,11 +9,10 @@* @position Core implementation; consumed by index.ts** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/CircularProgress/CircularProgress.doc.mjs (props table, features, implementation notes)- * - /packages/core/src/CircularProgress/CircularProgress.test.tsx (tests for new/changed behavior)- * - /packages/core/src/CircularProgress/index.ts (exports if types change)+ * - /packages/lab/src/CircularProgress/CircularProgress.doc.mjs (props table, features, implementation notes)+ * - /packages/lab/src/CircularProgress/CircularProgress.test.tsx (tests for new/changed behavior)+ * - /packages/lab/src/CircularProgress/index.ts (exports if types change)* - /apps/storybook/stories/CircularProgress.stories.tsx (storybook stories)- * - /packages/cli/templates/blocks/components/CircularProgress/ (showcase blocks)*/import {useId, type ReactNode} from 'react';@@ -37,7 +36,7 @@ import {themeProps} from '@astryxdesign/core/utils';* Theme packages can add custom variants via TypeScript module augmentation:* @example* ```- * declare module '@astryxdesign/core/CircularProgress' {+ * declare module '@astryxdesign/lab' {* interface CircularProgressVariantMap {* 'brand': true;* }@@ -67,7 +66,7 @@ export interface CircularProgressProps extends BaseProps<HTMLDivElement> {ref?: React.Ref<HTMLDivElement>;/*** Current value of the circular progress.- * When omitted, the component renders an indeterminate spinning animation.+ * Ignored when `isIndeterminate` is true.*/value?: number;/**@@ -84,9 +83,22 @@ export interface CircularProgressProps extends BaseProps<HTMLDivElement> {* @default true*/isLabelHidden?: boolean;+ /**+ * When true, displays the formatted value (e.g. "75%") in the center of+ * the ring. Ignored when `isIndeterminate` is true or when `children`+ * provide custom center content.+ * @default false+ */+ hasValueLabel?: boolean;+ /**+ * Custom formatter for the value label.+ * @default (value, max) => `${Math.round((value / max) * 100)}%`+ */+ formatValueLabel?: (value: number, max: number) => string;/*** Content displayed in the center of the ring.* Typically a percentage string, icon, or custom content.+ * Takes precedence over `hasValueLabel`.*/children?: ReactNode;/**@@ -102,6 +114,20 @@ export interface CircularProgressProps extends BaseProps<HTMLDivElement> {* @default 'accent'*/variant?: CircularProgressVariant;+ /**+ * When true, renders an animated indeterminate progress indicator.+ * Use when the progress amount is unknown (e.g. loading, processing).+ * The `value` and `hasValueLabel` props are ignored in this mode.+ * Respects `prefers-reduced-motion` by slowing the animation.+ * @default false+ */+ isIndeterminate?: boolean;+ /**+ * When true, the circular progress is visually disabled — the ring and+ * text use disabled colors. Use for canceled or inactive operations.+ * @default false+ */+ isDisabled?: boolean;/*** Test ID for testing utilities.*/@@ -198,6 +224,18 @@ const styles = stylex.create({fontWeight: fontWeightVars['--font-weight-medium'],color: colorVars['--color-text-secondary'],},+ labelDisabled: {+ color: colorVars['--color-text-disabled'],+ },+ valueLabel: {+ fontSize: typeScaleVars['--text-supporting-size'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ fontWeight: fontWeightVars['--font-weight-normal'],+ color: colorVars['--color-text-secondary'],+ },+ valueLabelDisabled: {+ color: colorVars['--color-text-disabled'],+ },visuallyHidden: {position: 'absolute',width: '1px',@@ -231,6 +269,9 @@ const variantStyles = stylex.create({neutral: {stroke: colorVars['--color-text-disabled'],},+ disabled: {+ stroke: colorVars['--color-text-disabled'],+ },});const trackVariantStyles = stylex.create({@@ -251,28 +292,40 @@ const trackVariantStyles = stylex.create({},});+function defaultFormatValueLabel(value: number, max: number): string {+ const pct = max > 0 ? Math.round((value / max) * 100) : 0;+ return `${pct}%`;+}+/*** A circular/radial progress indicator that shows completion as a ring.** In determinate mode, displays a known value as an arc fill.* In indeterminate mode, shows an animated spinning indicator.- * Supports center content via children for labels, percentages, or icons.+ * Supports center content via children for labels, percentages, or icons,+ * or an automatic formatted value label via `hasValueLabel`.** @example* ```- * <CircularProgress value={75} label="Upload progress" />- * <CircularProgress value={75} label="Progress" max={100}>75%</CircularProgress>- * <CircularProgress label="Loading..." />+ * <CircularProgress value={75} label="Upload progress" hasValueLabel />+ * <CircularProgress isIndeterminate label="Loading..." />+ * <CircularProgress value={3.2} max={5} label="Disk usage" hasValueLabel+ * formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />+ * <CircularProgress value={30} label="Canceled" isDisabled hasValueLabel />* ```*/export function CircularProgress({- value,+ value = 0,max = 100,label,isLabelHidden = true,+ hasValueLabel = false,+ formatValueLabel = defaultFormatValueLabel,children,size = 'md',variant = 'accent',+ isIndeterminate = false,+ isDisabled = false,xstyle,className,style,@@ -281,19 +334,30 @@ export function CircularProgress({...rest}: CircularProgressProps) {const labelId = useId();- const isIndeterminate = value == null;const {diameter, strokeWidth} = SIZE_CONFIG[size];const radius = (diameter - strokeWidth) / 2;const circumference = 2 * Math.PI * radius;- const resolvedValue = value ?? 0;- const clampedValue = Math.min(Math.max(0, resolvedValue), max);- const percentage = max > 0 ? clampedValue / max : 0;+ // A non-finite value or max (e.g. a NaN from an upstream `loaded / total`+ // with total 0) would otherwise leak into aria-valuenow, the value label,+ // and the arc geometry as the string "NaN". Treat it as empty progress,+ // matching the max=0 handling below.+ const safeValue = Number.isFinite(value) ? value : 0;+ const safeMax = Number.isFinite(max) ? max : 0;+ const clampedValue = Math.min(Math.max(0, safeValue), safeMax);+ const percentage = safeMax > 0 ? clampedValue / safeMax : 0;const dashoffset = circumference * (1 - percentage);+ const valueText = formatValueLabel(clampedValue, safeMax);const center = diameter / 2;const showLabel = !isLabelHidden;+ const showValueLabel = hasValueLabel && !isIndeterminate;+ const centerContent =+ children != null ? children : showValueLabel ? valueText : null;++ const fillVariant = isDisabled ? 'disabled' : variant;+ const trackVariant = isDisabled ? 'neutral' : variant;return (<div@@ -308,17 +372,21 @@ export function CircularProgress({{...rest}><spanid={labelId}- {...stylex.props(showLabel ? styles.label : styles.visuallyHidden)}>+ {...stylex.props(+ showLabel ? styles.label : styles.visuallyHidden,+ showLabel && isDisabled && styles.labelDisabled,+ )}>{label}</span><div {...stylex.props(styles.ringWrapper)}><svg- role={isIndeterminate ? 'progressbar' : 'meter'}+ role="progressbar"aria-labelledby={labelId}aria-valuenow={isIndeterminate ? undefined : clampedValue}aria-valuemin={isIndeterminate ? undefined : 0}- aria-valuemax={isIndeterminate ? undefined : max}+ aria-valuemax={isIndeterminate ? undefined : safeMax}+ aria-valuetext={isIndeterminate ? undefined : valueText}width={diameter}height={diameter}viewBox={`0 0 ${diameter} ${diameter}`}@@ -328,7 +396,7 @@ export function CircularProgress({<circle{...mergeProps(themeProps('circular-progress-track'),- stylex.props(styles.track, trackVariantStyles[variant]),+ stylex.props(styles.track, trackVariantStyles[trackVariant]),)}cx={center}cy={center}@@ -338,8 +406,11 @@ export function CircularProgress({{isIndeterminate ? (<circle{...mergeProps(- themeProps('circular-progress-fill', {variant}),- stylex.props(styles.fillIndeterminate, variantStyles[variant]),+ themeProps('circular-progress-fill', {variant: fillVariant}),+ stylex.props(+ styles.fillIndeterminate,+ variantStyles[fillVariant],+ ),)}cx={center}cy={center}@@ -349,8 +420,8 @@ export function CircularProgress({) : (<circle{...mergeProps(- themeProps('circular-progress-fill', {variant}),- stylex.props(styles.fill, variantStyles[variant]),+ themeProps('circular-progress-fill', {variant: fillVariant}),+ stylex.props(styles.fill, variantStyles[fillVariant]),)}cx={center}cy={center}@@ -362,8 +433,20 @@ export function CircularProgress({)}</svg>- {children != null && (- <div {...stylex.props(styles.children)}>{children}</div>+ {centerContent != null && (+ <div {...stylex.props(styles.children)}>+ {children != null ? (+ children+ ) : (+ <span+ {...stylex.props(+ styles.valueLabel,+ isDisabled && styles.valueLabelDisabled,+ )}>+ {valueText}+ </span>+ )}+ </div>)}</div></div>