facebook / facebook/astryx

[Tracker] Graduate CircularProgress from lab to core (API parity, docs, a11y)

Open
#4,133 0 comments 0 reactions 0 assignees View on GitHub
component enhancement
Dominant language
TypeScript
Stars
13.1k
Forks
1.1k
Avg merge
1d 14h
Merged PRs (30d)
669

Description

## Problem

`@astryxdesign/lab` ships `CircularProgress` — a radial progress indicator with `value` / `max` / `label` / `isLabelHidden` / `size` / `variant`. It's a useful primitive and the natural circular counterpart to core's `ProgressBar`, but it hasn't been through the graduation review that would move it from `lab` toward `core`, and it lags the core `ProgressBar` API.

This is a **tracker** for maturing `CircularProgress` to core-ready. Individual enhancements are filed and linked below; each lands on its own via the normal issue → API → PR flow.

## Current state

- Single component, no sub-parts. Props today: `value, max, label, isLabelHidden, children, size, variant, xstyle`.
- `CircularProgress.doc.mjs` has **no usage description** and **no examples**.
- API drift vs. core `ProgressBar` (`label, value, max, isLabelHidden, hasValueLabel, formatValueLabel, variant, isIndeterminate, isDisabled`).

## Scope — starter set

- [ ] **API parity with `ProgressBar`** — reconcile the shared surface: `hasValueLabel` / `formatValueLabel` (value display + formatter), `isIndeterminate` (spinner/indeterminate mode), `isDisabled`. Circular and linear progress should share prop naming where the concept is the same.
- [ ] **Value display** — no way to show/format the value today (EPS `CircularProgress` exposes `showValue` / `formatValue`; core `ProgressBar` uses `hasValueLabel` / `formatValueLabel` — align on the core naming).
- [ ] **Documentation** — fill in `CircularProgress.doc.mjs` usage description + examples; ensure Storybook coverage (`apps/storybook/stories/CircularProgress.stories.tsx` exists — expand states).
- [ ] **Accessibility pass** — `role="progressbar"` + `aria-valuenow/valuemin/valuemax`, indeterminate announcement, `prefers-reduced-motion` for any spin animation.
- [ ] **Theming review** — confirm `size` scale + `strokeWidth`/track styling go through sanctioned tokens (no raw values); decide whether stroke width is a public prop.
- [ ] **Graduation criteria** — define "core-ready" for CircularProgress (API arbitration, test coverage, docs) and the move from `@astryxdesign/lab` to `@astryxdesign/core`.

## Notes

Starting set — scope to firm up as priorities settle. Each sub-item follows the spec protocol independently (problem → research → API → PR). This issue only tracks the graduation effort.

- Component: `CircularProgress` (`@astryxdesign/lab`), `packages/lab/src/CircularProgress/`
- Parity reference: core `ProgressBar` (`packages/core/src/ProgressBar/`)

Contributor guide

Open the contributing guide

Research direction

Start with packages/lab/src/CircularProgress/ and compare its API with packages/core/src/ProgressBar/. Read CircularProgress.doc.mjs and apps/storybook/stories/CircularProgress.stories.tsx, then review the listed API, accessibility, theming, and graduation requirements. Done means the graduation criteria are defined and the linked enhancements, tests, docs, and core move are addressed.

Written by the indexing model from the issue text.

Assessment

Tech stack
storybook, typescript
Domain
accessibility, design, documentation, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.