Skip to content

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

TypeScript
29.5 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file ProgressBar.tsx
 * @input Uses React, useId, stylex, tokens, ProgressBarTouch and resolveMotion
 * @output Exports ProgressBar component, ProgressBarProps, ProgressBarVariant types
 * @position Core implementation; consumed by index.ts
 *
 * 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 {lazy, Suspense, useId, type CSSProperties} from 'react';
import * as stylex from '@stylexjs/stylex';

import {
  colorVars,
  spacingVars,
  radiusVars,
  fontWeightVars,
  durationVars,
  easeVars,
  typeScaleVars,
} from '../theme/tokens.stylex';
import {mergeProps} from '../utils';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {VisuallyHidden} from '../VisuallyHidden';
import type {ProgressBarVariantMap} from './index';
import {useProgressBarTouch} from './ProgressBarTouch';
import {formatMotionRoleValue} from '../motion/roles';
import {resolveMotion} from '../motion/resolveMotion';
import {progressBar} from '../motion/uikit/progressBar';
import {timing} from '../motion/uikit/timing';

// 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>;
  /**
   * Current value of the progress bar.
   * Ignored when `isIndeterminate` is true.
   */
  value?: number;
  /**
   * Maximum value of the progress bar.
   * @default 100
   */
  max?: number;
  /**
   * Accessible label for the progress bar. Required for a11y.
   * Shown visually above the bar unless `isLabelHidden` is true.
   */
  label: string;
  /**
   * When true, the label is visually hidden but remains accessible to screen readers.
   * @default false
   */
  isLabelHidden?: boolean;
  /**
   * When true, displays the formatted value (e.g. "75%") next to the label.
   * Ignored when `isIndeterminate` is true.
   * @default false
   */
  hasValueLabel?: boolean;
  /**
   * Custom formatter for the value label.
   * @default (value, max) => `${Math.round((value / max) * 100)}%`
   */
  formatValueLabel?: (value: number, max: number) => string;
  /**
   * Visual style variant mapped to semantic color tokens.
   * @default 'accent'
   */
  variant?: ProgressBarVariant;
  /**
   * 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.
   * Under reduced motion it pulses in place instead of sliding.
   * @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, and take their color from what they sit on: a mark
   * inside the filled area uses the fill variant's on-color (on-accent,
   * on-warning, on-error, …), while a mark still out on the bare track uses
   * `--color-text-primary` (`--color-text-secondary` on a disabled bar, which
   * dims everything it draws). 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.
   * @default false
   */
  isDisabled?: boolean;
  /**
   * Test ID for testing utilities.
   */
  'data-testid'?: string;
}

// =============================================================================
// Indeterminate animation
// =============================================================================

const indeterminateSlide = stylex.keyframes({
  '0%': {
    transform: 'translateX(-100%)',
  },
  '100%': {
    transform: 'translateX(250%)',
  },
});

// RTL: mirror the slide so the indeterminate bar travels along the reading
// flow (inline-start → inline-end, i.e. right → left) instead of always
// physically left → right. The magnitudes mirror the LTR keyframe.
const indeterminateSlideRtl = stylex.keyframes({
  '0%': {
    transform: 'translateX(100%)',
  },
  '100%': {
    transform: 'translateX(-250%)',
  },
});

// Under reduced motion the indeterminate fill stops travelling and pulses in
// place. It goes from full opacity down to the pulse's floor
// (`--_progress-bar-pulse-floor`, the progress table's) and back. The
// animation alternates direction each pass.
const indeterminatePulse = stylex.keyframes({
  from: {
    opacity: 1,
  },
  to: {
    opacity: 'var(--_progress-bar-pulse-floor)',
  },
});

// =============================================================================
// Styles
// =============================================================================

const styles = stylex.create({
  container: {
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-1'],
    width: '100%',
    minWidth: '48px',
  },
  header: {
    display: 'flex',
    justifyContent: 'space-between',
    alignItems: 'baseline',
  },
  label: {
    fontSize: typeScaleVars['--text-body-size'],
    lineHeight: typeScaleVars['--text-body-leading'],
    fontWeight: fontWeightVars['--font-weight-medium'],
    color: colorVars['--color-text-primary'],
  },
  labelDisabled: {
    color: colorVars['--color-text-disabled'],
  },
  valueLabel: {
    fontSize: typeScaleVars['--text-body-size'],
    lineHeight: typeScaleVars['--text-body-leading'],
    fontWeight: fontWeightVars['--font-weight-normal'],
    color: colorVars['--color-text-secondary'],
  },
  valueLabelDisabled: {
    color: colorVars['--color-text-disabled'],
  },
  visuallyHidden: {
    position: 'absolute',
    width: '1px',
    height: '1px',
    padding: 0,
    margin: '-1px',
    overflow: 'hidden',
    clip: 'rect(0, 0, 0, 0)',
    whiteSpace: 'nowrap',
    borderWidth: 0,
  },
  // The in-flow track determines this containing block's actual height.
  // Marks share its geometry without depending on the label row's height or
  // entering the progressbar's presentational subtree. Keep it unclipped so
  // themed tall marks can overhang the track symmetrically.
  trackContainer: {
    position: 'relative',
    width: '100%',
  },
  // The semantic rail holds only the fill and clips it to the rounded rail:
  // the determinate fill slides in from the inline-start side and the
  // indeterminate one overshoots both ends. Marks live outside the track (in
  // trackContainer), so the clip never cuts a themed tall mark.
  track: {
    width: '100%',
    height: '8px',
    backgroundColor: colorVars['--color-background-muted'],
    borderRadius: radiusVars['--radius-full'],
    overflow: 'hidden',
  },
  // The determinate fill spans the whole track and slides along it with a
  // transform, so a value change animates on the compositor and keeps moving
  // while a script runs; animating `width` would lay out and repaint on the
  // main thread every frame and stall with it. `--_progress-bar-fill` is the
  // filled share of the track (set inline); the fill's leading edge sits
  // exactly there, mirrored in RTL. The mirror follows the bar's own
  // direction (`:dir(rtl)`, the nearest `dir`), not any RTL ancestor, so a bar
  // in an LTR region of an RTL page fills from the left like its label and
  // marks. The layer is declared up front so Safari has the whole bar painted
  // before it first moves.
  //
  // Under forced colors the fill is sized to the value instead (its `width`,
  // no transform), as before: the track's clip would cut the CanvasText
  // outline's start cap off a slid fill, and that outline is what keeps the
  // fill's shape visible there (architecture:theme-tokens INV11).
  //
  // Under a finger (TOUCH_QUERY, on every touch device), the fill moves as
  // UIProgressView's setProgress(_:animated: true) does. It moves linearly
  // from wherever it is drawn. Its duration is the `progress.fillTrackMs` role
  // times the share of the track the value moved (`--_progress-bar-move`).
  // Its curve is the `progress.curves.fill` role (`--_progress-bar-curve`).
  // The touch layer (ProgressBarTouch) writes both, and this rule scales the
  // duration by the theme's tempo. Above zero, the fill never draws shorter
  // than the touch minimum (`--_progress-bar-min`, 16px on the 8px track). At
  // zero it paints nothing (`fillEmpty`). Under reduced motion it lands at
  // once, as everywhere (below). A mouse or trackpad keeps the theme's timing.
  fill: {
    width: {
      default: '100%',
      '@media (forced-colors: active)': {
        default: 'var(--_progress-bar-fill, 0%)',
        '@media (pointer: coarse)':
          'calc(max(var(--_progress-bar-fill, 0%), var(--_progress-bar-min, 0px)) + var(--_progress-bar-flip, 0) * 0.01px)',
      },
    },
    height: '100%',
    // Forced colors replace status fills with Canvas; this boundary keeps the
    // fill's shape visible (architecture:theme-tokens INV11).
    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
    outlineColor: {
      default: null,
      '@media (forced-colors: active)': 'CanvasText',
    },
    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
    borderRadius: radiusVars['--radius-full'],
    transform: {
      default: 'translateX(calc(var(--_progress-bar-fill, 0%) - 100%))',
      ':dir(rtl)': {
        default: 'translateX(calc(100% - var(--_progress-bar-fill, 0%)))',
        '@media (forced-colors: active)': 'none',
      },
      '@media (pointer: coarse)': {
        // `--_progress-bar-flip` steps 0, 1, 2, 0… on every change. It moves
        // the fill by that many hundredths of a pixel. So a change back to the
        // value it just left is never the running transition's own start
        // value. CSS shortens a transition that reverses to its start, which
        // would halve a return mid-flight (10 → 90 → 10). It takes three
        // values because two would repeat on that return.
        default:
          'translateX(calc(max(var(--_progress-bar-fill, 0%), var(--_progress-bar-min, 0px)) - 100% + var(--_progress-bar-flip, 0) * 0.01px))',
        ':dir(rtl)':
          'translateX(calc(min(calc(100% - var(--_progress-bar-fill, 0%)), calc(100% - var(--_progress-bar-min, 0px))) - var(--_progress-bar-flip, 0) * 0.01px))',
      },
      // After the touch key, so StyleX negates that key under forced colors.
      '@media (forced-colors: active)': 'none',
    },
    willChange: {
      default: 'transform',
      '@media (forced-colors: active)': 'auto',
    },
    transitionProperty: {
      default: 'transform',
      '@media (forced-colors: active)': 'width',
    },
    // Under reduced motion a new value lands at once, with a mouse as with a
    // finger: the fill never travels. The keys are the shared reduced-motion
    // queries, as the other transitions spell them. The coarse key comes after
    // the touch key, so it wins there.
    transitionDuration: {
      default: durationVars['--duration-medium'],
      // The touch layer's move (the `progress.fillTrackMs` role times the
      // share moved), scaled by the theme's tempo.
      '@media (pointer: coarse)': {
        default:
          'calc(var(--_progress-bar-move, 0ms) * var(--_astryx-motion-tempo, 1))',
        // Under forced colors the fill is sized by `width` instead. Touch
        // motion never animates a layout property, so with a finger the new
        // size lands at once there.
        '@media (forced-colors: active)': '0s',
      },
      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
        '0s',
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': '0s',
    },
    transitionTimingFunction: {
      default: easeVars['--ease-standard'],
      '@media (pointer: coarse)': 'var(--_progress-bar-curve, linear)',
    },
  },
  fillEmpty: {
    opacity: {
      default: null,
      '@media (pointer: coarse)': 0,
    },
  },
  indeterminateFill: {
    height: '100%',
    // Forced colors replace status fills with Canvas; this boundary keeps the
    // fill's shape visible (architecture:theme-tokens INV11).
    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
    outlineColor: {
      default: null,
      '@media (forced-colors: active)': 'CanvasText',
    },
    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
    // Under reduced motion, on every pointer, the fill spans the whole track
    // as one solid bar, and only its opacity pulses. Each way takes the
    // `progress.reducedMotionPulseMs` role on the `timing.curves.move` curve
    // (`--_progress-bar-pulse`, `--_progress-bar-pulse-curve`, set inline from
    // the progress table). A busy loop: tempo does not scale it.
    width: {
      default: '40%',
      '@media (prefers-reduced-motion: reduce)': '100%',
    },
    borderRadius: radiusVars['--radius-full'],
    animationName: {
      default: indeterminateSlide,
      ':is([dir="rtl"] *)': {
        default: indeterminateSlideRtl,
        '@media (prefers-reduced-motion: reduce)': indeterminatePulse,
      },
      '@media (prefers-reduced-motion: reduce)': indeterminatePulse,
    },
    animationDuration: {
      default: '1.5s',
      '@media (prefers-reduced-motion: reduce)': 'var(--_progress-bar-pulse)',
    },
    animationTimingFunction: {
      default: 'ease-in-out',
      '@media (prefers-reduced-motion: reduce)':
        'var(--_progress-bar-pulse-curve)',
    },
    animationDirection: {
      default: null,
      '@media (prefers-reduced-motion: reduce)': 'alternate',
    },
    animationIterationCount: 'infinite',
  },
  // A mark is a vertical tick centered on the track via their shared positioning container.
  // It stays outside role="progressbar" so it remains independently focusable.
  // The centering translate keeps themed overhang symmetric;
  // insetInlineStart and the mirrored translate preserve RTL.
  //
  // The dimensions read private vars rather than being plain declarations: a
  // theme writes `width`/`height` on the `progressbar-mark` target as usual and
  // the derived-var registry emits them as these vars instead of as competing
  // properties. Nothing else declares them, so the theme value lands whatever
  // the consumer's cascade looks like — a source-build app that compiles StyleX
  // without `useCSSLayers` leaves the atomics unlayered, where they outrank
  // every rule in `@layer astryx-theme` and made sizing the mark impossible
  // without `!important`.
  //
  // The tick's color is not set here: it depends on what the mark sits on, so
  // it comes from `markOnFillStyles[variant]` (mark inside the filled area) or
  // `markOnTrackStyles.track` (mark out on the bare track).
  mark: {
    position: 'absolute',
    top: '50%',
    width: 'var(--_progressbar-mark-width, 2px)',
    height: 'var(--_progressbar-mark-height, 8px)',
    transform: {
      default: 'translate(-50%, -50%)',
      ':is([dir="rtl"] *)': 'translate(50%, -50%)',
    },
  },
});

const variantStyles = stylex.create({
  accent: {
    backgroundColor: colorVars['--color-accent'],
  },
  success: {
    backgroundColor: colorVars['--color-success'],
  },
  warning: {
    backgroundColor: colorVars['--color-warning'],
  },
  error: {
    backgroundColor: colorVars['--color-error'],
  },
  neutral: {
    backgroundColor: colorVars['--color-text-disabled'],
  },
  disabled: {
    backgroundColor: colorVars['--color-text-disabled'],
  },
});

// A mark sitting inside the filled area is drawn *on* the bar, so it takes the
// on-color that pairs with the fill's own variant color — the same pairing
// Badge uses for solid semantic backgrounds.
//
// `neutral` and `disabled` both fill with the muted `--color-text-disabled`
// gray, which carries no semantic weight and has no dedicated on-token, so
// they fall back to a plain foreground. They pick different ones: a `neutral`
// bar is live, so its mark keeps the full-contrast `--color-text-primary` a
// mark uses out on the track; a `disabled` bar is deliberately low-emphasis —
// its own label and value text drop to muted colors — so its mark steps down
// to `--color-text-secondary` rather than becoming the loudest thing on a
// grayed-out component.
const markOnFillStyles = stylex.create({
  accent: {
    backgroundColor: colorVars['--color-on-accent'],
  },
  success: {
    backgroundColor: colorVars['--color-on-success'],
  },
  warning: {
    backgroundColor: colorVars['--color-on-warning'],
  },
  error: {
    backgroundColor: colorVars['--color-on-error'],
  },
  neutral: {
    backgroundColor: colorVars['--color-text-primary'],
  },
  disabled: {
    backgroundColor: colorVars['--color-text-secondary'],
  },
});

// A mark out on the bare track is a foreground tick over the muted track
// background, so it takes `--color-text-primary`.
//
// The obvious candidate was `--color-border-emphasized` — the emphasized
// divider color `Divider`'s `strong` variant and `Slider`'s marks use — but
// divider tokens sit a step or two from the track on the same neutral ramp, so
// a mark drawn in one is at or near invisible: measured against each shipped
// theme's track it lands between 1.00:1 (theme-neutral, both modes, where the
// track is aliased to that very token) and 2.9:1, under the 3:1 WCAG 1.4.11
// non-text floor in 7 of 8 themes. `--color-text-secondary` still misses in
// two. `--color-text-primary` is the one foreground guaranteed to read against
// every surface a theme defines: 5.8:1 to 15.7:1 on the track across all
// themes and both modes.
const markOnTrackStyles = stylex.create({
  track: {
    backgroundColor: colorVars['--color-text-primary'],
  },
  // A disabled bar dims everything it draws, so its track marks step down to
  // the secondary foreground for the same reason the disabled on-fill mark
  // does — matching the muted label and value text.
  trackDisabled: {
    backgroundColor: colorVars['--color-text-secondary'],
  },
});

// The reduced-motion pulse's variables, from the progress table.
type PulseStyle = CSSProperties &
  Record<
    | '--_progress-bar-pulse'
    | '--_progress-bar-pulse-curve'
    | '--_progress-bar-pulse-floor',
    string
  >;

// `CSSProperties` has no index signature for custom properties, so the fill's
// inline style — which publishes the filled share as the private
// `--_progress-bar-fill` — needs this augmentation to typecheck.
type FillStyle = CSSProperties &
  Record<
    | '--_progress-bar-fill'
    | '--_progress-bar-move'
    | '--_progress-bar-curve'
    | '--_progress-bar-flip'
    | '--_progress-bar-min',
    string
  >;

/**
 * The reduced-motion pulse plays the `progress.reducedMotionPulseMs` role on
 * the `timing.curves.move` curve, down to the progress table's floor.
 */
function pulseStyle(element: Element | null): PulseStyle {
  const pulseMs = resolveMotion(element, progressBar, 'reducedMotionPulseMs');
  const curve = resolveMotion(element, timing.curves.move);
  return {
    '--_progress-bar-pulse': `${pulseMs}ms`,
    '--_progress-bar-pulse-curve': formatMotionRoleValue('curve', curve),
    '--_progress-bar-pulse-floor': String(progressBar.reducedMotionPulseFloor),
  };
}

function defaultFormatValueLabel(value: number, max: number): string {
  const pct = max > 0 ? Math.round((value / max) * 100) : 0;
  return `${pct}%`;
}

/**
 * A progress bar for displaying determinate or indeterminate progress.
 *
 * In determinate mode, displays a known value within a range (upload progress,
 * disk usage, etc). In indeterminate mode, shows an animated loading indicator
 * for unknown progress.
 *
 * ProgressBar is intentionally minimal — compose additional labels, status
 * icons, and descriptions alongside the bar using layout components rather
 * 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.
 *
 * @example
 * ```
 * <ProgressBar value={75} label="Upload progress" />
 * <ProgressBar isIndeterminate label="Loading..." />
 * <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
 * `progress-bar-mark` target. The target reflects `data-placement`
 * (`"fill"` when the mark sits inside the filled area, `"track"` when it is
 * still out on the bare track) and `data-variant` (the fill's variant), so a
 * theme can style the two cases separately — e.g. a taller "goal flag" tick
 * that overhangs the bar (centered, so the overhang is symmetric):
 *
 * @example
 * ```
 * defineTheme({
 *   name: 'campaign',
 *   components: {
 *     'progress-bar-mark': {base: {height: '16px', backgroundColor: 'red'}},
 *   },
 * });
 * ```
 */
export function ProgressBar({
  value = 0,
  max = 100,
  label,
  isLabelHidden = false,
  hasValueLabel = false,
  formatValueLabel = defaultFormatValueLabel,
  variant = 'accent',
  isIndeterminate = false,
  isDisabled = false,
  marks,
  xstyle,
  className,
  style,
  'data-testid': dataTestId,
  ref,
  ...rest
}: ProgressBarProps) {
  const labelId = useId();
  // 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 fill width 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) * 100 : 0;
  const valueText = formatValueLabel(clampedValue, safeMax);

  const showValueLabel = hasValueLabel && !isIndeterminate;

  const fillVariant = isDisabled ? 'disabled' : variant;
  // Under a finger the fill moves as UIProgressView's does and draws at least
  // 16px; what that needs from script is the touch layer's (ProgressBarTouch).
  const touch = useProgressBarTouch(
    percentage,
    !isIndeterminate && (marks?.length ?? 0) > 0,
  );
  const fillStyle: FillStyle = {
    '--_progress-bar-fill': `${percentage}%`,
    ...touch.fillVars,
  };

  // 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`.
  //
  // Each mark also records whether it lands on the filled part of the bar
  // (`isOnFill`), which decides its color: a mark inside the fill reads against
  // the variant color, one out on the bare track reads against the track. A
  // mark exactly at the fill's leading edge counts as on the fill — it is the
  // "reached the target" moment — except at zero progress, where there is no
  // fill for it to sit on.
  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,
              isOnFill: percentage > 0 && pct <= touch.drawnPercentage,
            };
          })
      : [];

  return (
    <div
      ref={ref}
      {...mergeProps(
        themeProps('progress-bar', {variant}),
        stylex.props(styles.container, xstyle),
        className,
        style,
      )}
      data-testid={dataTestId}
      {...rest}>
      {/* Label row */}
      {!isLabelHidden || showValueLabel ? (
        <div {...stylex.props(styles.header)}>
          <span
            id={labelId}
            {...stylex.props(
              styles.label,
              isLabelHidden && styles.visuallyHidden,
              isDisabled && styles.labelDisabled,
            )}>
            {label}
          </span>
          {showValueLabel && (
            <span
              {...stylex.props(
                styles.valueLabel,
                isDisabled && styles.valueLabelDisabled,
              )}>
              {valueText}
            </span>
          )}
        </div>
      ) : (
        <VisuallyHidden id={labelId}>{label}</VisuallyHidden>
      )}

      <div {...stylex.props(styles.trackContainer)}>
        <div
          role="progressbar"
          aria-valuenow={isIndeterminate ? undefined : clampedValue}
          aria-valuemin={isIndeterminate ? undefined : 0}
          aria-valuemax={isIndeterminate ? undefined : safeMax}
          aria-labelledby={labelId}
          aria-valuetext={isIndeterminate ? undefined : valueText}
          ref={touch.trackRef}
          {...mergeProps(
            themeProps('progress-bar-track'),
            stylex.props(styles.track),
          )}>
          {isIndeterminate ? (
            <div
              {...mergeProps(
                themeProps('progress-bar-fill', {variant: fillVariant}),
                stylex.props(
                  styles.indeterminateFill,
                  variantStyles[fillVariant],
                ),
              )}
              style={pulseStyle(null)}
            />
          ) : (
            <div
              {...mergeProps(
                themeProps('progress-bar-fill', {variant: fillVariant}),
                stylex.props(
                  styles.fill,
                  percentage === 0 && styles.fillEmpty,
                  variantStyles[fillVariant],
                ),
              )}
              style={fillStyle}
            />
          )}
        </div>
        {/* Marks overlay the fill but live outside the semantic progressbar.
          Their Tooltip descriptions remain independently reachable on focus. */}
        {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 tooltip attaches once ready. The list `key`
          // lives on the mapped <Suspense>, not here.
          //
          // `placement` is reflected as `data-placement` (and a class) so a
          // theme can style the two cases separately on the
          // `progress-bar-mark` target; `variant` mirrors the fill's variant
          // for the same reason.
          const markEl = (
            <span
              role="img"
              aria-label={mark.label}
              tabIndex={0}
              {...mergeProps(
                themeProps('progress-bar-mark', {
                  variant: fillVariant,
                  placement: mark.isOnFill ? 'fill' : 'track',
                }),
                stylex.props(
                  focusOutlineStyles.focusVisible,
                  styles.mark,
                  mark.isOnFill
                    ? markOnFillStyles[fillVariant]
                    : isDisabled
                      ? markOnTrackStyles.trackDisabled
                      : markOnTrackStyles.track,
                ),
              )}
              style={{insetInlineStart: `${mark.pct}%`}}
            />
          );
          return (
            <Suspense key={`${mark.value}:${mark.label}`} fallback={markEl}>
              <LazyProgressBarMarkTooltip content={mark.label}>
                {markEl}
              </LazyProgressBarMarkTooltip>
            </Suspense>
          );
        })}
      </div>
    </div>
  );
}

ProgressBar.displayName = 'ProgressBar';