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.mdnew file mode 100644index 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.+@freddymetadiff --git a/apps/storybook/stories/ProgressBar.stories.tsx b/apps/storybook/stories/ProgressBar.stories.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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 (<divref={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`. */}<divrole="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.tsxnew file mode 100644index 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.tsindex 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';