ui/progress.tsx

GitHub
'use client';

import * as React from 'react';
import {Progress as ProgressPrimitive} from '@base-ui/react/progress';
import {Meter as MeterPrimitive} from '@base-ui/react/meter';
import {cn, mergeClass} from '../lib/utils';
import type {Kind} from '../lib/kind';
import {Icon, Renew, Checkmark, Close} from '../icon';
import {Button} from './button';
import {InkSlot, StatusArc, statusLabels} from './status';

type Mode = 'progress' | 'meter';
type Shape = 'bar' | 'ring';
type Size = 'sm' | 'default' | 'lg';

type ProgressContextValue = {mode: Mode};
const ProgressContext = React.createContext<ProgressContextValue>({mode: 'progress'});

function meterStatus(fraction: number, warnAt: number | null, failAt: number | null) {
  if (failAt !== null && fraction >= failAt) return 'fail' as const;
  if (warnAt !== null && fraction >= warnAt) return 'warn' as const;
  return undefined;
}

type ProgressProps = Omit<ProgressPrimitive.Root.Props, 'value'> & {
  value?: number | null;
  mode?: Mode;
  shape?: Shape;
  size?: Size;
  kind?: Kind;
  status?: 'warn' | 'fail';
  warnAt?: number | null;
  failAt?: number | null;
};

function Progress({className, children, value = null, min = 0, max = 100, mode = 'progress', shape = 'bar', size = 'default', kind, status: statusProp, warnAt = 0.8, failAt = 1, ...props}: ProgressProps) {
  const fraction = value === null ? null : Math.min(Math.max((value - min) / (max - min || 1), 0), 1);
  const meter = mode === 'meter';
  const status = statusProp ?? (meter && fraction !== null ? meterStatus(fraction, warnAt, failAt) : undefined);
  const shared = {
    'data-slot': 'progress',
    'data-mode': mode,
    'data-shape': shape,
    'data-size': size,
    'data-kind': status ? undefined : kind,
    'data-status': status,
    locale: 'en-US' as const,
    className: mergeClass(['group/progress flex w-full min-w-0 flex-wrap items-baseline gap-x-3 gap-y-2', shape === 'ring' && 'w-auto flex-nowrap items-center gap-2'], className),
  };
  const visual = shape === 'ring'
    ? <ProgressRingVisual fraction={fraction} size={size}/>
    : <ProgressBar fraction={fraction} meter={meter} warnAt={meter ? warnAt : null}/>;

  if (meter) {
    return <ProgressContext.Provider value={{mode}}>
      <MeterPrimitive.Root value={value ?? 0} min={min} max={max} {...shared} className={shared.className as MeterPrimitive.Root.Props['className']} {...(props as Omit<MeterPrimitive.Root.Props, 'value'>)}>
        {children}{visual}
      </MeterPrimitive.Root>
    </ProgressContext.Provider>;
  }
  return <ProgressContext.Provider value={{mode}}>
    <ProgressPrimitive.Root value={value} min={min} max={max} {...shared} {...props}>
      {children}{visual}
    </ProgressPrimitive.Root>
  </ProgressContext.Provider>;
}

const trackFill = 'bg-cell-quiet forced-colors:bg-[Canvas] forced-colors:outline forced-colors:outline-1';
const trackHeight = 'h-1';

function Notch({at}: {at: number | null}) {
  if (at === null || at <= 0 || at >= 1) return null;
  return <span
    aria-hidden
    data-slot="progress-notch"
    className="absolute inset-y-0 w-px bg-text-3"
    style={{insetInlineStart: `${at * 100}%`}}
  />;
}

function ProgressBar({fraction, meter, warnAt}: {fraction: number | null; meter: boolean; warnAt: number | null}) {
  const Track = meter ? MeterPrimitive.Track : ProgressPrimitive.Track;
  const Indicator = meter ? MeterPrimitive.Indicator : ProgressPrimitive.Indicator;
  return <Track data-slot="progress-track" className={cn('relative block w-full overflow-hidden', trackHeight, trackFill)}>
    {fraction === null
      ? <span
          data-slot="progress-indicator"
          data-indeterminate
          className="absolute inset-y-0 start-0 w-1/3 bg-accent-line forced-colors:bg-[CanvasText] motion-safe:animate-slide"
        />
      : <Indicator data-slot="progress-indicator" className={cn('block h-full bg-accent-line forced-colors:bg-[CanvasText]', !meter && 'transition-[width] duration-(--dur-base) ease-(--ease-step) motion-reduce:transition-none')}/>}
    <Notch at={warnAt}/>
  </Track>;
}

const ringPx: Record<Size, number> = {sm: 12, default: 16, lg: 24};

function RingSvg({fraction, px}: {fraction: number | null; px: number}) {
  const stroke = px >= 24 ? 2.5 : px >= 16 ? 2 : 1.5;
  const r = (px - stroke) / 2;
  const c = 2 * Math.PI * r;
  const indeterminate = fraction === null;
  return <svg data-slot="progress-ring" viewBox={`0 0 ${px} ${px}`} width={px} height={px} aria-hidden className="shrink-0 -rotate-90" style={{width: px, height: px}}>
    <circle cx={px / 2} cy={px / 2} r={r} fill="none" strokeWidth={stroke} className="stroke-cell-quiet"/>
    {indeterminate
      ? <>
          <circle cx={px / 2} cy={px / 2} r={r} fill="none" strokeWidth={stroke} strokeDasharray={`${c / 6} ${c / 3}`} className="origin-center stroke-accent-mark animate-spin motion-reduce:hidden"/>
          <circle cx={px / 2} cy={px / 2} r={r} fill="none" strokeWidth={stroke} strokeDasharray={`${c / 16} ${c / 16}`} className="hidden stroke-accent-mark motion-reduce:block"/>
        </>
      : <circle cx={px / 2} cy={px / 2} r={r} fill="none" strokeWidth={stroke} strokeDasharray={`${c * fraction} ${c}`} className="stroke-accent-mark transition-[stroke-dasharray] duration-(--dur-base) ease-(--ease-step) motion-reduce:transition-none"/>}
  </svg>;
}

function ProgressRingVisual({fraction, size}: {fraction: number | null; size: Size}) {
  return <ProgressPrimitive.Track data-slot="progress-track" className="flex shrink-0 items-center">
    <RingSvg fraction={fraction} px={ringPx[size]}/>
  </ProgressPrimitive.Track>;
}

type ProgressRingProps = Omit<React.ComponentProps<'span'>, 'children'> & {
  size?: 12 | 16 | 20 | 24;
  label?: string | null;
  fraction?: number | null;
};

function ProgressRing({size = 16, label = 'Loading', fraction = null, className, ...props}: ProgressRingProps) {
  const a11y = label === null
    ? {'aria-hidden': true as const}
    : {role: 'progressbar' as const, 'aria-label': label, 'aria-valuenow': fraction === null ? undefined : Math.round(fraction * 100), 'aria-valuemin': 0, 'aria-valuemax': 100};
  return <span data-slot="progress-ring-inline" className={cn('inline-flex shrink-0 text-current [--accent-mark:currentColor]', className)} {...a11y} {...props}>
    <RingSvg fraction={fraction} px={size}/>
  </span>;
}

function ProgressLabel({className, ...props}: ProgressPrimitive.Label.Props) {
  const {mode} = React.useContext(ProgressContext);
  const Label = mode === 'meter' ? MeterPrimitive.Label : ProgressPrimitive.Label;
  return <Label data-slot="progress-label" className={mergeClass('min-w-0 truncate type-label text-text-1', className) as MeterPrimitive.Label.Props['className']} {...(props as MeterPrimitive.Label.Props)}/>;
}

type ProgressValueProps = Omit<MeterPrimitive.Value.Props, 'children'> & {
  children?: ((formattedValue: string, value: number) => React.ReactNode) | null;
};

function ProgressValue({className, children, ...props}: ProgressValueProps) {
  const {mode} = React.useContext(ProgressContext);
  const cls = cn('ms-auto type-label-sm text-text-2', className as string);
  if (mode === 'meter') return <MeterPrimitive.Value data-slot="progress-value" className={cls} {...props}>{children}</MeterPrimitive.Value>;
  return <ProgressPrimitive.Value data-slot="progress-value" className={cls} {...(props as ProgressPrimitive.Value.Props)}>
    {children ? (formatted: string | null, value: number | null) => children(formatted ?? "", value ?? 0) : undefined}
  </ProgressPrimitive.Value>;
}

type StepState = 'done' | 'current' | 'upcoming' | 'error' | 'pending' | 'waiting';

type StepsContextValue = {
  value: number;
  orientation: 'horizontal' | 'vertical';
  onValueChange?: (step: number) => void;
  linear: boolean;
};

const StepsContext = React.createContext<StepsContextValue | null>(null);
const StepContext = React.createContext<{step: number; state: StepState; disabled: boolean} | null>(null);

function useSteps() {
  const ctx = React.useContext(StepsContext);
  if (!ctx) throw new Error('ProgressStep parts must be inside <ProgressSteps>.');
  return ctx;
}
function useStep() {
  const ctx = React.useContext(StepContext);
  if (!ctx) throw new Error('Step parts must be inside <ProgressStep>.');
  return ctx;
}

type ProgressStepsProps = Omit<React.ComponentProps<'ol'>, 'onChange'> & {
  value: number;
  onValueChange?: (step: number) => void;
  orientation?: 'horizontal' | 'vertical';
  linear?: boolean;
};

function ProgressSteps({value, onValueChange, orientation = 'horizontal', linear = true, className, ...props}: ProgressStepsProps) {
  const ctx = React.useMemo(() => ({value, onValueChange, orientation, linear}), [value, onValueChange, orientation, linear]);
  return <StepsContext.Provider value={ctx}>
    <ol
      data-slot="progress-steps"
      data-orientation={orientation}
      className={cn('group/steps flex w-full min-w-0', orientation === 'horizontal' ? 'flex-row items-start gap-2' : 'flex-col', className)}
      {...props}
    />
  </StepsContext.Provider>;
}

type ProgressStepProps = React.ComponentProps<'li'> & {
  step: number;
  state?: StepState;
  disabled?: boolean;
};

function ProgressStep({step, state: stateProp, disabled = false, className, ...props}: ProgressStepProps) {
  const {value, orientation} = useSteps();
  const state: StepState = stateProp ?? (step < value ? 'done' : step === value ? 'current' : 'upcoming');
  const ctx = React.useMemo(() => ({step, state, disabled}), [step, state, disabled]);
  return <StepContext.Provider value={ctx}>
    <li
      data-slot="progress-step"
      data-state={state}
      aria-current={step === value ? 'step' : undefined}
      className={cn('group/step relative flex min-w-0', orientation === 'horizontal' ? 'flex-1 flex-col' : 'flex-col pb-6 last:pb-0', className)}
      {...props}
    />
  </StepContext.Provider>;
}

function ProgressStepTrigger({className, children, ...props}: React.ComponentProps<'button'>) {
  const {onValueChange, value, linear, orientation} = useSteps();
  const {step, disabled} = useStep();
  const base = cn('-m-1 flex min-w-0 p-1 text-start', orientation === 'horizontal' ? 'flex-col items-start gap-2 pe-5' : 'items-start gap-3', className);
  if (!onValueChange) return <div data-slot="progress-step-trigger" className={base}>{children}</div>;
  const blocked = disabled || (linear && step > value);
  return <button
    type="button"
    data-slot="progress-step-trigger"
    disabled={blocked}
    onClick={() => onValueChange(step)}
    className={cn(base, 'rounded-soft decoration-1 underline-offset-4 enabled:hover:[&_[data-slot=progress-step-title]]:underline disabled:cursor-not-allowed')}
    {...props}
  >{children}</button>;
}

const stepWord: Record<StepState, string> = {done: ', done', error: ', failed', pending: ', in progress', current: ', current', upcoming: '', waiting: ', waiting on you'};

function ProgressStepIndicator({className, children, ...props}: React.ComponentProps<'span'>) {
  const {step, state} = useStep();
  return <span
    data-slot="progress-step-indicator"
    data-state={state}
    data-status={state === 'error' ? 'fail' : undefined}
    className={cn(
      'frame [--frame-radius:var(--radius-soft)] grid size-6 shrink-0 place-items-center bg-page type-label-sm text-text-1 data',
      'data-[state=done]:text-text-2 data-[state=done]:[--frame-color:var(--line-control)] data-[state=current]:[--frame-color:var(--ink)] data-[state=pending]:[--frame-color:var(--ink)] data-[state=waiting]:[--frame-color:var(--ink)]',
      'data-[state=upcoming]:text-text-3 data-[state=upcoming]:[--frame-color:var(--line-control)]',
      'data-[state=error]:bg-accent-wash data-[state=error]:[--frame-color:var(--accent-line)]',
      className,
    )}
    {...props}
  >
    {children ?? (state === 'done' ? <Icon icon={Checkmark} size={12}/>
      : state === 'error' ? <Icon icon={Close} size={12}/>
      : state === 'pending' ? <ProgressRing size={12} label={null}/>
      : String(step))}
    <span className="sr-only">{stepWord[state]}</span>
  </span>;
}

function ProgressStepTitle({className, children, ...props}: React.ComponentProps<'span'>) {
  const {state} = useStep();
  return <span data-slot="progress-step-title" className={cn('flex flex-wrap items-center gap-x-2 gap-y-1 type-label text-text-1 group-data-[state=upcoming]/step:text-text-2', className)} {...props}>
    {children}{state === 'waiting' && <InkSlot size="sm">{statusLabels.waiting}</InkSlot>}
  </span>;
}

function ProgressStepDescription({className, ...props}: React.ComponentProps<'span'>) {
  return <span data-slot="progress-step-description" className={cn('mt-1 block type-body-sm text-text-3', className)} {...props}/>;
}

function ProgressStepText({className, ...props}: React.ComponentProps<'span'>) {
  return <span data-slot="progress-step-text" className={cn('flex min-w-0 flex-col group-data-[orientation=vertical]/steps:pt-0.5', className)} {...props}/>;
}

function ProgressStepSeparator({className, ...props}: React.ComponentProps<'span'>) {
  const {orientation} = useSteps();
  const {state} = useStep();
  return <span
    aria-hidden
    data-slot="progress-step-separator"
    data-state={state}
    className={cn(
      'block bg-line-row group-last/step:hidden data-[state=done]:bg-ink',
      orientation === 'horizontal'
        ? 'absolute start-8 end-2 top-3 h-px'
        : 'absolute start-3 top-8 bottom-2 w-px -translate-x-1/2 rtl:translate-x-1/2',
      className,
    )}
    {...props}
  />;
}

type ProgressItemStatus = 'queued' | 'running' | 'done' | 'warn' | 'failed' | 'canceled';

type ProgressItemProps = Omit<React.ComponentProps<'div'>, 'title'> & {
  title: React.ReactNode;
  detail?: React.ReactNode;
  status: ProgressItemStatus;
  value?: number | null;
  max?: number;
  amount?: React.ReactNode;
  kind?: Kind;
  onCancel?: () => void;
  onRetry?: () => void;
  label?: string;
};

const itemWord: Record<ProgressItemStatus, string> = {queued: 'Queued', running: 'Running', done: 'Done', warn: 'Partly done', failed: 'Failed', canceled: 'Canceled'};

function ItemWord({status}: {status: ProgressItemStatus}) {
  return <span
    data-slot="progress-item-status"
    data-status={status === 'failed' ? 'fail' : status === 'warn' ? 'warn' : undefined}
    className={cn('inline-flex shrink-0 items-center gap-1.5 type-label-sm', status === 'failed' ? 'text-fail-text' : status === 'warn' ? 'text-warn-text' : status === 'running' ? 'text-text-1' : 'text-text-3')}
  >
    {status === 'running' && <StatusArc/>}
    {itemWord[status]}
  </span>;
}

function ProgressItem({className, title, detail, status, value = 0, max = 100, amount, kind, onCancel, onRetry, label, ...props}: ProgressItemProps) {
  const active = status === 'running' || status === 'queued';
  const shownAmount = amount ?? (status === 'running' && value !== null ? `${Math.round((value / max) * 100)}%` : null);
  const name = label ?? (typeof title === 'string' ? title : 'task');
  return <div
    data-slot="progress-item"
    data-state={status}
    className={cn('grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-3 gap-y-1 py-2', className)}
    {...props}
  >
    <div className="flex min-w-0 items-baseline gap-2">
      <span className={cn('truncate type-label', status === 'canceled' && 'text-text-3')}>{title}</span>
      <ItemWord status={status}/>
    </div>
    <div className="flex items-center gap-1">
      {shownAmount !== null && <span className="type-label-sm text-text-2 data">{shownAmount}</span>}
      {active && onCancel && <Button size="icon-sm" variant="ghost" aria-label={`Cancel ${name}`} onClick={onCancel}><Icon icon={Close} size={16}/></Button>}
      {status === 'failed' && onRetry && <Button size="icon-sm" variant="ghost" aria-label={`Retry ${name}`} onClick={onRetry}><Icon icon={Renew} size={16}/></Button>}
    </div>
    {(detail || active) && <div className="col-span-2 flex min-w-0 flex-col gap-1.5">
      {active && <Progress aria-label={`${name} progress`} size="sm" kind={kind} value={status === 'queued' ? 0 : value} max={max}/>}
      {detail && <span className={cn('truncate type-body-sm', status === 'failed' ? 'text-fail-text' : 'text-text-3')}>{detail}</span>}
    </div>}
  </div>;
}

function ProgressList({className, ...props}: React.ComponentProps<'div'>) {
  return <div data-slot="progress-list" className={cn('flex flex-col [&>[data-slot=progress-item]]:rule-row', className)} {...props}/>;
}

export {
  Progress, ProgressLabel, ProgressValue, ProgressRing,
  ProgressSteps, ProgressStep, ProgressStepTrigger, ProgressStepIndicator, ProgressStepTitle, ProgressStepDescription, ProgressStepText, ProgressStepSeparator,
  ProgressItem, ProgressList, meterStatus,
  type ProgressProps, type ProgressRingProps, type ProgressStepsProps, type ProgressStepProps, type StepState, type ProgressItemProps, type ProgressItemStatus,
};