@delacour/react-native-ui 0.1.0-alpha.4 → 0.1.0

package/src/components/progress/progress.variants.test.ts

@@ -0,0 +1,335 @@
+import { describe, expect, test } from "bun:test";
+import { declarationCount } from "../../styles/theme-tokens.test";
+import { SLIDER_COLORS, SLIDER_OUTPUT_TEXT_SIZE, SLIDER_SIZES } from "../slider/slider.variants";
+import { TEXT_SIZES } from "../text/text.variants";
+import {
+	fillTranslate,
+	formatProgressValue,
+	indeterminateSegment,
+	PROGRESS_COLORS,
+	PROGRESS_DEFAULT_COLOR,
+	PROGRESS_DEFAULT_SIZE,
+	PROGRESS_FILL_DURATION_MS,
+	PROGRESS_INDETERMINATE_DURATION_MS,
+	PROGRESS_INDETERMINATE_SEGMENT,
+	PROGRESS_MAX_VALUE,
+	PROGRESS_MIN_VALUE,
+	PROGRESS_OUTPUT_TEXT_SIZE,
+	PROGRESS_PULSE,
+	PROGRESS_SIZES,
+	progressRatio,
+	progressVariants,
+	resolveProgressAccessibility,
+	resolveProgressAxes,
+} from "./progress.variants";
+
+/** The bare colour a `bg-*` class names — `bg-success` yields `success`. */
+function backgroundToken(value: string): string | undefined {
+	return value.match(/\bbg-([\w-]+)\b/)?.[1];
+}
+
+/** A slot's class string, with `tv`'s empty-slot `undefined` flattened. */
+function cls(value: string | undefined): string {
+	return value ?? "";
+}
+
+/** The `h-*` step a class string sets — `h-1.5` yields 1.5. */
+function heightStep(value: string): number {
+	return Number(value.match(/\bh-(\d+(?:\.\d+)?)\b/)?.[1]);
+}
+
+describe("the theme reader", () => {
+	// Guard: every token assertion below is worthless if the parse found nothing.
+	test("finds both variants of the theme", () => {
+		expect(declarationCount("primary")).toBe(2);
+	});
+});
+
+describe("the axes", () => {
+	// A meter stacked on this bar, and a slider beside it, have to be able to
+	// name the same colour and the same size with the same word.
+	test("share the slider's six colours and three sizes", () => {
+		expect([...PROGRESS_COLORS]).toEqual([...SLIDER_COLORS]);
+		expect([...PROGRESS_SIZES]).toEqual([...SLIDER_SIZES]);
+	});
+
+	test("default to values the axes actually hold", () => {
+		expect(PROGRESS_COLORS).toContain(PROGRESS_DEFAULT_COLOR);
+		expect(PROGRESS_SIZES).toContain(PROGRESS_DEFAULT_SIZE);
+	});
+
+	test("default the range to 0–100", () => {
+		expect(PROGRESS_MIN_VALUE).toBe(0);
+		expect(PROGRESS_MAX_VALUE).toBe(100);
+	});
+});
+
+describe("resolveProgressAxes", () => {
+	test("falls back to the defaults", () => {
+		expect(resolveProgressAxes({})).toEqual({
+			color: PROGRESS_DEFAULT_COLOR,
+			isIndeterminate: false,
+			size: PROGRESS_DEFAULT_SIZE,
+		});
+	});
+
+	test("keeps what the call site named", () => {
+		expect(resolveProgressAxes({ color: "success", isIndeterminate: true, size: "lg" })).toEqual({
+			color: "success",
+			isIndeterminate: true,
+			size: "lg",
+		});
+	});
+
+	// The progress bar is not a form control, so an enclosing Field has nothing
+	// to hand it. The resolver takes no second argument, and this pins that.
+	test("takes the call site alone", () => {
+		expect(resolveProgressAxes.length).toBe(1);
+	});
+});
+
+describe("progressVariants", () => {
+	test("paints the fill differently for every colour", () => {
+		const painted = new Set(PROGRESS_COLORS.map((color) => cls(progressVariants({ color }).fill())));
+		expect(painted.size).toBe(PROGRESS_COLORS.length);
+	});
+
+	test("never paints the track in a colour", () => {
+		const tracks = new Set(PROGRESS_COLORS.map((color) => cls(progressVariants({ color }).track())));
+		expect(tracks.size).toBe(1);
+	});
+
+	test("names only tokens both variants of the theme declare", () => {
+		const tokens = [
+			backgroundToken(cls(progressVariants({}).track())),
+			...PROGRESS_COLORS.map((color) => backgroundToken(cls(progressVariants({ color }).fill()))),
+		];
+		for (const token of tokens) {
+			expect(token).toBeDefined();
+			expect(declarationCount(token as string)).toBe(2);
+		}
+	});
+
+	test("never paints the fill in the track's own colour", () => {
+		const track = backgroundToken(cls(progressVariants({}).track()));
+		for (const color of PROGRESS_COLORS) {
+			expect(backgroundToken(cls(progressVariants({ color }).fill()))).not.toBe(track);
+		}
+	});
+
+	test("thickens the track as the size steps up", () => {
+		const heights = PROGRESS_SIZES.map((size) => heightStep(cls(progressVariants({ size }).track())));
+		for (const height of heights) expect(Number.isFinite(height)).toBe(true);
+		expect([...heights].sort((a, b) => a - b)).toEqual(heights);
+		expect(new Set(heights).size).toBe(heights.length);
+	});
+
+	// The fill slides under the track's rounded clip; a track that stops clipping
+	// shows the fill parked to its left at every value below the maximum.
+	test("clips the fill to the track", () => {
+		expect(cls(progressVariants({}).track())).toMatch(/\boverflow-hidden\b/);
+		expect(cls(progressVariants({}).fill())).toMatch(/\babsolute\b/);
+	});
+
+	// No slot worn by a View carries type — the readout names a Text step instead.
+	test("puts no text styling on a View slot", () => {
+		for (const size of PROGRESS_SIZES) {
+			const slots = progressVariants({ size });
+			for (const slot of [slots.root(), slots.track(), slots.fill()]) {
+				expect(cls(slot)).not.toMatch(/\b(text|font)-/);
+			}
+		}
+	});
+});
+
+describe("PROGRESS_OUTPUT_TEXT_SIZE", () => {
+	test("names a size Text actually has, for every progress size", () => {
+		for (const size of PROGRESS_SIZES) {
+			expect(TEXT_SIZES).toContain(PROGRESS_OUTPUT_TEXT_SIZE[size]);
+		}
+	});
+
+	// A progress bar under a slider in one form reads at the same type step.
+	test("matches the slider's readout", () => {
+		expect(PROGRESS_OUTPUT_TEXT_SIZE).toEqual(SLIDER_OUTPUT_TEXT_SIZE);
+	});
+});
+
+describe("the motion constants", () => {
+	test("are positive and ordered the way the eye reads them", () => {
+		expect(PROGRESS_FILL_DURATION_MS).toBeGreaterThan(0);
+		expect(PROGRESS_INDETERMINATE_DURATION_MS).toBeGreaterThan(PROGRESS_FILL_DURATION_MS);
+	});
+
+	test("keep the indeterminate segment a strict fraction of the track", () => {
+		expect(PROGRESS_INDETERMINATE_SEGMENT).toBeGreaterThan(0);
+		expect(PROGRESS_INDETERMINATE_SEGMENT).toBeLessThan(1);
+	});
+
+	// A pulse that dims to nothing reads as the bar disappearing, not breathing.
+	test("never pulses to fully transparent", () => {
+		expect(PROGRESS_PULSE.from).toBeGreaterThan(0);
+		expect(PROGRESS_PULSE.to).toBe(1);
+		expect(PROGRESS_PULSE.from).toBeLessThan(PROGRESS_PULSE.to);
+		expect(PROGRESS_PULSE.durationMs).toBeGreaterThan(0);
+	});
+});
+
+describe("progressRatio", () => {
+	test("maps the range onto 0–1", () => {
+		expect(progressRatio(0, 0, 100)).toBe(0);
+		expect(progressRatio(25, 0, 100)).toBe(0.25);
+		expect(progressRatio(100, 0, 100)).toBe(1);
+		expect(progressRatio(18, 0, 24)).toBe(0.75);
+		expect(progressRatio(15, 10, 20)).toBe(0.5);
+	});
+
+	test("clamps rather than extrapolating", () => {
+		expect(progressRatio(-5, 0, 100)).toBe(0);
+		expect(progressRatio(150, 0, 100)).toBe(1);
+	});
+
+	// NaN in a shared value freezes the fill for good — no later frame recovers.
+	test("returns 0 for a degenerate range or a value that is not a number", () => {
+		expect(progressRatio(5, 10, 10)).toBe(0);
+		expect(progressRatio(5, 20, 10)).toBe(0);
+		expect(progressRatio(Number.NaN, 0, 100)).toBe(0);
+		expect(progressRatio(Number.POSITIVE_INFINITY, 0, 100)).toBe(0);
+	});
+});
+
+describe("fillTranslate", () => {
+	test("parks the full-length fill left of the track by what is still to go", () => {
+		expect(fillTranslate({ ratio: 0, trackSize: 200 })).toBe(-200);
+		expect(fillTranslate({ ratio: 0.25, trackSize: 200 })).toBe(-150);
+		expect(fillTranslate({ ratio: 1, trackSize: 200 })).toBe(0);
+	});
+
+	test("clamps a ratio outside 0–1", () => {
+		expect(fillTranslate({ ratio: -1, trackSize: 200 })).toBe(-200);
+		expect(fillTranslate({ ratio: 2, trackSize: 200 })).toBe(0);
+	});
+
+	// An unmeasured track is 0 wide; the bar is hidden until it is measured.
+	test("is 0 for an unmeasured track", () => {
+		expect(fillTranslate({ ratio: 0.5, trackSize: 0 })).toBe(0);
+	});
+});
+
+describe("indeterminateSegment", () => {
+	test("sizes the segment as a fraction of the track", () => {
+		expect(indeterminateSegment({ phase: 0, segment: 0.4, trackSize: 200 }).width).toBe(80);
+	});
+
+	// Both ends of the loop are off-track, so the seam where it repeats is never
+	// on screen.
+	test("starts wholly left of the track and ends wholly right of it", () => {
+		const start = indeterminateSegment({ phase: 0, segment: 0.4, trackSize: 200 });
+		const end = indeterminateSegment({ phase: 1, segment: 0.4, trackSize: 200 });
+		expect(start.translate + start.width).toBe(0);
+		expect(end.translate).toBe(200);
+	});
+
+	test("moves monotonically", () => {
+		let last = Number.NEGATIVE_INFINITY;
+		for (let phase = 0; phase <= 1; phase += 0.1) {
+			const { translate } = indeterminateSegment({ phase, segment: 0.4, trackSize: 200 });
+			expect(translate).toBeGreaterThan(last);
+			last = translate;
+		}
+	});
+
+	test("draws nothing on an unmeasured track", () => {
+		expect(indeterminateSegment({ phase: 0.5, segment: 0.4, trackSize: 0 })).toEqual({ translate: 0, width: 0 });
+	});
+});
+
+describe("formatProgressValue", () => {
+	test("reads as a whole percentage of the range by default", () => {
+		expect(formatProgressValue({ maxValue: 100, minValue: 0, value: 72 })).toBe("72%");
+		expect(formatProgressValue({ maxValue: 24, minValue: 0, value: 18 })).toBe("75%");
+		expect(formatProgressValue({ maxValue: 100, minValue: 0, value: 33.4 })).toBe("33%");
+	});
+
+	test("clamps the percentage the way the fill clamps", () => {
+		expect(formatProgressValue({ maxValue: 100, minValue: 0, value: 140 })).toBe("100%");
+	});
+
+	test("formats the value itself when given a non-percent style", () => {
+		const formatted = formatProgressValue({
+			formatOptions: { currency: "NZD", maximumFractionDigits: 0, style: "currency" },
+			maxValue: 2000,
+			minValue: 0,
+			value: 1250,
+		});
+		expect(formatted).toMatch(/1,250/);
+		expect(formatted).not.toMatch(/%/);
+	});
+
+	// `style: "percent"` would print 7200% if it formatted the value, so a percent
+	// style still formats the ratio — with the caller's other options applied.
+	test("keeps formatting the ratio under a percent style", () => {
+		expect(
+			formatProgressValue({
+				formatOptions: { maximumFractionDigits: 1, style: "percent" },
+				maxValue: 1000,
+				minValue: 0,
+				value: 125,
+			})
+		).toBe("12.5%");
+	});
+});
+
+describe("resolveProgressAccessibility", () => {
+	test("reports the range and the value for a determinate bar", () => {
+		expect(resolveProgressAccessibility({ isIndeterminate: false, maxValue: 100, minValue: 0, value: 72 })).toEqual({
+			busy: false,
+			value: { max: 100, min: 0, now: 72, text: "72%" },
+		});
+	});
+
+	// "18 of 24" says more than "75%": the count is what the screen is about.
+	test("reads a count as value of maximum when the range is not 0–100", () => {
+		expect(
+			resolveProgressAccessibility({ isIndeterminate: false, maxValue: 24, minValue: 0, value: 18 }).value
+		).toEqual({ max: 24, min: 0, now: 18, text: "18 of 24" });
+	});
+
+	test("speaks a formatted value when the readout formats one", () => {
+		const { value } = resolveProgressAccessibility({
+			formatOptions: { currency: "NZD", maximumFractionDigits: 0, style: "currency" },
+			isIndeterminate: false,
+			maxValue: 2000,
+			minValue: 0,
+			value: 1250,
+		});
+		expect(value?.text).toMatch(/1,250 of .*2,000/);
+	});
+
+	test("prefers the caller's own words", () => {
+		expect(
+			resolveProgressAccessibility({
+				isIndeterminate: false,
+				maxValue: 10,
+				minValue: 0,
+				value: 3,
+				valueLabel: "Step 3 of 10",
+			}).value?.text
+		).toBe("Step 3 of 10");
+	});
+
+	test("clamps the reported value into the range", () => {
+		expect(
+			resolveProgressAccessibility({ isIndeterminate: false, maxValue: 100, minValue: 0, value: 130 }).value?.now
+		).toBe(100);
+	});
+
+	// An indeterminate bar has no value to report, and a `now` of 0 would be read
+	// out as "zero percent" — which is a lie about work that is under way.
+	test("reports busy and no value while indeterminate", () => {
+		expect(resolveProgressAccessibility({ isIndeterminate: true, maxValue: 100, minValue: 0, value: 40 })).toEqual({
+			busy: true,
+			value: undefined,
+		});
+	});
+});

package/src/components/progress/progress.variants.ts

@@ -0,0 +1,284 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { TextSize } from "../text/text.variants";
+
+/** What the filled part of the bar means. The slider's set, so the two name a colour alike. */
+export const PROGRESS_COLORS = ["default", "primary", "success", "warning", "destructive", "info"] as const;
+
+export const PROGRESS_SIZES = ["sm", "md", "lg"] as const;
+
+export type ProgressColor = (typeof PROGRESS_COLORS)[number];
+export type ProgressSize = (typeof PROGRESS_SIZES)[number];
+
+/**
+ * The axes a progress bar falls back to when nothing names one.
+ *
+ * Named once because two places read them — `defaultVariants` below and
+ * {@link resolveProgressAxes}, which runs before `tv` is ever called.
+ */
+export const PROGRESS_DEFAULT_COLOR: ProgressColor = "default";
+export const PROGRESS_DEFAULT_SIZE: ProgressSize = "md";
+
+/** The range a progress bar covers when the caller names none. */
+export const PROGRESS_MIN_VALUE = 0;
+export const PROGRESS_MAX_VALUE = 100;
+
+/**
+ * How long the fill takes to reach a new value.
+ *
+ * Short enough that a bar fed every hundred milliseconds by an upload never
+ * falls visibly behind, long enough that a jump from 20 to 60 reads as travel
+ * rather than as a cut.
+ */
+export const PROGRESS_FILL_DURATION_MS = 320;
+
+/** One pass of the indeterminate segment, from off the left edge to off the right. */
+export const PROGRESS_INDETERMINATE_DURATION_MS = 1400;
+
+/** The indeterminate segment's length, as a fraction of the track. */
+export const PROGRESS_INDETERMINATE_SEGMENT = 0.4;
+
+/**
+ * The reduce-motion stand-in for the indeterminate sweep: the whole track fills
+ * and breathes between these two opacities.
+ *
+ * Never down to zero — a bar that fades out entirely reads as the work having
+ * stopped, which is the one thing an indeterminate bar must not say.
+ */
+export const PROGRESS_PULSE = { from: 0.35, to: 1, durationMs: 900 } as const;
+
+/**
+ * The `Text` size step each progress size hands its label and its readout.
+ *
+ * The slider's own map, restated rather than imported so this leaf imports no
+ * other component's variants; a test pins the two together.
+ */
+export const PROGRESS_OUTPUT_TEXT_SIZE: Record<ProgressSize, TextSize> = { sm: "sm", md: "md", lg: "lg" };
+
+/**
+ * Styling for every part of a progress bar.
+ *
+ * One slotted `tv()` because `progress-label.tsx`, `progress-output.tsx`,
+ * `progress-track.tsx` and `progress-fill.tsx` cannot import the root without
+ * closing a cycle (AGENTS.md rule 3), yet all four read the same `color` and
+ * `size`.
+ *
+ * **The colour paints the fill and never the track.** An empty bar is the same
+ * chrome at every colour — the slider's groove, `bg-secondary` — and a test
+ * pins that.
+ *
+ * **The fill is a full-length bar slid under a clipping track**, not a bar whose
+ * width changes. Its position is a `translateX`, which is a transform — composited
+ * on the UI thread with no layout pass per frame, where an animated `width`
+ * re-lays the bar out every frame of every update. The track's `overflow-hidden`
+ * and `rounded-full` are what make that read as a bar growing from the left: the
+ * part parked beyond the start is clipped, and the leading end keeps its round
+ * cap because it is the fill's own end rather than a cut.
+ *
+ * **The size is the track's thickness and nothing else.** There is no thumb to
+ * keep flush and no touch target to pad, so these are plain spacing steps —
+ * thinner than the slider's groove, because a bar you read is lighter than a
+ * groove you grab.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot parse
+ * React Native's Flow-typed source. See AGENTS.md.
+ */
+export const progressVariants = tv({
+	slots: {
+		/** The column holding the header and the track. */
+		root: "w-full gap-2",
+		/** The row a label and a readout share, when both are given. */
+		header: "flex-row items-center justify-between gap-3",
+		/** Handed to a `Text.Label`. Layout only. */
+		label: "shrink",
+		/** Handed to a `Text.Label`. Layout only. */
+		output: "",
+		/** The clipped, rounded groove the fill slides along. */
+		track: "relative w-full overflow-hidden rounded-full bg-secondary",
+		/** The painted bar. Its position is an animated transform, never a class. */
+		fill: "absolute top-0 bottom-0 left-0 rounded-full",
+	},
+	variants: {
+		size: {
+			sm: { track: "h-1" },
+			md: { track: "h-2" },
+			lg: { track: "h-3" },
+		},
+		color: {
+			default: { fill: "bg-foreground" },
+			primary: { fill: "bg-primary" },
+			success: { fill: "bg-success" },
+			warning: { fill: "bg-warning" },
+			destructive: { fill: "bg-destructive" },
+			info: { fill: "bg-info" },
+		},
+		// The empty branches are load-bearing typing: `tv` types a map holding only
+		// `true` as `true` rather than `boolean`.
+		isIndeterminate: { true: {}, false: {} },
+	},
+	defaultVariants: {
+		color: PROGRESS_DEFAULT_COLOR,
+		size: PROGRESS_DEFAULT_SIZE,
+		isIndeterminate: false,
+	},
+});
+
+/**
+ * Where a value sits in the range, as 0–1.
+ *
+ * Clamped rather than extrapolated, and `0` for a degenerate range or a value
+ * that is not a finite number: a `NaN` written into a shared value freezes the
+ * fill for good, and an upload that divides by a total it has not learned yet
+ * produces exactly that.
+ */
+export function progressRatio(value: number, minValue: number, maxValue: number): number {
+	"worklet";
+	const span = maxValue - minValue;
+	if (!(span > 0) || !Number.isFinite(value)) return 0;
+	const ratio = (value - minValue) / span;
+	return ratio < 0 ? 0 : ratio > 1 ? 1 : ratio;
+}
+
+/**
+ * The fill's `translateX`: how far left of the track's start the full-length bar
+ * is parked.
+ *
+ * A bar at `ratio` shows `ratio × trackSize` of itself, so it sits back by the
+ * rest. `0` on an unmeasured track — the fill is hidden until the first layout,
+ * so there is nothing to place.
+ */
+export function fillTranslate({ ratio, trackSize }: { ratio: number; trackSize: number }): number {
+	"worklet";
+	if (trackSize <= 0) return 0;
+	const clamped = ratio < 0 ? 0 : ratio > 1 ? 1 : ratio;
+	return (clamped - 1) * trackSize;
+}
+
+/**
+ * The indeterminate segment's box at one point in its loop.
+ *
+ * `phase` runs 0–1. At 0 the segment sits wholly off the track's left edge and at
+ * 1 wholly off its right, so the frame where the loop restarts is never on screen
+ * — a sweep that began at the track's start would pop into view every pass.
+ */
+export function indeterminateSegment({
+	phase,
+	segment,
+	trackSize,
+}: {
+	phase: number;
+	segment: number;
+	trackSize: number;
+}): { translate: number; width: number } {
+	"worklet";
+	if (trackSize <= 0) return { translate: 0, width: 0 };
+	const width = segment * trackSize;
+	return { translate: -width + phase * (trackSize + width), width };
+}
+
+/** What {@link formatProgressValue} and {@link resolveProgressAccessibility} read. */
+export type ProgressFormatInput = {
+	value: number;
+	minValue: number;
+	maxValue: number;
+	formatOptions?: Intl.NumberFormatOptions;
+};
+
+/** Whether the readout speaks a percentage of the range, rather than the value itself. */
+function isPercentFormat(formatOptions: Intl.NumberFormatOptions | undefined): boolean {
+	return formatOptions?.style === undefined || formatOptions.style === "percent";
+}
+
+/**
+ * The readout's default text.
+ *
+ * With no `formatOptions`, or a `percent` style, it is the share of the range —
+ * `72%`, or `75%` for 18 of 24. A percent style formats the *ratio* rather than
+ * the value, because `Intl` multiplies by a hundred and a value of 72 would read
+ * `7,200%`. Any other style formats the value itself, so a budget reads `$1,250`.
+ *
+ * JS-thread only — `Intl` is not available to a worklet.
+ */
+export function formatProgressValue({ value, minValue, maxValue, formatOptions }: ProgressFormatInput): string {
+	if (isPercentFormat(formatOptions)) {
+		const format = new Intl.NumberFormat(undefined, { maximumFractionDigits: 0, ...formatOptions, style: "percent" });
+		return format.format(progressRatio(value, minValue, maxValue));
+	}
+	return new Intl.NumberFormat(undefined, formatOptions).format(value);
+}
+
+/** The accessibility surface a progress bar publishes on its root. */
+export type ProgressAccessibility = {
+	busy: boolean;
+	value: { min: number; max: number; now: number; text: string } | undefined;
+};
+
+/**
+ * What assistive technology is told.
+ *
+ * **The spoken text names the range, not only the share of it.** A bar over
+ * 0–100 reads its percentage; any other range reads `18 of 24`, formatted the way
+ * the readout formats the value — because the count is what the screen is about,
+ * and "seventy-five percent" makes the listener do the division back.
+ * `valueLabel` replaces both.
+ *
+ * **An indeterminate bar reports `busy` and no value at all.** A `now` of zero
+ * would be read out as "zero percent", which is a lie about work that is under
+ * way.
+ */
+export function resolveProgressAccessibility({
+	value,
+	minValue,
+	maxValue,
+	formatOptions,
+	isIndeterminate,
+	valueLabel,
+}: ProgressFormatInput & { isIndeterminate: boolean; valueLabel?: string }): ProgressAccessibility {
+	if (isIndeterminate) return { busy: true, value: undefined };
+
+	const ratio = progressRatio(value, minValue, maxValue);
+	const now = minValue + ratio * (maxValue - minValue);
+	const isHundredScale = minValue === 0 && maxValue === 100;
+
+	let text = valueLabel;
+	if (text === undefined) {
+		if (isHundredScale && isPercentFormat(formatOptions)) {
+			text = formatProgressValue({ formatOptions, maxValue, minValue, value });
+		} else {
+			const format = new Intl.NumberFormat(
+				undefined,
+				isPercentFormat(formatOptions) ? { maximumFractionDigits: 2 } : formatOptions
+			);
+			text = `${format.format(now)} of ${format.format(maxValue)}`;
+		}
+	}
+
+	return { busy: false, value: { max: maxValue, min: minValue, now, text } };
+}
+
+/** What a progress bar was given at its own call site. */
+export type ProgressOwnAxes = {
+	color?: ProgressColor;
+	size?: ProgressSize;
+	isIndeterminate?: boolean;
+};
+
+/** Every axis settled, ready to hand to {@link progressVariants} and to context. */
+export type ProgressAxes = Required<ProgressOwnAxes>;
+
+/**
+ * Settles a progress bar's axes.
+ *
+ * One rung, deliberately: a progress bar is an output, not a form control, so an
+ * enclosing `Field` has no disabled or invalid state to hand it. `??` rather than
+ * `||`, so an explicit `false` is a value rather than an absence.
+ */
+export function resolveProgressAxes(own: ProgressOwnAxes): ProgressAxes {
+	return {
+		color: own.color ?? PROGRESS_DEFAULT_COLOR,
+		isIndeterminate: own.isIndeterminate ?? false,
+		size: own.size ?? PROGRESS_DEFAULT_SIZE,
+	};
+}
+
+export type ProgressVariantProps = VariantProps<typeof progressVariants>;