Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(ok): adopt the shadcn progress primitive (PRD-7911) (#3387)

Andrew Mikofalvy11247c2d9a1d
diff --git a/packages/app/src/components/ReportBugDialog.dom.test.tsx b/packages/app/src/components/ReportBugDialog.dom.test.tsx
index 913b55bc6..3a8599f8d 100644
--- a/packages/app/src/components/ReportBugDialog.dom.test.tsx
+++ b/packages/app/src/components/ReportBugDialog.dom.test.tsx
@@ -348,7 +348,16 @@ describe('ReportBugDialog', () => {
// Only the honest total — no fabricated transferred-bytes counter.
expect(screen.getByText(/6\.8 MB total/)).not.toBeNull();
expect(screen.queryByText(/MB of/)).toBeNull();
- expect(screen.getByRole('progressbar')).not.toBeNull();
+ const uploadBar = screen.getByRole('progressbar');
+
+ expect(uploadBar).not.toBeNull();
+ // The width here is a time-eased estimate, not real transfer progress, so
+ // the bar must stay indeterminate: no percentage may reach assistive tech.
+ // The primitive omits these whenever `value` is null, so this pins that
+ // this call site keeps passing null rather than the eased fill percentage.
+ expect(uploadBar.getAttribute('aria-valuenow')).toBeNull();
+ expect(uploadBar.getAttribute('aria-valuetext')).toBeNull();
+ expect(uploadBar.getAttribute('data-state')).toBe('indeterminate');
expect(
(screen.getByRole('button', { name: 'Send report' }) as HTMLButtonElement).disabled,
).toBe(true);
diff --git a/packages/app/src/components/ReportBugDialogBody.tsx b/packages/app/src/components/ReportBugDialogBody.tsx
index dbb1641d7..0e60028b8 100644
--- a/packages/app/src/components/ReportBugDialogBody.tsx
+++ b/packages/app/src/components/ReportBugDialogBody.tsx
@@ -50,6 +50,7 @@ import {
DialogTitle,
} from '@/components/ui/dialog';
import { Input } from '@/components/ui/input';
+import { Progress } from '@/components/ui/progress';
import { Spinner } from '@/components/ui/spinner';
import { Textarea } from '@/components/ui/textarea';
import { dispatchExternalLinkClick } from '@/lib/external-link';
@@ -773,20 +774,16 @@ function ReportBugDialog({
<Trans>{formatSize(phase.report.zipSizeBytes)} total</Trans>
</span>
</div>
- {/* The width animation is a time-eased estimate, not real
- transfer progress, so the machine-readable state stays
- indeterminate (no aria-valuenow) — assistive tech must not
- hear invented percentages. */}
- <div
- role="progressbar"
+ {/* The fill is a time-eased estimate, not real transfer progress,
+ so the machine-readable state stays indeterminate (`value`
+ null, hence no aria-valuenow) while the bar still moves —
+ assistive tech must not hear invented percentages. */}
+ <Progress
+ value={null}
+ indeterminateFillPercent={uploadPct}
aria-label={t`Sending report`}
- className="h-1.5 overflow-hidden rounded-full bg-secondary"
- >
- <div
- className="h-full rounded-full bg-primary"
- style={{ width: `${uploadPct}%` }}
- />
- </div>
+ className="h-1.5 bg-secondary"
+ />
</DialogBody>
<DialogFooter className="sm:justify-between">
<Button
diff --git a/packages/app/src/components/acp/ThreadView.tsx b/packages/app/src/components/acp/ThreadView.tsx
index 3035e57df..963d28d2b 100644
--- a/packages/app/src/components/acp/ThreadView.tsx
+++ b/packages/app/src/components/acp/ThreadView.tsx
@@ -98,6 +98,7 @@ import {
MessageScrollerViewport,
useMessageScroller,
} from '@/components/ui/message-scroller';
+import { Progress } from '@/components/ui/progress';
import { Skeleton } from '@/components/ui/skeleton';
import { Spinner } from '@/components/ui/spinner';
import { Switch } from '@/components/ui/switch';
@@ -2540,6 +2541,7 @@ function RuntimeConsentPrompt({
const { t } = useLingui();
const client = getAgentThreadClient();
const [remember, setRemember] = useState(true);
+ const downloadLabelId = useId();
if (item.resolved === 'declined' || item.resolved === 'timeout') {
return (
@@ -2587,16 +2589,24 @@ function RuntimeConsentPrompt({
>
<div className="mb-1.5 flex items-center gap-1.5 text-muted-foreground">
<Spinner className="size-3.5 shrink-0" aria-hidden="true" />
- <span>{t`Downloading ${item.displayName} ${item.version}…`}</span>
- </div>
- <div className="h-1.5 w-full overflow-hidden rounded-full bg-muted">
- <div
- className="h-full rounded-full bg-primary transition-[width] duration-200"
- style={{ width: pct !== null ? `${pct}%` : '40%' }}
- />
+ <span id={downloadLabelId}>{t`Downloading ${item.displayName} ${item.version}…`}</span>
</div>
+ {/* Naming the bar off the visible status line keeps one string doing
+ both jobs. A download with no total bytes has no honest percentage,
+ so it stays indeterminate and only the fill is faked. */}
+ <Progress
+ value={pct}
+ indeterminateFillPercent={40}
+ aria-labelledby={downloadLabelId}
+ className="h-1.5"
+ />
{pct !== null ? (
- <div className="mt-1 text-[11px] text-muted-foreground">{`${pct}%`}</div>
+ // The bar already carries this number as aria-valuenow; leaving the
+ // text in the a11y tree would announce it twice.
+ <div
+ aria-hidden="true"
+ className="mt-1 text-[11px] text-muted-foreground"
+ >{`${pct}%`}</div>
) : null}
</div>
);
diff --git a/packages/app/src/components/ui/progress.dom.test.tsx b/packages/app/src/components/ui/progress.dom.test.tsx
new file mode 100644
index 000000000..6d35a357b
--- /dev/null
+++ b/packages/app/src/components/ui/progress.dom.test.tsx
@@ -0,0 +1,159 @@
+/**
+ * DOM-substrate tests for Progress. The contract that matters here is the split
+ * between what the bar *announces* and what it *paints*: upstream shadcn drops
+ * `value` before it reaches the Radix root, so a determinate bar silently loses
+ * its `aria-valuenow`. These tests pin the forwarding, and pin that a bar can
+ * be visually filled while staying honestly indeterminate.
+ */
+
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+import {
+ expectVisualClassTokens,
+ expectVisualClassTokensAbsent,
+} from '@/test-utils/visual-contract';
+import { Progress } from './progress';
+
+afterEach(cleanup);
+
+function indicatorOf(container: HTMLElement): HTMLElement {
+ const indicator = container.querySelector<HTMLElement>('[data-slot="progress-indicator"]');
+ if (!indicator) throw new Error('Progress rendered no indicator');
+ return indicator;
+}
+
+describe('Progress', () => {
+ test('exposes a progressbar role', () => {
+ render(<Progress value={42} aria-label="Downloading" />);
+
+ expect(screen.getByRole('progressbar')).not.toBeNull();
+ });
+
+ test('a determinate value reaches the accessibility tree', () => {
+ // The reason this primitive diverges from upstream: shadcn destructures
+ // `value` and never forwards it, so this attribute would be absent.
+ render(<Progress value={42} aria-label="Downloading" />);
+
+ expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBe('42');
+ });
+
+ test('a determinate value paints the track to that percentage', () => {
+ const { container } = render(<Progress value={42} aria-label="Downloading" />);
+
+ expect(indicatorOf(container).style.transform).toBe('translateX(-58%)');
+ });
+
+ test('a null value announces nothing rather than an invented number', () => {
+ render(<Progress value={null} aria-label="Sending report" />);
+
+ const bar = screen.getByRole('progressbar');
+
+ expect(bar.getAttribute('aria-valuenow')).toBeNull();
+ expect(bar.getAttribute('data-state')).toBe('indeterminate');
+ });
+
+ test('an indeterminate bar still paints the requested fill', () => {
+ // A time-eased estimate: the bar moves, but no percentage is claimed.
+ const { container } = render(
+ <Progress value={null} indeterminateFillPercent={30} aria-label="Sending report" />,
+ );
+
+ expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBeNull();
+ expect(indicatorOf(container).style.transform).toBe('translateX(-70%)');
+ });
+
+ test('indeterminate fill is ignored once a real value arrives', () => {
+ // Both call sites pass a constant fallback alongside a live value, so the
+ // fallback must never win when the value is measurable.
+ const { container } = render(
+ <Progress value={90} indeterminateFillPercent={40} aria-label="Downloading" />,
+ );
+
+ expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBe('90');
+ expect(indicatorOf(container).style.transform).toBe('translateX(-10%)');
+ });
+
+ test('an indeterminate bar with no fill requested stays empty', () => {
+ const { container } = render(<Progress value={null} aria-label="Sending report" />);
+
+ expect(indicatorOf(container).style.transform).toBe('translateX(-100%)');
+ });
+
+ test('caller className composes with the base classes rather than replacing them', () => {
+ const { container } = render(
+ <Progress value={10} aria-label="Downloading" className="h-1.5 bg-secondary" />,
+ );
+
+ const rootClassName = container.querySelector('[data-slot="progress"]')?.getAttribute('class');
+
+ expectVisualClassTokens(rootClassName, ['rounded-full', 'w-full', 'h-1.5', 'bg-secondary']);
+
+ // Presence alone would still pass if `cn` degenerated to plain `clsx`: both
+ // the base and the override would sit in the attribute and source order
+ // would silently decide. The displaced tokens have to be gone.
+ expectVisualClassTokensAbsent(rootClassName, ['bg-muted']);
+ // `h-1` is a prefix of the `h-1.5` that replaced it, so substring absence
+ // cannot express this one — the height override needs an exact-token check.
+ expect((rootClassName ?? '').split(/\s+/)).not.toContain('h-1');
+ });
+
+ test('a value is scaled by max rather than read as a literal percentage', () => {
+ // Radix announces `value/max`; painting `value` directly would show a full
+ // bar while the accessibility tree said half.
+ const { container } = render(<Progress value={100} max={200} aria-label="Downloading" />);
+
+ expect(screen.getByRole('progressbar').getAttribute('aria-valuetext')).toBe('50%');
+ expect(indicatorOf(container).style.transform).toBe('translateX(-50%)');
+ });
+
+ test('an out-of-range value paints the indeterminate fill Radix falls back to', () => {
+ // Radix demotes a value above max to indeterminate. Treating it as a literal
+ // percentage would translate the indicator off the right edge of its track.
+ // Radix scolds the caller on the way, which is how this test proves it is
+ // exercising the demotion rather than passing by coincidence.
+ const scold = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+ try {
+ const { container } = render(
+ <Progress value={150} indeterminateFillPercent={40} aria-label="Downloading" />,
+ );
+
+ expect(scold).toHaveBeenCalled();
+ expect(screen.getByRole('progressbar').getAttribute('aria-valuenow')).toBeNull();
+ expect(indicatorOf(container).style.transform).toBe('translateX(-60%)');
+ } finally {
+ scold.mockRestore();
+ }
+ });
+
+ test('an impossible indeterminate fill is clamped to the track', () => {
+ const { container } = render(
+ <Progress value={null} indeterminateFillPercent={400} aria-label="Sending report" />,
+ );
+
+ expect(indicatorOf(container).style.transform).toBe('translateX(-0%)');
+ });
+
+ test('the fill transition stands still under prefers-reduced-motion', () => {
+ const { container } = render(<Progress value={42} aria-label="Downloading" />);
+
+ expectVisualClassTokens(indicatorOf(container).getAttribute('class'), [
+ 'transition-all',
+ 'motion-reduce:transition-none',
+ ]);
+ });
+
+ test('accepts a visible status line as its accessible name', () => {
+ // Preferred over inventing a second string: the name matches what is on
+ // screen, and no new copy needs translating.
+ render(
+ <>
+ <span id="status-line">Downloading ripgrep 14.1.0</span>
+ <Progress value={25} aria-labelledby="status-line" />
+ </>,
+ );
+
+ expect(screen.getByRole('progressbar').getAttribute('aria-labelledby')).toBe('status-line');
+ expect(screen.getByLabelText('Downloading ripgrep 14.1.0')).not.toBeNull();
+ });
+});
diff --git a/packages/app/src/components/ui/progress.tsx b/packages/app/src/components/ui/progress.tsx
new file mode 100644
index 000000000..fc996f00d
--- /dev/null
+++ b/packages/app/src/components/ui/progress.tsx
@@ -0,0 +1,79 @@
+import { Progress as ProgressPrimitive } from 'radix-ui';
+import type * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+/**
+ * Horizontal progress bar, determinate or indeterminate.
+ *
+ * Installed from shadcn/ui with three deliberate divergences, recorded so a
+ * future `shadcn diff` reviewer knows the drift is intentional rather than rot:
+ *
+ * 1. `value` is forwarded to the Radix root. Upstream destructures it and uses
+ * it only to compute the indicator transform, so the root never sees a value
+ * and every bar reports as indeterminate — the visual fills while the
+ * accessible `aria-valuenow` stays absent. Forwarding is what makes a
+ * determinate bar actually announce its position.
+ * 2. `indeterminateFillPercent` paints the track while `value` stays null.
+ * Radix renders `value={null}` as an empty bar, but some progress is honestly
+ * unknowable (no byte counts cross the boundary) and yet still wants a moving
+ * bar. Splitting the two lets a call site show motion without asserting a
+ * percentage it cannot measure — assistive tech must not hear invented
+ * numbers.
+ * 3. `motion-reduce:transition-none` on the indicator, matching what `spinner`
+ * does for its spin: reduced motion is the default rather than something
+ * each call site has to remember. Upstream eases the fill unconditionally.
+ *
+ * So: `value` drives what is announced, `indeterminateFillPercent` drives what is
+ * painted when nothing can be announced. It is ignored whenever `value` is a
+ * determinate number.
+ *
+ * The fill mirrors Radix's own validity rule rather than treating `value` as a
+ * literal percentage, so what is painted can never disagree with what is
+ * announced: Radix scales the announcement by `max` and demotes an out-of-range
+ * `value` back to indeterminate, and the fill has to follow it in both cases or
+ * the bar paints a number nothing is claiming.
+ *
+ * A progress bar needs an accessible name. Prefer `aria-labelledby` pointing at
+ * the visible status text over inventing a second string, and mark any adjacent
+ * percentage text `aria-hidden` once the bar carries the number itself.
+ */
+function Progress({
+ className,
+ value,
+ max,
+ indeterminateFillPercent,
+ ...props
+}: React.ComponentProps<typeof ProgressPrimitive.Root> & {
+ indeterminateFillPercent?: number;
+}) {
+ const resolvedMax = typeof max === 'number' && max > 0 ? max : 100;
+ const requestedFill =
+ typeof value === 'number' && value >= 0 && value <= resolvedMax
+ ? (value / resolvedMax) * 100
+ : (indeterminateFillPercent ?? 0);
+ // The determinate branch is in range by construction; this clamps a caller
+ // that asks for an impossible indeterminate fill.
+ const fillPercent = Math.min(100, Math.max(0, requestedFill));
+
+ return (
+ <ProgressPrimitive.Root
+ data-slot="progress"
+ value={value}
+ max={max}
+ className={cn(
+ 'relative flex h-1 w-full items-center overflow-x-hidden rounded-full bg-muted',
+ className,
+ )}
+ {...props}
+ >
+ <ProgressPrimitive.Indicator
+ data-slot="progress-indicator"
+ className="size-full flex-1 bg-primary transition-all motion-reduce:transition-none"
+ style={{ transform: `translateX(-${100 - fillPercent}%)` }}
+ />
+ </ProgressPrimitive.Root>
+ );
+}
+
+export { Progress };