Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(progressbar): add opt-in target markers (#4599)

freddymetad9f2985c3cd0
diff --git a/.changeset/progressbar-target-markers.md b/.changeset/progressbar-target-markers.md
new file mode 100644
index 0000000000..71e7159685
--- /dev/null
+++ b/.changeset/progressbar-target-markers.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] ProgressBar: add an opt-in `marks` prop that draws fixed target lines on the track at values in the same 0..max scale as `value` (e.g. a goal or threshold). Marks stay visible whether progress is below or past them; each mark requires a `label` (its accessible name, revealed via a tooltip on hover/focus), and marks are ignored in indeterminate mode. The mark tick is directly themeable via the `progressbar-mark` target — a theme sets `backgroundColor`, `width`, and `height` on it (a larger height makes a "flag" tick that overhangs the bar symmetrically above and below). The mark tooltip is loaded lazily, so a ProgressBar with no marks bundles no tooltip code. Named `marks` (with a `ProgressBarMark` type) to match the `marks` prop on Slider.
+@freddymeta
diff --git a/apps/storybook/stories/ProgressBar.stories.tsx b/apps/storybook/stories/ProgressBar.stories.tsx
index 5c09669221..9950724a6f 100644
--- a/apps/storybook/stories/ProgressBar.stories.tsx
+++ b/apps/storybook/stories/ProgressBar.stories.tsx
@@ -77,31 +77,11 @@ export const Variants: Story = {
gap: '16px',
width: '300px',
}}>
- <ProgressBar
- value={60}
- label="Accent"
- variant="accent"
- hasValueLabel
- />
- <ProgressBar
- value={80}
- label="Success"
- variant="success"
- hasValueLabel
- />
- <ProgressBar
- value={50}
- label="Warning"
- variant="warning"
- hasValueLabel
- />
+ <ProgressBar value={60} label="Accent" variant="accent" hasValueLabel />
+ <ProgressBar value={80} label="Success" variant="success" hasValueLabel />
+ <ProgressBar value={50} label="Warning" variant="warning" hasValueLabel />
<ProgressBar value={92} label="Error" variant="error" hasValueLabel />
- <ProgressBar
- value={35}
- label="Neutral"
- variant="neutral"
- hasValueLabel
- />
+ <ProgressBar value={35} label="Neutral" variant="neutral" hasValueLabel />
</div>
),
};
@@ -214,3 +194,65 @@ export const IndeterminateVariants: Story = {
</div>
),
};
+
+export const WithTargetMark: Story = {
+ args: {
+ value: 45,
+ label: 'Fundraiser',
+ hasValueLabel: true,
+ marks: [{value: 80, label: 'Goal'}],
+ },
+};
+
+export const WithMultipleMarks: Story = {
+ args: {
+ value: 55,
+ label: 'Quarterly milestones',
+ hasValueLabel: true,
+ marks: [
+ {value: 25, label: 'Q1 target'},
+ {value: 50, label: 'Q2 target'},
+ {value: 80, label: 'Stretch goal'},
+ ],
+ },
+};
+
+export const ProgressPastMark: Story = {
+ args: {
+ value: 92,
+ label: 'Budget used',
+ hasValueLabel: true,
+ variant: 'warning',
+ marks: [{value: 75, label: 'Budget cap'}],
+ },
+};
+
+export const ThemedMarks: Story = {
+ // Marks are themeable directly via the `progressbar-mark` target: a theme sets
+ // `backgroundColor`, `width`, and `height` on it with `defineTheme` — no
+ // dedicated CSS vars needed. A taller height overhangs the bar symmetrically
+ // above and below. Here we set the properties via a scoped style block so the
+ // effect is visible without a full theme.
+ render: () => (
+ <div style={{width: '320px'}}>
+ <style>{`
+ .themed-marks-demo .astryx-progressbar-mark {
+ background-color: red;
+ width: 3px;
+ height: 14px;
+ }
+ `}</style>
+ <div className="themed-marks-demo">
+ <ProgressBar
+ value={55}
+ label="Themed target marks"
+ hasValueLabel
+ marks={[
+ {value: 25, label: 'Lower bound'},
+ {value: 80, label: 'Upper bound'},
+ ]}
+ />
+ </div>
+ </div>
+ ),
+};
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index 7a87f950d7..97c27900da 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -56,6 +56,12 @@ export const docs = {
description: 'Animated loading indicator for unknown progress.',
default: 'false',
},
+ {
+ name: 'marks',
+ type: 'ReadonlyArray<{value: number; label: string}>',
+ description:
+ 'Fixed target marks drawn on the track at values in the same 0..max scale as value (e.g. a goal line). They stay visible whether progress is below or past them. Each mark requires a label — it is the mark\'s accessible name and the text revealed via a tooltip on hover/focus. Ignored when indeterminate.',
+ },
{
name: 'isDisabled',
type: 'boolean',
@@ -74,6 +80,7 @@ export const docs = {
{className: 'astryx-progressbar', visualProps: ['variant']},
{className: 'astryx-progressbar-fill', visualProps: ['variant']},
{className: 'astryx-progressbar-track'},
+ {className: 'astryx-progressbar-mark'},
],
},
usage: {
@@ -143,6 +150,12 @@ export const docsZh = {
description: '用于未知进度的动画加载指示器。',
default: 'false',
},
+ {
+ name: 'marks',
+ type: 'ReadonlyArray<{value: number; label: string}>',
+ description:
+ '在轨道上按与 value 相同的 0..max 刻度绘制的固定目标标记(例如目标线)。无论进度低于还是超过它们都保持可见。每个标记都必须提供 label——它既是标记的无障碍名称,也是悬停/聚焦时通过工具提示显示的文本。不确定模式下忽略。',
+ },
{
name: 'isDisabled',
type: 'boolean',
@@ -161,6 +174,7 @@ export const docsZh = {
{className: 'astryx-progressbar', visualProps: ['variant']},
{className: 'astryx-progressbar-fill', visualProps: ['variant']},
{className: 'astryx-progressbar-track'},
+ {className: 'astryx-progressbar-mark'},
],
},
usage: {
@@ -202,6 +216,7 @@ export const docsDense = {
formatValueLabel: 'Custom value label formatter; defaults to percentage string.',
variant: 'Semantic color variant.',
isIndeterminate: 'Animated loading indicator for unknown progress.',
+ marks: 'Fixed target marks ({value, label?}) drawn on the track in the 0..max scale; stay visible past the fill. A label reveals a tooltip on hover/focus. Ignored when indeterminate.',
isDisabled: 'Visually disabled: grays out fill and text.',
xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
},
diff --git a/packages/core/src/ProgressBar/ProgressBar.test.tsx b/packages/core/src/ProgressBar/ProgressBar.test.tsx
index e53b1d26d6..98f0599463 100644
--- a/packages/core/src/ProgressBar/ProgressBar.test.tsx
+++ b/packages/core/src/ProgressBar/ProgressBar.test.tsx
@@ -1,9 +1,18 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
-import {describe, it, expect} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {describe, it, expect, beforeAll} from 'vitest';
+import {render, screen, waitFor} from '@testing-library/react';
import {ProgressBar} from './ProgressBar';
+// A labeled mark wraps the tick in a lazily-loaded Tooltip (React.lazy +
+// Suspense). Preload that chunk once so the Tooltip (and its
+// aria-describedby) is present synchronously on first render, keeping these
+// tests deterministic rather than racing the dynamic import's default 1s
+// Suspense timeout.
+beforeAll(async () => {
+ await import('./ProgressBarMarkTooltip');
+});
+
describe('ProgressBar', () => {
it('renders with default props', () => {
render(<ProgressBar value={50} label="Progress" />);
@@ -277,4 +286,333 @@ describe('ProgressBar', () => {
expect(css).toMatch(/:is\(\[dir="rtl"\][^)]*\)[^{]*\{\s*animation-name:/);
});
});
+
+ // Target marks
+ describe('target marks', () => {
+ const MARK = '.astryx-progressbar-mark';
+
+ it('renders no mark elements when marks is omitted', () => {
+ const {container} = render(<ProgressBar value={50} label="Progress" />);
+ expect(container.querySelectorAll(MARK)).toHaveLength(0);
+ });
+
+ it('renders no mark elements for an empty marks array', () => {
+ const {container} = render(
+ <ProgressBar value={50} label="Progress" marks={[]} />,
+ );
+ expect(container.querySelectorAll(MARK)).toHaveLength(0);
+ });
+
+ it('renders a mark at the position matching its value', () => {
+ const {container} = render(
+ <ProgressBar
+ value={40}
+ label="Progress"
+ marks={[{value: 80, label: 'M'}]}
+ />,
+ );
+ const marks = container.querySelectorAll<HTMLElement>(MARK);
+ expect(marks).toHaveLength(1);
+ // value 80 of max 100 -> 80% along the track (RTL-safe logical property).
+ expect(marks[0].style.insetInlineStart).toBe('80%');
+ });
+
+ it('positions marks relative to a custom max', () => {
+ const {container} = render(
+ <ProgressBar
+ value={1}
+ max={5}
+ label="Steps"
+ marks={[{value: 4, label: 'M'}]}
+ />,
+ );
+ const marks = container.querySelectorAll<HTMLElement>(MARK);
+ // value 4 of max 5 -> 80%.
+ expect(marks[0].style.insetInlineStart).toBe('80%');
+ });
+
+ it('keeps a mark past the current value visible', () => {
+ // A mark beyond the fill still renders — it layers above the fill.
+ const {container} = render(
+ <ProgressBar
+ value={20}
+ label="Progress"
+ marks={[{value: 90, label: 'M'}]}
+ />,
+ );
+ const marks = container.querySelectorAll<HTMLElement>(MARK);
+ expect(marks).toHaveLength(1);
+ expect(marks[0].style.insetInlineStart).toBe('90%');
+ });
+
+ it('renders multiple marks', () => {
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[
+ {value: 25, label: 'M'},
+ {value: 50, label: 'M'},
+ {value: 80, label: 'M'},
+ ]}
+ />,
+ );
+ expect(container.querySelectorAll(MARK)).toHaveLength(3);
+ });
+
+ it('clamps out-of-range mark positions to the track edges', () => {
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[
+ {value: -10, label: 'M'},
+ {value: 150, label: 'M'},
+ ]}
+ />,
+ );
+ const marks = container.querySelectorAll<HTMLElement>(MARK);
+ expect(marks).toHaveLength(2);
+ expect(marks[0].style.insetInlineStart).toBe('0%');
+ expect(marks[1].style.insetInlineStart).toBe('100%');
+ });
+
+ it('drops non-finite mark values', () => {
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[
+ {value: NaN, label: 'M'},
+ {value: Infinity, label: 'M'},
+ {value: 60, label: 'M'},
+ ]}
+ />,
+ );
+ const marks = container.querySelectorAll<HTMLElement>(MARK);
+ expect(marks).toHaveLength(1);
+ expect(marks[0].style.insetInlineStart).toBe('60%');
+ });
+
+ it('does not render marks in indeterminate mode', () => {
+ const {container} = render(
+ <ProgressBar
+ isIndeterminate
+ label="Loading"
+ marks={[{value: 80, label: 'M'}]}
+ />,
+ );
+ expect(container.querySelectorAll(MARK)).toHaveLength(0);
+ });
+
+ it('renders every mark as a focusable trigger (label is required, never decorative)', () => {
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'Goal'}]}
+ />,
+ );
+ const mark = container.querySelector<HTMLElement>(MARK)!;
+ // A mark always stands for something meaningful, so it is never
+ // aria-hidden and is always keyboard-focusable to reveal its label.
+ expect(mark).not.toHaveAttribute('aria-hidden');
+ expect(mark).toHaveAttribute('tabindex', '0');
+ // The name comes from the Tooltip (aria-describedby), not a role/label on
+ // the tick itself, so the progressbar's own subtree stays clean.
+ expect(mark).not.toHaveAttribute('role');
+ expect(mark).not.toHaveAttribute('aria-label');
+ });
+
+ it('reveals a labeled mark via a focusable Tooltip trigger', async () => {
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'Goal'}]}
+ />,
+ );
+ // Focusable so keyboard users can reveal the label; named via the
+ // Tooltip's aria-describedby rather than a labeled child of the bar.
+ // The Tooltip loads lazily (Suspense), so re-query the live element and
+ // wait for it to attach aria-describedby.
+ const mark0 = container.querySelector<HTMLElement>(MARK)!;
+ expect(mark0).toHaveAttribute('tabindex', '0');
+ expect(mark0).not.toHaveAttribute('aria-hidden');
+ await waitFor(() =>
+ expect(container.querySelector(MARK)).toHaveAttribute(
+ 'aria-describedby',
+ ),
+ );
+ const mark = container.querySelector<HTMLElement>(MARK)!;
+ const tip = document.getElementById(
+ mark.getAttribute('aria-describedby')!,
+ );
+ expect(tip).toHaveTextContent('Goal');
+ });
+
+ it('keeps the progressbar element free of role="img"/aria-label children', () => {
+ // Marks are children of role="progressbar" (unchanged DOM), but a
+ // mark uses a Tooltip (aria-describedby) rather than a
+ // role="img"+aria-label child, so nothing muddies what SRs announce for
+ // the bar.
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'Goal'}]}
+ />,
+ );
+ const progressbar = screen.getByRole('progressbar');
+ // Mark is a child of the progressbar (DOM unchanged from main).
+ expect(progressbar.querySelector(MARK)).not.toBeNull();
+ // But it is not a labeled graphic that pollutes the a11y subtree.
+ expect(progressbar.querySelector('[role="img"]')).toBeNull();
+ expect(progressbar.querySelector('[aria-label]')).toBeNull();
+ expect(container.querySelectorAll(MARK)).toHaveLength(1);
+ });
+
+ it('does not add mark info to the progressbar aria-valuetext', () => {
+ render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'Goal'}]}
+ />,
+ );
+ const progressbar = screen.getByRole('progressbar');
+ expect(progressbar.getAttribute('aria-valuetext')).toBe('50%');
+ });
+
+ it('renders marks as children of the progressbar (unchanged DOM)', () => {
+ // Marks stay children of role="progressbar", after the fill — the same
+ // shape as main. The fill remains the first child.
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'M'}]}
+ />,
+ );
+ const progressbar = screen.getByRole('progressbar');
+ const fill = progressbar.firstElementChild as HTMLElement;
+ expect(fill.style.width).toBe('50%');
+ expect(fill.classList.contains('astryx-progressbar-mark')).toBe(false);
+ const mark = container.querySelector<HTMLElement>(MARK)!;
+ expect(mark.closest('[role="progressbar"]')).toBe(progressbar);
+ expect(container.querySelectorAll(MARK)).toHaveLength(1);
+ });
+
+ it('does not clip marks in determinate mode (track carries no overflow:hidden)', () => {
+ // In determinate mode the track must NOT clip, so a themed taller mark
+ // can overhang the bar. (Indeterminate mode re-adds the clip — covered
+ // separately — but marks are suppressed there, so nothing overhangs.)
+ render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'M'}]}
+ />,
+ );
+ const progressbar = screen.getByRole('progressbar');
+ const trackClass = Array.from(progressbar.classList).find(c =>
+ c.startsWith('x'),
+ );
+ let css = '';
+ for (const sheet of Array.from(document.styleSheets)) {
+ try {
+ for (const rule of Array.from(sheet.cssRules)) {
+ css += rule.cssText + '\n';
+ }
+ } catch {
+ // ignore cross-origin sheets
+ }
+ }
+ css += Array.from(document.querySelectorAll('style'))
+ .map(s => s.textContent || '')
+ .join('\n');
+ // The atomic class that would set overflow:hidden must not be applied to
+ // the track. Sanity-check the bar still rendered with a StyleX class.
+ expect(trackClass).toBeDefined();
+ // No rule targeting the track's classes sets overflow:hidden. (StyleX
+ // atomic classes are unique per declaration; if overflow:hidden were on
+ // the track we'd see it applied. We assert the track element's computed
+ // intent by checking no overflow:hidden atomic is in its class list's
+ // rules — simplest robust check: the track style object omits it.)
+ const trackHasOverflowHidden = Array.from(progressbar.classList).some(
+ cls => {
+ const re = new RegExp(
+ `\\.${cls}\\b[^{]*\\{[^}]*overflow:\\s*hidden`,
+ 'i',
+ );
+ return re.test(css);
+ },
+ );
+ expect(trackHasOverflowHidden).toBe(false);
+ });
+
+ it('clips the track in indeterminate mode (the sliding fill must not escape)', () => {
+ // Regression: the indeterminate fill slides from translateX -100% to
+ // 250%, deliberately overshooting the track, and relies on the track
+ // clipping it to the visible window. Determinate mode drops the clip so
+ // marks can overhang — indeterminate mode must keep it.
+ render(<ProgressBar isIndeterminate label="Loading" />);
+ const progressbar = screen.getByRole('progressbar');
+ let css = '';
+ for (const sheet of Array.from(document.styleSheets)) {
+ try {
+ for (const rule of Array.from(sheet.cssRules)) {
+ css += rule.cssText + '\n';
+ }
+ } catch {
+ // ignore cross-origin sheets
+ }
+ }
+ css += Array.from(document.querySelectorAll('style'))
+ .map(s => s.textContent || '')
+ .join('\n');
+ const trackHasOverflowHidden = Array.from(progressbar.classList).some(
+ cls => {
+ const re = new RegExp(
+ `\\.${cls}\\b[^{]*\\{[^}]*overflow:\\s*hidden`,
+ 'i',
+ );
+ return re.test(css);
+ },
+ );
+ expect(trackHasOverflowHidden).toBe(true);
+ });
+
+ it('renders the mark on the stable progressbar-mark target, centered for symmetric overhang', () => {
+ // The mark's width/height/color are directly overridable via the
+ // `progressbar-mark` theme target (no dedicated CSS vars). It is centered
+ // on the track (translate -50%,-50%) so a themed taller tick overhangs the
+ // bar symmetrically above and below without being clipped.
+ const {container} = render(
+ <ProgressBar
+ value={50}
+ label="Progress"
+ marks={[{value: 80, label: 'M'}]}
+ />,
+ );
+ const mark = container.querySelector<HTMLElement>(MARK)!;
+ expect(mark.className).toContain('astryx-progressbar-mark');
+ let css = '';
+ for (const sheet of Array.from(document.styleSheets)) {
+ try {
+ for (const rule of Array.from(sheet.cssRules)) {
+ css += rule.cssText + '\n';
+ }
+ } catch {
+ // ignore cross-origin sheets
+ }
+ }
+ css += Array.from(document.querySelectorAll('style'))
+ .map(s => s.textContent || '')
+ .join('\n');
+ // Centered so any themed overhang stays symmetric.
+ expect(css).toMatch(/translate\(-50%,\s*-50%\)/);
+ expect(container.querySelectorAll(MARK)).toHaveLength(1);
+ });
+ });
});
diff --git a/packages/core/src/ProgressBar/ProgressBar.tsx b/packages/core/src/ProgressBar/ProgressBar.tsx
index acf379e792..3b9630a9fe 100644
--- a/packages/core/src/ProgressBar/ProgressBar.tsx
+++ b/packages/core/src/ProgressBar/ProgressBar.tsx
@@ -11,12 +11,13 @@
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/ProgressBar/ProgressBar.doc.mjs (props table, features, implementation notes)
* - /packages/core/src/ProgressBar/ProgressBar.test.tsx (tests for new/changed behavior)
+ * - /packages/core/src/ProgressBar/ProgressBarMarkTooltip.tsx (the lazy Tooltip wrapper for labeled marks)
* - /packages/core/src/ProgressBar/index.ts (exports if types change)
* - /apps/storybook/stories/ProgressBar.stories.tsx (storybook stories)
* - /packages/cli/assets/templates/blocks/components/ProgressBar/ (showcase blocks)
*/
-import {useId} from 'react';
+import {lazy, Suspense, useId} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
@@ -34,12 +35,43 @@ import {themeProps} from '../utils/themeProps';
import {VisuallyHidden} from '../VisuallyHidden';
import type {ProgressBarVariantMap} from './index';
+// Every mark is wrapped in a Tooltip (marks always carry a label), so load it
+// lazily: a ProgressBar with no marks never bundles the Tooltip chunk. While it
+// loads, the Suspense fallback shows the bare mark, so nothing disappears; the
+// tooltip simply attaches once the chunk is ready.
+const LazyProgressBarMarkTooltip = lazy(
+ async () => import('./ProgressBarMarkTooltip'),
+);
+
/**
* Progress bar variant type — maps to semantic color tokens.
* Extensible via module augmentation of ProgressBarVariantMap.
*/
export type ProgressBarVariant = keyof ProgressBarVariantMap;
+/**
+ * A fixed target mark drawn on the progress track.
+ *
+ * Positioned by `value` in the same `0..max` scale as the bar's `value` prop —
+ * mirroring the object shape of Slider's `marks` so the two APIs stay
+ * consistent.
+ */
+export interface ProgressBarMark {
+ /**
+ * Position of the mark in the same `0..max` scale as `value`. Values
+ * outside the range are clamped to the track edges.
+ */
+ value: number;
+ /**
+ * Names the mark. A mark stands for something meaningful on the track — a
+ * goal, a threshold, a quarter target — so a label is required: it is the
+ * mark's accessible name and the text revealed in a `Tooltip` on hover and
+ * keyboard focus. Can be the value itself (e.g. `'70%'`) or something richer
+ * (e.g. `'Q1 target: 50%'`).
+ */
+ label: string;
+}
+
export interface ProgressBarProps extends BaseProps<HTMLDivElement> {
/** Ref forwarded to the root element */
ref?: React.Ref<HTMLDivElement>;
@@ -87,6 +119,14 @@ export interface ProgressBarProps extends BaseProps<HTMLDivElement> {
* @default false
*/
isIndeterminate?: boolean;
+ /**
+ * Target marks drawn on the track at fixed points in the same `0..max`
+ * scale as `value` — e.g. a goal line. Marks stay visible whether progress
+ * is below or past them. Each mark's required `label` names it for assistive
+ * tech and is revealed via a `Tooltip` on hover/focus. Ignored when
+ * `isIndeterminate` is true.
+ */
+ marks?: ReadonlyArray<ProgressBarMark>;
/**
* When true, the progress bar is visually disabled — the fill bar and
* text use disabled colors. Use for canceled or inactive operations.
@@ -170,11 +210,27 @@ const styles = stylex.create({
whiteSpace: 'nowrap',
borderWidth: 0,
},
+ // The `role="progressbar"` element. In determinate mode it does NOT clip its
+ // content (`overflow` stays visible) so a themed mark taller than the bar can
+ // overhang it; the determinate fill rounds its own corners via `border-radius`
+ // (see `fill`) and is always inside the track box, so dropping the clip does
+ // not change its appearance at any progress. Indeterminate mode re-adds the
+ // clip via `trackClipped` (see below) — its sliding fill travels outside the
+ // track and must be clipped, and marks are ignored while indeterminate, so
+ // there is nothing to overhang.
track: {
+ position: 'relative',
width: '100%',
height: '8px',
backgroundColor: colorVars['--color-background-muted'],
borderRadius: radiusVars['--radius-full'],
+ },
+ // Indeterminate-only clip. The indeterminate fill slides from translateX
+ // -100% to 250%, so it deliberately overshoots the track on both sides and
+ // relies on the track clipping it to the visible window. Applied only when
+ // `isIndeterminate` (marks are suppressed then, so nothing needs to overhang)
+ // so it never re-clips a themed tall mark in determinate mode.
+ trackClipped: {
overflow: 'hidden',
},
fill: {
@@ -199,6 +255,35 @@ const styles = stylex.create({
animationTimingFunction: 'ease-in-out',
animationIterationCount: 'infinite',
},
+ // A mark is a vertical tick centered on the track, a child of the
+ // `role="progressbar"` element (unchanged DOM). The track no longer clips, so
+ // its height — 8px by default, directly overridable via the `progressbar-mark`
+ // theme target — may exceed the bar and overhang; the centering translate
+ // keeps any overhang symmetric. Positioned horizontally via `insetInlineStart`;
+ // the translate mirrors under RTL.
+ mark: {
+ position: 'absolute',
+ top: '50%',
+ width: 2,
+ height: 8,
+ // Defaults to text-primary. Directly overridable via the `progressbar-mark`
+ // theme target — a theme can set `backgroundColor`, `width`, and `height`
+ // (e.g. a taller "flag" tick that overhangs the bar, or per-variant
+ // contrast) with `defineTheme`; no dedicated CSS vars needed.
+ backgroundColor: colorVars['--color-text-primary'],
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
+ },
+ transform: {
+ default: 'translate(-50%, -50%)',
+ ':is([dir="rtl"] *)': 'translate(50%, -50%)',
+ },
+ },
});
const variantStyles = stylex.create({
@@ -236,7 +321,8 @@ function defaultFormatValueLabel(value: number, max: number): string {
*
* ProgressBar is intentionally minimal — compose additional labels, status
* icons, and descriptions alongside the bar using layout components rather
- * than adding props to ProgressBar itself.
+ * than adding props to ProgressBar itself. The exception is on-track content
+ * like `marks`, which are positioned by value over the track.
*
* Styles use Astryx theme tokens via StyleX.
* Wrap your app in <Theme> to apply a theme.
@@ -248,6 +334,21 @@ function defaultFormatValueLabel(value: number, max: number): string {
* <ProgressBar value={3.2} max={5} label="Disk usage" hasValueLabel
* formatValueLabel={(v, m) => `${v} GB / ${m} GB`} />
* <ProgressBar value={30} label="Canceled" isDisabled hasValueLabel />
+ * <ProgressBar value={45} label="Fundraiser" marks={[{value: 80, label: 'Goal'}]} />
+ * ```
+ *
+ * A mark's height, width, and color are directly themeable via the
+ * `progressbar-mark` target — e.g. a taller "goal flag" tick that overhangs the
+ * bar (centered, so the overhang is symmetric):
+ *
+ * @example
+ * ```
+ * defineTheme({
+ * name: 'campaign',
+ * components: {
+ * 'progressbar-mark': {base: {height: '16px', backgroundColor: 'red'}},
+ * },
+ * });
* ```
*/
export function ProgressBar({
@@ -260,6 +361,7 @@ export function ProgressBar({
variant = 'accent',
isIndeterminate = false,
isDisabled = false,
+ marks,
xstyle,
className,
style,
@@ -282,6 +384,20 @@ export function ProgressBar({
const fillVariant = isDisabled ? 'disabled' : variant;
+ // Marks make no sense without a determinate value, so they are only drawn
+ // in determinate mode. Non-finite mark values are dropped; the rest are
+ // clamped to the track edges, matching the bar's own `clampedValue`.
+ const resolvedMarks =
+ !isIndeterminate && marks
+ ? marks
+ .filter(mark => Number.isFinite(mark.value))
+ .map(mark => {
+ const clamped = Math.min(Math.max(0, mark.value), safeMax);
+ const pct = safeMax > 0 ? (clamped / safeMax) * 100 : 0;
+ return {value: mark.value, label: mark.label, pct};
+ })
+ : [];
+
return (
<div
ref={ref}
@@ -319,7 +435,10 @@ export function ProgressBar({
<VisuallyHidden id={labelId}>{label}</VisuallyHidden>
)}
- {/* Progress track */}
+ {/* Progress track — the `role="progressbar"` element, holding the fill
+ and marks as its children (unchanged DOM shape). It no longer clips
+ (`overflow` is visible), so a themed taller mark can overhang it;
+ the fill preserves its rounded shape via its own `border-radius`. */}
<div
role="progressbar"
aria-valuenow={isIndeterminate ? undefined : clampedValue}
@@ -329,7 +448,7 @@ export function ProgressBar({
aria-valuetext={isIndeterminate ? undefined : valueText}
{...mergeProps(
themeProps('progressbar-track'),
- stylex.props(styles.track),
+ stylex.props(styles.track, isIndeterminate && styles.trackClipped),
)}>
{isIndeterminate ? (
<div
@@ -350,6 +469,35 @@ export function ProgressBar({
style={{width: `${percentage}%`}}
/>
)}
+ {/* Target marks — children of the progressbar element (unchanged),
+ layered above the fill so they show whether progress is below or
+ past them. Each mark is labeled, so it is a focusable Tooltip
+ trigger: the label is visible on hover/focus and names the mark for
+ assistive tech via the Tooltip's aria-describedby, without adding a
+ labeled child to the progressbar's own a11y subtree. */}
+ {resolvedMarks.map(mark => {
+ // The tick element. It is both the Tooltip's anchor and the Suspense
+ // fallback shown while the lazy Tooltip chunk loads, so the tick is
+ // always visible and the label attaches once ready. The list `key`
+ // lives on the mapped <Suspense>, not here.
+ const markEl = (
+ <span
+ tabIndex={0}
+ {...mergeProps(
+ themeProps('progressbar-mark'),
+ stylex.props(styles.mark),
+ )}
+ style={{insetInlineStart: `${mark.pct}%`}}
+ />
+ );
+ return (
+ <Suspense key={`${mark.value}:${mark.label}`} fallback={markEl}>
+ <LazyProgressBarMarkTooltip content={mark.label}>
+ {markEl}
+ </LazyProgressBarMarkTooltip>
+ </Suspense>
+ );
+ })}
</div>
</div>
);
diff --git a/packages/core/src/ProgressBar/ProgressBarMarkTooltip.tsx b/packages/core/src/ProgressBar/ProgressBarMarkTooltip.tsx
new file mode 100644
index 0000000000..55ec0f8a43
--- /dev/null
+++ b/packages/core/src/ProgressBar/ProgressBarMarkTooltip.tsx
@@ -0,0 +1,43 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ProgressBarMarkTooltip.tsx
+ * @input Uses React, Tooltip, the mark element to wrap, and its label
+ * @output Default-exports the lazily-loaded Tooltip wrapper for a labeled mark
+ * @position Split out of ProgressBar so the Tooltip only loads when a mark is
+ * actually rendered — a ProgressBar with no marks never bundles the Tooltip
+ * chunk.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/ProgressBar/ProgressBar.tsx (the lazy() + Suspense wrapper)
+ * - /packages/core/src/ProgressBar/ProgressBar.test.tsx
+ */
+
+import type {ReactElement} from 'react';
+import {Tooltip} from '../Tooltip/Tooltip';
+
+export interface ProgressBarMarkTooltipProps {
+ /** The mark's accessible name / visible tooltip text. */
+ content: string;
+ /** The bare mark element the tooltip anchors to (also the Suspense fallback). */
+ children: ReactElement;
+}
+
+/**
+ * Wraps a labeled mark in a `Tooltip` that reveals its label on hover and
+ * keyboard focus. Placement and focus behavior match the inline usage this
+ * split replaced (`placement="above"`, `focusTrigger="always"`), so the
+ * rendered result is identical — only the load timing changes.
+ */
+export default function ProgressBarMarkTooltip({
+ content,
+ children,
+}: ProgressBarMarkTooltipProps): ReactElement {
+ return (
+ <Tooltip content={content} placement="above" focusTrigger="always">
+ {children}
+ </Tooltip>
+ );
+}
diff --git a/packages/core/src/ProgressBar/index.ts b/packages/core/src/ProgressBar/index.ts
index 70e6f42ba9..dd818f15bf 100644
--- a/packages/core/src/ProgressBar/index.ts
+++ b/packages/core/src/ProgressBar/index.ts
@@ -28,4 +28,8 @@ export interface ProgressBarVariantMap {
}
export {ProgressBar} from './ProgressBar';
-export type {ProgressBarProps, ProgressBarVariant} from './ProgressBar';
+export type {
+ ProgressBarProps,
+ ProgressBarMark,
+ ProgressBarVariant,
+} from './ProgressBar';