Skip to content

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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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}>
<span
id={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>