@delacour/react-native-ui 0.1.0-alpha.20261009011834 → 0.1.0-alpha.20261009012154

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20261009011834",
+	"version": "0.1.0-alpha.20261009012154",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -64,6 +64,7 @@
 		"./popover": "./src/components/popover/index.ts",
 		"./pressable": "./src/components/pressable/index.ts",
 		"./progress": "./src/components/progress/index.ts",
+		"./progress-button": "./src/components/progress-button/index.ts",
 		"./provider": "./src/components/provider/index.ts",
 		"./radio": "./src/components/radio/index.ts",
 		"./rating": "./src/components/rating/index.ts",
@@ -115,8 +116,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261009011834",
-		"@delacour/react-native-charts": "0.1.0-alpha.20261009011834",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261009012154",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261009012154",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",

package/src/components/progress-button/AGENTS.md

@@ -0,0 +1,116 @@
+# ProgressButton
+
+A button that has to be **held**, not tapped. A fill grows from the leading edge for
+`holdDuration`, and the action fires when it reaches the end. Compound root plus
+`ProgressButton.Label` and `ProgressButton.Done`. For an irreversible action that would
+otherwise need a confirmation dialog — erasing, paying. Two taps in a row are a rhythm a hand
+falls into; a two-second hold cannot be done by accident or by habit.
+
+`import { ProgressButton } from "@delacour/react-native-ui/progress-button";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/progress-button` |
+| `progress-button.tsx` | Root + the `Object.assign` compound surface: the gesture, the fill, the two label layers, the done mark |
+| `progress-button-label.tsx` | `ProgressButton.Label`, coloured by the layer it renders in |
+| `progress-button-done.tsx` | `ProgressButton.Done`, the default tick or the caller's content |
+| `progress-button.context.tsx` | `ProgressButtonContext`, the layer context, `useProgressButton()` |
+| `progress-button.variants.ts` | Pure `tv()` slots, colour tables, and the hold, playback, stepping and reset resolvers |
+| `progress-button.variants.test.ts` | |
+
+## Design
+
+- **Variants**: `primary`, `secondary`, `destructive`, `success`. **Sizes**: `sm`, `md`, `lg`.
+  **Shapes**: `pill` (default), `rounded`. There is no square `icon-*` size: a hold has to
+  say what it does, and a glyph alone cannot carry "hold to erase".
+- **The box is the button's box.** `h-button-*`, the button's `px-*`, `text-button-*`,
+  `size-icon-*` and, as a pill, `rounded-button-*` — the tokens `buttonVariants` reads, and a
+  test pins them equal to the button's own, so the two sit level in a row and a retune moves
+  both. `rounded` is the card corner, `rounded-lg`, so the button sits square with a
+  `Button` given the same class beside it. No token is minted.
+- **Every variant rests on `bg-secondary` and carries its colour in the label and the fill.**
+  A resting button that is already solid red has nothing left to say when the fill arrives.
+  `secondary` fills with `foreground` and draws its inner label on `background`, because a
+  `secondary` fill on a `secondary` surface would not be seen and `secondary-foreground` on a
+  `foreground` fill is the same colour twice. The three colour tables are exported and a test
+  checks every token in them exists in both themes.
+- **The label is drawn twice.** Once on the surface in the variant colour, once inside the
+  clipped fill in the variant's foreground, laid out at the button's **measured** width
+  (`onLayout`), so both copies wrap identically and the wipe's edge cuts through a glyph. A
+  single label under a translucent wash goes muddy exactly at the boundary, which is where
+  the eye is. A test asserts the two label slots differ in colour and nothing else.
+  `ProgressButton.Label` reads which copy it is from a layer context rather than a prop the
+  caller would have to repeat; a composed `Icon` takes the layer's colour through
+  `IconDefaultsProvider`, the same mechanism `Button` uses.
+- **The fill's copy and the done mark are hidden from assistive technology.** The root is the
+  one accessible element; announcing the label twice would be the fill's bookkeeping leaking
+  into a screen reader.
+- **Bare strings are wrapped in a `ProgressButton.Label`**, consecutive ones collapsing into
+  one, for the reason `Button` gives: React Native crashes on text outside a `<Text>`.
+- **`ProgressButton.Done` is lifted out of the children by type** and drawn over the full fill.
+  With none written the root draws one, which is a full-size `IconCheckmark2` at `size-icon-*` (the `Small` glyph, alone on a button, read as a speck) in
+  the fill's foreground. A caller's `Done` replaces it whole.
+
+## Behaviour
+
+- **The gesture is a pan with no minimum distance**, `onBegin` to `onFinalize`. A long-press
+  gesture fires once and cannot tell "still holding" from "held long enough".
+  `shouldCancelWhenOutside(false)`, and a finger may drift 16pt
+  (`PROGRESS_BUTTON_MAX_DRIFT`) before the hold lets go, because a hand resting on a control for
+  two seconds moves.
+- **Pressing runs the fill toward 1 over what is left** — `holdDuration × (1 − p)` — so a second
+  attempt resumes rather than restarting. **Releasing runs it back over what is filled** —
+  `holdDuration × p` — the same rate, played backwards, never a snap to empty.
+  `resolveRemainingDuration` is the tested copy; the worklets restate it inline because a
+  worklet body must be self-contained.
+- **Completion is read from the animation**, in the timing's finish callback (`finished` at 1),
+  then crosses to JS with `scheduleOnRN`. Never a JS `setTimeout` running alongside: two clocks
+  disagree under load, and the one the user can see is the fill. There is no tolerance near the
+  end — released at 99%, nothing fires.
+- **Completed, it is locked.** A shared `isLocked` flag makes the gesture ignore further presses
+  and stops a release from draining a finished fill, until a reset: `isAutoReset` after
+  `autoResetDelay` (a timer is fine here — it schedules the reset, not the completion), or a
+  controlled `isCompleted` going `false`. **A reset travels** back over
+  `PROGRESS_BUTTON_TRAVEL_MS` scaled by how full the fill is; it is never set to 0. A completion
+  set from outside travels forward the same way.
+- **Controlled, the caller has to accept a hold in the same update.** A completed hold calls
+  `onCompletedChange(true)` and `onComplete`. If `isCompleted` is still `false` once those have
+  run, the fill travels back — the caller declined. The alternative, sitting full and locked
+  until the prop changes, leaves a caller who declines with no prop change to make, so the
+  button would be stuck. A caller with async work accepts at once (`isCompleted` true) and shows
+  progress in a custom `Done`, then sets `false` to rewind on failure; the `controlled` demo does
+  exactly that.
+- **Haptics are off by default.** `haptic` plays when the hold takes, and a `success` knock
+  follows on completion, both from the UI thread through `playHaptic`.
+- **`isDisabled`** fades the button (`opacity-50`) and turns the gesture off, so the fill never
+  starts. A hold in progress when it flips is cancelled and plays back.
+
+## Reduced motion
+
+- **The fill steps in fifths instead of sweeping.** `Math.floor(p × 5) / 5`, applied in the
+  animated style, rounding **down** so it never shows more than the hold has earned. It stays an
+  indicator, because a control that asks you to wait and shows nothing is broken.
+  `resolveSteppedProgress` is the tested copy.
+- **Every timing opts out of the reduce-motion policy** (`ReduceMotion.Never`). Under the default
+  policy Reanimated completes a timing instantly when the setting is on — so a two-second hold
+  would complete on touch-down, which is the one thing this component exists to prevent. The
+  stepping is what reduces the motion; the clock underneath has to keep real time.
+- **The done mark fades without scaling** under reduced motion.
+
+## Accessibility
+
+- `accessibilityRole="button"`, `accessibilityHint` (default: "Press and hold to confirm"), and
+  `accessibilityState={{ disabled, checked: isCompleted }}`.
+- **Decision: activate completes.** The root declares an `activate` accessibility action, and a
+  screen reader's activate completes the button outright. A screen reader cannot hold, the hint
+  has already announced what the button does, and refusing would leave the action unreachable
+  for anyone using one. The slide-to-confirm control makes the same call.
+
+## Out of scope
+
+- An `icon-*` square size, and a loading state of its own — a caller shows work in a custom
+  `Done`.
+- Progress that is not time-based (a fill driven by an upload). That is `Progress`.
+- Cancelling a completed hold from inside the button. Reset is `isAutoReset` or the caller's.

package/src/components/progress-button/index.ts

@@ -0,0 +1,36 @@
+export { ProgressButton, type ProgressButtonProps } from "./progress-button";
+export {
+	type ProgressButtonContextValue,
+	type ProgressButtonLayer,
+	ProgressButtonProvider,
+	useProgressButton,
+	useProgressButtonContext,
+} from "./progress-button.context";
+export {
+	PROGRESS_BUTTON_CROSSFADE_MS,
+	PROGRESS_BUTTON_DEFAULT_AUTO_RESET_MS,
+	PROGRESS_BUTTON_DEFAULT_HINT,
+	PROGRESS_BUTTON_DEFAULT_HOLD_MS,
+	PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN,
+	PROGRESS_BUTTON_FILL_TOKEN,
+	PROGRESS_BUTTON_LABEL_TOKEN,
+	PROGRESS_BUTTON_MAX_DRIFT,
+	PROGRESS_BUTTON_MIN_HOLD_MS,
+	PROGRESS_BUTTON_REDUCED_MOTION_STEPS,
+	PROGRESS_BUTTON_SHAPES,
+	PROGRESS_BUTTON_SIZES,
+	PROGRESS_BUTTON_TRAVEL_MS,
+	PROGRESS_BUTTON_VARIANTS,
+	type ProgressButtonShape,
+	type ProgressButtonSize,
+	type ProgressButtonVariant,
+	type ProgressButtonVariantProps,
+	progressButtonVariants,
+	resolveAutoResetDelay,
+	resolveHoldDuration,
+	resolveProgressButtonAccessibilityState,
+	resolveRemainingDuration,
+	resolveSteppedProgress,
+} from "./progress-button.variants";
+export type { ProgressButtonDoneProps } from "./progress-button-done";
+export type { ProgressButtonLabelProps } from "./progress-button-label";

package/src/components/progress-button/progress-button-done.tsx

@@ -0,0 +1,33 @@
+import type { ReactElement, ReactNode } from "react";
+import { View, type ViewProps } from "react-native";
+import { IconCheckmark2 } from "../../icons/central";
+import { cn } from "../../lib/cn";
+import { Icon } from "../icon";
+import { useProgressButtonPart } from "./progress-button.context";
+
+export type ProgressButtonDoneProps = ViewProps & {
+	/** Replaces the default tick. A bare `Icon` inherits the fill's foreground and the button's icon size. */
+	children?: ReactNode;
+	className?: string;
+};
+
+/**
+ * What the button shows once the hold completes.
+ *
+ * The root lifts this part out of its children by type and draws it over the
+ * full fill, fading and scaling it in as the labels fade out. With no children
+ * it draws a tick; the root draws one of these by itself when the caller writes
+ * none, so the tick is there by default.
+ *
+ * Size and colour come from the `IconDefaultsProvider` the root wraps it in, so
+ * a composed `Icon` matches the default tick with nothing said at the call site.
+ */
+export function ProgressButtonDone({ children, className, ...props }: ProgressButtonDoneProps): ReactElement {
+	useProgressButtonPart("ProgressButton.Done");
+	return (
+		<View className={cn("flex-row items-center justify-center gap-2", className)} {...props}>
+			{children ?? <Icon icon={IconCheckmark2} />}
+		</View>
+	);
+}
+ProgressButtonDone.displayName = "DelacourUI.ProgressButton.Done";

package/src/components/progress-button/progress-button-label.tsx

@@ -0,0 +1,27 @@
+import type { ReactElement, ReactNode } from "react";
+import type { TextProps } from "react-native";
+import { Text } from "../text";
+import { useProgressButtonLayer, useProgressButtonPart } from "./progress-button.context";
+import { progressButtonVariants } from "./progress-button.variants";
+
+export type ProgressButtonLabelProps = Omit<TextProps, "children"> & {
+	children: ReactNode;
+	className?: string;
+};
+
+/**
+ * The button's text.
+ *
+ * Rendered twice by the root, once per layer, and picks its colour from the
+ * layer it is in: the variant colour on the resting surface, the variant's
+ * foreground inside the fill. The two copies share every other class, so they
+ * wrap the same and the wipe's edge falls inside a glyph.
+ */
+export function ProgressButtonLabel({ className, ...props }: ProgressButtonLabelProps): ReactElement {
+	const { variant, size } = useProgressButtonPart("ProgressButton.Label");
+	const layer = useProgressButtonLayer();
+	const slots = progressButtonVariants({ size, variant });
+	const resolved = layer === "fill" ? slots.fillLabel({ className }) : slots.label({ className });
+	return <Text className={resolved} {...props} />;
+}
+ProgressButtonLabel.displayName = "DelacourUI.ProgressButton.Label";

package/src/components/progress-button/progress-button.context.tsx

@@ -0,0 +1,93 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { ProgressButtonSize, ProgressButtonVariant } from "./progress-button.variants";
+
+export type ProgressButtonContextValue = {
+	variant: ProgressButtonVariant;
+	size: ProgressButtonSize;
+	/** Whether the hold has completed and not yet been reset. */
+	isCompleted: boolean;
+	isDisabled: boolean;
+	/** How far the fill has got, 0 to 1, on the UI thread. */
+	progress: SharedValue<number>;
+};
+
+/**
+ * Which copy of the children a part is rendering in.
+ *
+ * The children are drawn twice — once on the resting surface and once inside
+ * the fill — and a `ProgressButton.Label` picks its colour from this rather
+ * than from a prop the caller would have to repeat.
+ */
+export type ProgressButtonLayer = "surface" | "fill";
+
+const ProgressButtonContext = createContext<ProgressButtonContextValue | null>(null);
+const ProgressButtonLayerContext = createContext<ProgressButtonLayer>("surface");
+
+/**
+ * Supplies the enclosing button's state to its subtree.
+ *
+ * In a leaf of its own, importing nothing but types, so a part can read it
+ * without importing `./progress-button` and closing a cycle (package AGENTS.md
+ * rule 3).
+ */
+export function ProgressButtonProvider({
+	value,
+	children,
+}: {
+	value: ProgressButtonContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <ProgressButtonContext value={value}>{children}</ProgressButtonContext>;
+}
+ProgressButtonProvider.displayName = "DelacourUI.ProgressButton.Provider";
+
+/** Marks which copy of the children — surface or fill — its subtree is. */
+export function ProgressButtonLayerProvider({
+	value,
+	children,
+}: {
+	value: ProgressButtonLayer;
+	children: ReactNode;
+}): ReactElement {
+	return <ProgressButtonLayerContext value={value}>{children}</ProgressButtonLayerContext>;
+}
+ProgressButtonLayerProvider.displayName = "DelacourUI.ProgressButton.LayerProvider";
+
+/** The enclosing button's state, or null outside a `<ProgressButton>`. */
+export function useProgressButtonContext(): ProgressButtonContextValue | null {
+	return use(ProgressButtonContext);
+}
+
+/**
+ * Reads the enclosing button's state.
+ *
+ * For a custom child that changes with the hold — `progress` is a shared value,
+ * so a child can drive an animated style off it without a render per frame.
+ * Throws outside a `<ProgressButton>`.
+ */
+export function useProgressButton(): ProgressButtonContextValue {
+	const context = useProgressButtonContext();
+	if (!context) {
+		throw new Error("useProgressButton must be called inside a <ProgressButton>.");
+	}
+	return context;
+}
+
+/**
+ * The enclosing button's state, for a compound part that cannot work without it.
+ *
+ * Internal: deliberately not re-exported from `index.ts`.
+ */
+export function useProgressButtonPart(component: string): ProgressButtonContextValue {
+	const context = useProgressButtonContext();
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <ProgressButton>.`);
+	}
+	return context;
+}
+
+/** Which copy of the children this part is in. `surface` outside a button. */
+export function useProgressButtonLayer(): ProgressButtonLayer {
+	return use(ProgressButtonLayerContext);
+}

package/src/components/progress-button/progress-button.tsx

@@ -0,0 +1,414 @@
+import {
+	Children,
+	type ComponentRef,
+	isValidElement,
+	type ReactElement,
+	type ReactNode,
+	type Ref,
+	useCallback,
+	useEffect,
+	useMemo,
+	useState,
+} from "react";
+import type { AccessibilityActionEvent, LayoutChangeEvent, ViewProps } from "react-native";
+import { Gesture, GestureDetector } from "react-native-gesture-handler";
+import Animated, {
+	Easing,
+	ReduceMotion,
+	useAnimatedStyle,
+	useReducedMotion,
+	useSharedValue,
+	withTiming,
+} from "react-native-reanimated";
+import { scheduleOnRN } from "react-native-worklets";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { IconDefaultsProvider } from "../icon";
+import { type HapticFeedback, playHaptic } from "../pressable/pressable";
+import {
+	type ProgressButtonContextValue,
+	ProgressButtonLayerProvider,
+	ProgressButtonProvider,
+} from "./progress-button.context";
+import {
+	PROGRESS_BUTTON_CROSSFADE_MS,
+	PROGRESS_BUTTON_DEFAULT_HINT,
+	PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN,
+	PROGRESS_BUTTON_LABEL_TOKEN,
+	PROGRESS_BUTTON_MAX_DRIFT,
+	PROGRESS_BUTTON_REDUCED_MOTION_STEPS,
+	PROGRESS_BUTTON_TRAVEL_MS,
+	type ProgressButtonShape,
+	type ProgressButtonSize,
+	type ProgressButtonVariant,
+	progressButtonVariants,
+	resolveAutoResetDelay,
+	resolveHoldDuration,
+	resolveProgressButtonAccessibilityState,
+	resolveRemainingDuration,
+} from "./progress-button.variants";
+import { ProgressButtonDone } from "./progress-button-done";
+import { ProgressButtonLabel } from "./progress-button-label";
+
+export type ProgressButtonProps = Omit<ViewProps, "children"> & {
+	children: ReactNode;
+	className?: string;
+	/** The colour the label and the fill carry. Every variant rests on the same surface. */
+	variant?: ProgressButtonVariant;
+	/** The button's own height, padding, label step and icon step. */
+	size?: ProgressButtonSize;
+	/** `pill` (the default) takes the button's capsule corner; `rounded` takes `rounded-lg`. */
+	shape?: ProgressButtonShape;
+	/** Stretch to the parent's width. */
+	isFullWidth?: boolean;
+	/** How long a full hold takes, in milliseconds. Defaults to 2000, floored at 200. */
+	holdDuration?: number;
+	/** Called once, when the fill reaches the end. */
+	onComplete?: () => void;
+	/** Controlled completion. */
+	isCompleted?: boolean;
+	/** Starting completion while uncontrolled. */
+	defaultCompleted?: boolean;
+	/** Called with `true` when a hold completes, and `false` when the button resets. */
+	onCompletedChange?: (isCompleted: boolean) => void;
+	/** Rewind by itself after `autoResetDelay`. Off by default. */
+	isAutoReset?: boolean;
+	/** How long a completed button waits before `isAutoReset` rewinds it. Defaults to 1000. */
+	autoResetDelay?: number;
+	isDisabled?: boolean;
+	/** Played when the hold takes; a `success` knock follows on completion. Off by default. */
+	haptic?: false | HapticFeedback;
+	/** Defaults to saying the button has to be held. */
+	accessibilityHint?: string;
+	ref?: Ref<ComponentRef<typeof Animated.View>>;
+};
+
+/**
+ * Splits the children into the content drawn on each layer and the caller's
+ * `ProgressButton.Done`, if one was written.
+ *
+ * Consecutive strings collapse into one label, so `Erase {count} files` stays a
+ * single piece of text rather than three spaced apart by the row's gap.
+ */
+function splitChildren(children: ReactNode): { content: ReactNode[]; done: ReactElement | null } {
+	const content: ReactNode[] = [];
+	let done: ReactElement | null = null;
+	let text: string[] = [];
+
+	const flushText = () => {
+		if (text.length === 0) return;
+		content.push(<ProgressButtonLabel key={`label-${content.length}`}>{text.join("")}</ProgressButtonLabel>);
+		text = [];
+	};
+
+	for (const child of Children.toArray(children)) {
+		if (typeof child === "string" || typeof child === "number") {
+			text.push(String(child));
+			continue;
+		}
+		flushText();
+		if (isValidElement(child) && child.type === ProgressButtonDone) {
+			done = child;
+			continue;
+		}
+		content.push(child);
+	}
+	flushText();
+
+	return { content, done };
+}
+
+function ProgressButtonRoot({
+	children,
+	className,
+	variant = "primary",
+	size = "md",
+	shape = "pill",
+	isFullWidth = false,
+	holdDuration: holdDurationProp,
+	onComplete,
+	isCompleted: isCompletedProp,
+	defaultCompleted = false,
+	onCompletedChange,
+	isAutoReset = false,
+	autoResetDelay: autoResetDelayProp,
+	isDisabled = false,
+	haptic = false,
+	accessibilityHint = PROGRESS_BUTTON_DEFAULT_HINT,
+	onLayout,
+	ref,
+	...props
+}: ProgressButtonProps): ReactElement {
+	const holdDuration = resolveHoldDuration(holdDurationProp);
+	const autoResetDelay = resolveAutoResetDelay(autoResetDelayProp);
+	const isReducedMotion = useReducedMotion();
+
+	const [isCompleted, setCompleted] = useControllableState<boolean>({
+		defaultValue: defaultCompleted,
+		onChange: onCompletedChange,
+		value: isCompletedProp,
+	});
+
+	// Bumped by every completed hold. A controlled caller that does not accept
+	// the completion leaves `isCompleted` false, and without a change to key on
+	// the button would sit full and locked forever; this is the change.
+	const [holdCount, setHoldCount] = useState(0);
+
+	const progress = useSharedValue(isCompleted ? 1 : 0);
+	// 1 while completed: the gesture worklets read it to refuse a new hold and to
+	// leave a completed fill where it is on release.
+	const isLocked = useSharedValue(isCompleted ? 1 : 0);
+	const isHolding = useSharedValue(0);
+	const completion = useSharedValue(isCompleted ? 1 : 0);
+	const boxWidth = useSharedValue(0);
+	const [measuredWidth, setMeasuredWidth] = useState(0);
+
+	const complete = useCallback(() => {
+		setCompleted(true);
+		onComplete?.();
+		setHoldCount((count) => count + 1);
+	}, [onComplete, setCompleted]);
+
+	// Follows `isCompleted` whichever side moved it. A completion travels the
+	// fill to the end (already there after a hold); a reset travels it back.
+	// Neither is ever a jump.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `holdCount` is the re-run trigger, not a value read
+	useEffect(() => {
+		completion.value = withTiming(isCompleted ? 1 : 0, {
+			duration: PROGRESS_BUTTON_CROSSFADE_MS,
+			reduceMotion: ReduceMotion.Never,
+		});
+
+		if (isCompleted) {
+			isLocked.value = 1;
+			const remaining = resolveRemainingDuration({
+				direction: "forward",
+				holdDuration: PROGRESS_BUTTON_TRAVEL_MS,
+				progress: progress.value,
+			});
+			if (remaining > 0) {
+				progress.value = withTiming(1, {
+					duration: remaining,
+					easing: Easing.out(Easing.cubic),
+					reduceMotion: ReduceMotion.Never,
+				});
+			}
+			return;
+		}
+
+		if (isLocked.value === 1) {
+			isLocked.value = 0;
+			progress.value = withTiming(0, {
+				duration: resolveRemainingDuration({
+					direction: "reverse",
+					holdDuration: PROGRESS_BUTTON_TRAVEL_MS,
+					progress: progress.value,
+				}),
+				easing: Easing.inOut(Easing.cubic),
+				reduceMotion: ReduceMotion.Never,
+			});
+		}
+	}, [completion, holdCount, isCompleted, isLocked, progress]);
+
+	useEffect(() => {
+		if (!isCompleted || !isAutoReset) return;
+		const timer = setTimeout(() => setCompleted(false), autoResetDelay);
+		return () => clearTimeout(timer);
+	}, [autoResetDelay, isAutoReset, isCompleted, setCompleted]);
+
+	// A pan with no minimum distance begins on touch-down and finalizes on
+	// release or cancel, which is the whole hold. A long-press gesture fires once
+	// and cannot tell "still holding" from "held long enough".
+	const gesture = useMemo(
+		() =>
+			Gesture.Pan()
+				.minDistance(0)
+				.enabled(!isDisabled)
+				.shouldCancelWhenOutside(false)
+				.onBegin(() => {
+					"worklet";
+					if (isLocked.value === 1) return;
+					isHolding.value = 1;
+					if (haptic) playHaptic(haptic);
+					const from = Math.min(1, Math.max(0, progress.value));
+					progress.value = withTiming(
+						1,
+						{ duration: holdDuration * (1 - from), easing: Easing.linear, reduceMotion: ReduceMotion.Never },
+						(finished) => {
+							"worklet";
+							if (!finished || isLocked.value === 1) return;
+							isLocked.value = 1;
+							isHolding.value = 0;
+							if (haptic) playHaptic("success");
+							scheduleOnRN(complete);
+						}
+					);
+				})
+				.onUpdate((event) => {
+					"worklet";
+					if (isHolding.value === 0 || isLocked.value === 1) return;
+					const drift = event.translationX * event.translationX + event.translationY * event.translationY;
+					if (drift <= PROGRESS_BUTTON_MAX_DRIFT * PROGRESS_BUTTON_MAX_DRIFT) return;
+					isHolding.value = 0;
+					const from = Math.min(1, Math.max(0, progress.value));
+					progress.value = withTiming(0, {
+						duration: holdDuration * from,
+						easing: Easing.linear,
+						reduceMotion: ReduceMotion.Never,
+					});
+				})
+				.onFinalize(() => {
+					"worklet";
+					if (isHolding.value === 0 || isLocked.value === 1) return;
+					isHolding.value = 0;
+					const from = Math.min(1, Math.max(0, progress.value));
+					progress.value = withTiming(0, {
+						duration: holdDuration * from,
+						easing: Easing.linear,
+						reduceMotion: ReduceMotion.Never,
+					});
+				}),
+		[complete, haptic, holdDuration, isDisabled, isHolding, isLocked, progress]
+	);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const { width } = event.nativeEvent.layout;
+			boxWidth.value = width;
+			setMeasuredWidth(width);
+			onLayout?.(event);
+		},
+		[boxWidth, onLayout]
+	);
+
+	// A screen reader cannot hold, so activating completes outright. The hint
+	// has already said what the button does.
+	const handleAccessibilityAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			if (event.nativeEvent.actionName !== "activate") return;
+			if (isDisabled || isCompleted) return;
+			isLocked.value = 1;
+			complete();
+		},
+		[complete, isCompleted, isDisabled, isLocked]
+	);
+
+	const fillStyle = useAnimatedStyle(() => {
+		const p = progress.value;
+		const steps = PROGRESS_BUTTON_REDUCED_MOTION_STEPS;
+		const shown = isReducedMotion && p < 1 ? Math.floor(Math.max(0, p) * steps) / steps : p;
+		return { width: shown * boxWidth.value };
+	});
+
+	// One style per view: each copy of the labels fades on its own binding.
+	const labelsStyle = useAnimatedStyle(() => ({ opacity: 1 - completion.value }));
+	const fillLabelsStyle = useAnimatedStyle(() => ({ opacity: 1 - completion.value }));
+
+	const doneStyle = useAnimatedStyle(() => ({
+		opacity: completion.value,
+		transform: [{ scale: isReducedMotion ? 1 : 0.6 + 0.4 * completion.value }],
+	}));
+
+	const context = useMemo<ProgressButtonContextValue>(
+		() => ({ isCompleted, isDisabled, progress, size, variant }),
+		[isCompleted, isDisabled, progress, size, variant]
+	);
+
+	const { content, done } = useMemo(() => splitChildren(children), [children]);
+
+	const slots = progressButtonVariants({ isDisabled, isFullWidth, shape, size, variant });
+	const iconClass = slots.icon();
+	const surfaceIcons = useMemo(
+		() => ({ className: iconClass, color: PROGRESS_BUTTON_LABEL_TOKEN[variant] }),
+		[iconClass, variant]
+	);
+	const fillIcons = useMemo(
+		() => ({ className: iconClass, color: PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN[variant] }),
+		[iconClass, variant]
+	);
+	const innerWidth = { width: measuredWidth };
+
+	// The fill copy and the done mark are hidden from assistive technology: the
+	// root is the one accessible element, and the surface copy already names it.
+	return (
+		<ProgressButtonProvider value={context}>
+			<GestureDetector gesture={gesture}>
+				<Animated.View
+					accessibilityActions={[{ name: "activate" }]}
+					accessibilityHint={accessibilityHint}
+					accessibilityRole="button"
+					accessibilityState={resolveProgressButtonAccessibilityState({ isCompleted, isDisabled })}
+					accessible
+					className={slots.root({ className })}
+					onAccessibilityAction={handleAccessibilityAction}
+					onLayout={handleLayout}
+					ref={ref}
+					{...props}
+				>
+					<Animated.View className={slots.content()} style={labelsStyle}>
+						<ProgressButtonLayerProvider value="surface">
+							<IconDefaultsProvider value={surfaceIcons}>{content}</IconDefaultsProvider>
+						</ProgressButtonLayerProvider>
+					</Animated.View>
+					<Animated.View
+						accessibilityElementsHidden
+						className={slots.fill()}
+						importantForAccessibility="no-hide-descendants"
+						pointerEvents="none"
+						style={fillStyle}
+					>
+						<Animated.View className={slots.fillContent()} style={[innerWidth, fillLabelsStyle]}>
+							<ProgressButtonLayerProvider value="fill">
+								<IconDefaultsProvider value={fillIcons}>{content}</IconDefaultsProvider>
+							</ProgressButtonLayerProvider>
+						</Animated.View>
+						<Animated.View className={slots.done()} style={[innerWidth, doneStyle]}>
+							<ProgressButtonLayerProvider value="fill">
+								<IconDefaultsProvider value={fillIcons}>{done ?? <ProgressButtonDone />}</IconDefaultsProvider>
+							</ProgressButtonLayerProvider>
+						</Animated.View>
+					</Animated.View>
+				</Animated.View>
+			</GestureDetector>
+		</ProgressButtonProvider>
+	);
+}
+
+/**
+ * A button that has to be held, not tapped.
+ *
+ * A fill grows from the leading edge for `holdDuration` and the action fires
+ * when it reaches the end — never before, with no tolerance near it. Released
+ * early, the fill plays back at the rate it went in; pressed again, it resumes
+ * from where it is. For an irreversible action that would otherwise need a
+ * confirmation dialog: two taps are a rhythm a hand falls into, a two-second
+ * hold cannot be done by habit.
+ *
+ * Completion is read off the fill's own animation, then the labels cross-fade
+ * to `ProgressButton.Done` — a tick unless the caller writes one. It stays
+ * completed until `isAutoReset` rewinds it, or a controlled `isCompleted` goes
+ * `false`; either way the fill travels back rather than jumping.
+ *
+ * A screen reader cannot hold, so its activate action completes the button
+ * outright; the default hint says it must be held.
+ *
+ * @example
+ * <ProgressButton onComplete={erase} variant="destructive">
+ *   <ProgressButton.Label>Hold to erase</ProgressButton.Label>
+ * </ProgressButton>
+ *
+ * @example
+ * <ProgressButton isAutoReset haptic="medium" onComplete={pay} variant="success">
+ *   <Icon icon={IconCreditCard1} />
+ *   <ProgressButton.Label>Hold to pay</ProgressButton.Label>
+ *   <ProgressButton.Done>
+ *     <ProgressButton.Label>Paid</ProgressButton.Label>
+ *   </ProgressButton.Done>
+ * </ProgressButton>
+ */
+export const ProgressButton = Object.assign(ProgressButtonRoot, {
+	/** The button's text, drawn once on the surface and once inside the fill. */
+	Label: ProgressButtonLabel,
+	/** What shows once the hold completes. A tick when omitted. */
+	Done: ProgressButtonDone,
+	displayName: "DelacourUI.ProgressButton",
+});

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

@@ -0,0 +1,314 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import { buttonVariants } from "../button/button.variants";
+import {
+	PROGRESS_BUTTON_DEFAULT_AUTO_RESET_MS,
+	PROGRESS_BUTTON_DEFAULT_HINT,
+	PROGRESS_BUTTON_DEFAULT_HOLD_MS,
+	PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN,
+	PROGRESS_BUTTON_FILL_TOKEN,
+	PROGRESS_BUTTON_LABEL_TOKEN,
+	PROGRESS_BUTTON_MIN_HOLD_MS,
+	PROGRESS_BUTTON_REDUCED_MOTION_STEPS,
+	PROGRESS_BUTTON_SHAPES,
+	PROGRESS_BUTTON_SIZES,
+	PROGRESS_BUTTON_VARIANTS,
+	progressButtonVariants,
+	resolveAutoResetDelay,
+	resolveHoldDuration,
+	resolveProgressButtonAccessibilityState,
+	resolveRemainingDuration,
+	resolveSteppedProgress,
+} from "./progress-button.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** Every theme token a class string paints with, with any `/alpha` suffix dropped. */
+function colorTokens(cls: string): string[] {
+	const tokens: string[] = [];
+	for (const [, utility, token] of cls.matchAll(/\b(bg|text)-([a-z][\w-]*)(?:\/\d+)?\b/g)) {
+		if (utility === "text" && token.startsWith("button-")) continue;
+		if (utility === "text" && (token === "center" || token === "left" || token === "right")) continue;
+		tokens.push(token);
+	}
+	return tokens;
+}
+
+const SLOT_NAMES = ["root", "content", "fill", "fillContent", "label", "fillLabel", "done", "icon"] as const;
+
+/** Every colour token any slot names, across the whole variant × size × shape matrix. */
+function everySlotToken(): string[] {
+	const tokens = new Set<string>();
+	const combos = PROGRESS_BUTTON_VARIANTS.flatMap((variant) =>
+		PROGRESS_BUTTON_SIZES.flatMap((size) => PROGRESS_BUTTON_SHAPES.map((shape) => ({ shape, size, variant })))
+	);
+	for (const combo of combos) {
+		const slots = progressButtonVariants(combo);
+		for (const name of SLOT_NAMES) {
+			for (const token of colorTokens(slots[name]() ?? "")) tokens.add(token);
+		}
+	}
+	return [...tokens];
+}
+
+describe("resolveHoldDuration", () => {
+	test("defaults to two seconds", () => {
+		expect(PROGRESS_BUTTON_DEFAULT_HOLD_MS).toBe(2000);
+		expect(resolveHoldDuration()).toBe(2000);
+		expect(resolveHoldDuration(undefined)).toBe(2000);
+	});
+
+	test("passes a sensible value through", () => {
+		expect(resolveHoldDuration(1500)).toBe(1500);
+		expect(resolveHoldDuration(200)).toBe(200);
+	});
+
+	test("floors a hold too short to be deliberate", () => {
+		expect(PROGRESS_BUTTON_MIN_HOLD_MS).toBe(200);
+		expect(resolveHoldDuration(50)).toBe(200);
+		expect(resolveHoldDuration(0)).toBe(200);
+		expect(resolveHoldDuration(-1000)).toBe(200);
+	});
+
+	test("a non-finite value gives the default", () => {
+		expect(resolveHoldDuration(Number.NaN)).toBe(2000);
+		expect(resolveHoldDuration(Number.POSITIVE_INFINITY)).toBe(2000);
+		expect(resolveHoldDuration(Number.NEGATIVE_INFINITY)).toBe(2000);
+	});
+});
+
+describe("resolveRemainingDuration", () => {
+	test("forward from empty is the whole hold", () => {
+		expect(resolveRemainingDuration({ direction: "forward", holdDuration: 2000, progress: 0 })).toBe(2000);
+	});
+
+	test("forward resumes from where the fill is", () => {
+		expect(resolveRemainingDuration({ direction: "forward", holdDuration: 2000, progress: 0.25 })).toBe(1500);
+		expect(resolveRemainingDuration({ direction: "forward", holdDuration: 2000, progress: 1 })).toBe(0);
+	});
+
+	test("reverse plays back at the same rate", () => {
+		expect(resolveRemainingDuration({ direction: "reverse", holdDuration: 2000, progress: 0.9 })).toBeCloseTo(1800);
+		expect(resolveRemainingDuration({ direction: "reverse", holdDuration: 2000, progress: 0 })).toBe(0);
+	});
+
+	test("forward and reverse at one point sum to the hold", () => {
+		for (const progress of [0, 0.1, 0.5, 0.73, 1]) {
+			const forward = resolveRemainingDuration({ direction: "forward", holdDuration: 1200, progress });
+			const reverse = resolveRemainingDuration({ direction: "reverse", holdDuration: 1200, progress });
+			expect(forward + reverse).toBeCloseTo(1200);
+		}
+	});
+
+	test("clamps progress outside 0..1 and treats a non-finite one as empty", () => {
+		expect(resolveRemainingDuration({ direction: "forward", holdDuration: 2000, progress: -0.5 })).toBe(2000);
+		expect(resolveRemainingDuration({ direction: "forward", holdDuration: 2000, progress: 1.5 })).toBe(0);
+		expect(resolveRemainingDuration({ direction: "reverse", holdDuration: 2000, progress: Number.NaN })).toBe(0);
+	});
+});
+
+describe("resolveSteppedProgress", () => {
+	test("steps in fifths by default", () => {
+		expect(PROGRESS_BUTTON_REDUCED_MOTION_STEPS).toBe(5);
+		expect(resolveSteppedProgress(0)).toBe(0);
+		expect(resolveSteppedProgress(0.19)).toBe(0);
+		expect(resolveSteppedProgress(0.2)).toBe(0.2);
+		expect(resolveSteppedProgress(0.39)).toBe(0.2);
+		expect(resolveSteppedProgress(0.5)).toBe(0.4);
+		expect(resolveSteppedProgress(0.99)).toBe(0.8);
+		expect(resolveSteppedProgress(1)).toBe(1);
+	});
+
+	test("takes another step count", () => {
+		expect(resolveSteppedProgress(0.6, 2)).toBe(0.5);
+		expect(resolveSteppedProgress(0.3, 4)).toBe(0.25);
+	});
+
+	test("clamps, and never shows more than the hold has earned", () => {
+		expect(resolveSteppedProgress(-1)).toBe(0);
+		expect(resolveSteppedProgress(2)).toBe(1);
+		expect(resolveSteppedProgress(Number.NaN)).toBe(0);
+		for (let p = 0; p <= 1; p += 0.01) {
+			expect(resolveSteppedProgress(p)).toBeLessThanOrEqual(p + 1e-9);
+		}
+	});
+
+	test("a step count below one is treated as one", () => {
+		expect(resolveSteppedProgress(0.5, 0)).toBe(0);
+		expect(resolveSteppedProgress(1, 0)).toBe(1);
+	});
+});
+
+describe("resolveAutoResetDelay", () => {
+	test("defaults to a second", () => {
+		expect(PROGRESS_BUTTON_DEFAULT_AUTO_RESET_MS).toBe(1000);
+		expect(resolveAutoResetDelay()).toBe(1000);
+	});
+
+	test("passes a value through and floors a negative one at zero", () => {
+		expect(resolveAutoResetDelay(2500)).toBe(2500);
+		expect(resolveAutoResetDelay(0)).toBe(0);
+		expect(resolveAutoResetDelay(-5)).toBe(0);
+	});
+
+	test("a non-finite value gives the default", () => {
+		expect(resolveAutoResetDelay(Number.NaN)).toBe(1000);
+		expect(resolveAutoResetDelay(Number.POSITIVE_INFINITY)).toBe(1000);
+	});
+});
+
+describe("resolveProgressButtonAccessibilityState", () => {
+	test("announces disabled and completed as checked", () => {
+		expect(resolveProgressButtonAccessibilityState({ isCompleted: false, isDisabled: false })).toEqual({
+			checked: false,
+			disabled: false,
+		});
+		expect(resolveProgressButtonAccessibilityState({ isCompleted: true, isDisabled: true })).toEqual({
+			checked: true,
+			disabled: true,
+		});
+	});
+
+	test("the default hint says the button has to be held", () => {
+		expect(PROGRESS_BUTTON_DEFAULT_HINT.toLowerCase()).toContain("hold");
+	});
+});
+
+describe("progressButtonVariants — axes", () => {
+	test("exposes the variants, sizes and shapes the API names", () => {
+		expect([...PROGRESS_BUTTON_VARIANTS]).toEqual(["primary", "secondary", "destructive", "success"]);
+		expect([...PROGRESS_BUTTON_SIZES]).toEqual(["sm", "md", "lg"]);
+		expect([...PROGRESS_BUTTON_SHAPES]).toEqual(["pill", "rounded"]);
+	});
+
+	test("defaults to primary, md, pill", () => {
+		const root = progressButtonVariants().root();
+		expect(root).toContain("h-button-md");
+		expect(root).toContain("rounded-button-md");
+		expect(progressButtonVariants().fill()).toContain("bg-primary");
+	});
+
+	test("every variant rests on the same surface", () => {
+		for (const variant of PROGRESS_BUTTON_VARIANTS) {
+			const root = progressButtonVariants({ variant }).root();
+			expect(root).toContain("bg-secondary");
+			expect(colorTokens(root)).toEqual(["secondary"]);
+		}
+	});
+
+	test("the variant colour is carried by the fill and the labels", () => {
+		for (const variant of PROGRESS_BUTTON_VARIANTS) {
+			const slots = progressButtonVariants({ variant });
+			expect(slots.fill()).toContain(`bg-${PROGRESS_BUTTON_FILL_TOKEN[variant]}`);
+			expect(slots.label()).toContain(`text-${PROGRESS_BUTTON_LABEL_TOKEN[variant]}`);
+			expect(slots.fillLabel()).toContain(`text-${PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN[variant]}`);
+		}
+	});
+
+	test("secondary fills with the foreground and draws its inner label on the background", () => {
+		const slots = progressButtonVariants({ variant: "secondary" });
+		expect(slots.fill()).toContain("bg-foreground");
+		expect(slots.label()).toContain("text-secondary-foreground");
+		expect(slots.fillLabel()).toContain("text-background");
+	});
+
+	test("the two label copies differ only in colour", () => {
+		for (const variant of PROGRESS_BUTTON_VARIANTS) {
+			for (const size of PROGRESS_BUTTON_SIZES) {
+				const slots = progressButtonVariants({ size, variant });
+				const strip = (cls: string) =>
+					cls
+						.split(/\s+/)
+						.filter((c) => colorTokens(c).length === 0)
+						.sort();
+				expect(strip(slots.label())).toEqual(strip(slots.fillLabel()));
+			}
+		}
+	});
+
+	test("the fill is clipped and anchored to the leading edge", () => {
+		const fill = progressButtonVariants().fill();
+		for (const cls of ["absolute", "overflow-hidden", "inset-y-0", "start-0"]) {
+			expect(fill).toContain(cls);
+		}
+	});
+});
+
+describe("progressButtonVariants — the button's box", () => {
+	test("height, padding, label step and icon step come off the button's own size tokens", () => {
+		for (const size of PROGRESS_BUTTON_SIZES) {
+			const ours = progressButtonVariants({ size });
+			const button = buttonVariants({ size });
+			const buttonRoot = button.root().split(/\s+/);
+			const height = buttonRoot.find((c) => c.startsWith("h-button-"));
+			const padding = buttonRoot.find((c) => c.startsWith("px-"));
+			expect(height).toBeDefined();
+			expect(padding).toBeDefined();
+			expect(ours.root()).toContain(height as string);
+			expect(ours.root()).toContain(padding as string);
+			expect(ours.fillContent()).toContain(padding as string);
+			expect(ours.label()).toContain(`text-button-${size}`);
+			expect(ours.icon()).toContain(`size-icon-${size}`);
+		}
+	});
+
+	test("a pill takes the button's corner, rounded takes the card's", () => {
+		for (const size of PROGRESS_BUTTON_SIZES) {
+			expect(progressButtonVariants({ shape: "pill", size }).root()).toContain(`rounded-button-${size}`);
+			const rounded = progressButtonVariants({ shape: "rounded", size }).root();
+			expect(rounded).toContain("rounded-lg");
+			expect(rounded).not.toContain("rounded-button-");
+		}
+	});
+
+	test("full width stretches", () => {
+		const root = progressButtonVariants({ isFullWidth: true }).root();
+		expect(root).toContain("w-full");
+		expect(root).toContain("self-stretch");
+		expect(progressButtonVariants({ isFullWidth: false }).root()).not.toContain("w-full");
+	});
+
+	test("disabled fades", () => {
+		expect(progressButtonVariants({ isDisabled: true }).root()).toContain("opacity-50");
+		expect(progressButtonVariants({ isDisabled: false }).root()).not.toContain("opacity-50");
+	});
+
+	test("a caller's className merges over the root's own", () => {
+		const root = progressButtonVariants().root({ className: "rounded-none" });
+		expect(root).toContain("rounded-none");
+		expect(root).not.toContain("rounded-button-md");
+	});
+});
+
+describe("progressButtonVariants — theme tokens", () => {
+	test("the theme reader found both variants, and the slots name some tokens", () => {
+		expect(LIGHT.size).toBeGreaterThan(0);
+		expect(DARK.size).toBeGreaterThan(0);
+		expect(everySlotToken().length).toBeGreaterThan(4);
+	});
+
+	test("every token named in every slot, at every axis, exists in both themes", () => {
+		const missing = everySlotToken().filter((token) => !(LIGHT.has(token) && DARK.has(token)));
+		expect(missing).toEqual([]);
+	});
+
+	test("every token in the colour tables exists in both themes", () => {
+		for (const table of [
+			PROGRESS_BUTTON_FILL_TOKEN,
+			PROGRESS_BUTTON_LABEL_TOKEN,
+			PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN,
+		]) {
+			for (const variant of PROGRESS_BUTTON_VARIANTS) {
+				expect(LIGHT.has(table[variant])).toBe(true);
+				expect(DARK.has(table[variant])).toBe(true);
+			}
+		}
+	});
+
+	test("the fill and its label never share a token", () => {
+		for (const variant of PROGRESS_BUTTON_VARIANTS) {
+			expect(PROGRESS_BUTTON_FILL_TOKEN[variant]).not.toBe(PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN[variant]);
+		}
+	});
+});

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

@@ -0,0 +1,236 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+export const PROGRESS_BUTTON_VARIANTS = ["primary", "secondary", "destructive", "success"] as const;
+
+/** The button's label sizes. A hold needs a label, so there is no square `icon-*` step. */
+export const PROGRESS_BUTTON_SIZES = ["sm", "md", "lg"] as const;
+
+/** `pill` takes the button's capsule corner; `rounded` takes the card's `rounded-lg`. */
+export const PROGRESS_BUTTON_SHAPES = ["pill", "rounded"] as const;
+
+export type ProgressButtonVariant = (typeof PROGRESS_BUTTON_VARIANTS)[number];
+export type ProgressButtonSize = (typeof PROGRESS_BUTTON_SIZES)[number];
+export type ProgressButtonShape = (typeof PROGRESS_BUTTON_SHAPES)[number];
+
+/** How long a hold takes when nothing says otherwise. */
+export const PROGRESS_BUTTON_DEFAULT_HOLD_MS = 2000;
+
+/** The shortest hold accepted. Anything quicker is a long tap, not a decision. */
+export const PROGRESS_BUTTON_MIN_HOLD_MS = 200;
+
+/** How long a completed button waits before `isAutoReset` rewinds it. */
+export const PROGRESS_BUTTON_DEFAULT_AUTO_RESET_MS = 1000;
+
+/** How long a reset, or a completion set from outside, takes to travel the whole width. */
+export const PROGRESS_BUTTON_TRAVEL_MS = 400;
+
+/** How long the labels and the done mark take to cross-fade. */
+export const PROGRESS_BUTTON_CROSSFADE_MS = 200;
+
+/** How far, in points, a resting finger may drift before the hold lets go. */
+export const PROGRESS_BUTTON_MAX_DRIFT = 16;
+
+/** How many discrete steps the fill takes under reduced motion. */
+export const PROGRESS_BUTTON_REDUCED_MOTION_STEPS = 5;
+
+/** What VoiceOver and TalkBack read after the label when no `accessibilityHint` is given. */
+export const PROGRESS_BUTTON_DEFAULT_HINT = "Press and hold to confirm";
+
+/**
+ * Theme token each variant fills with.
+ *
+ * `secondary` fills with the foreground: its resting surface already is
+ * `bg-secondary`, and a fill the same colour as the surface under it would not
+ * be seen at all.
+ */
+export const PROGRESS_BUTTON_FILL_TOKEN: Record<ProgressButtonVariant, string> = {
+	primary: "primary",
+	secondary: "foreground",
+	destructive: "destructive",
+	success: "success",
+};
+
+/** Theme token the resting label, and a composed icon on the surface, are drawn in. */
+export const PROGRESS_BUTTON_LABEL_TOKEN: Record<ProgressButtonVariant, string> = {
+	primary: "primary",
+	secondary: "secondary-foreground",
+	destructive: "destructive",
+	success: "success",
+};
+
+/**
+ * Theme token the label copy inside the fill, its icons and the done mark are drawn in.
+ *
+ * `secondary` draws on `background`, the token `foreground` is the foreground
+ * *of* — `secondary-foreground` on a `foreground` fill would be the same colour
+ * twice.
+ */
+export const PROGRESS_BUTTON_FILL_FOREGROUND_TOKEN: Record<ProgressButtonVariant, string> = {
+	primary: "primary-foreground",
+	secondary: "background",
+	destructive: "destructive-foreground",
+	success: "success-foreground",
+};
+
+/**
+ * Styling for every part of a progress button.
+ *
+ * The box is a button's box: `h-button-*`, the button's `px-*` and, as a pill,
+ * `rounded-button-*` — the same tokens `buttonVariants` reads, never new ones,
+ * and a test pins them equal. Every variant rests on one surface,
+ * `bg-secondary`, and carries its colour in the label and the fill.
+ *
+ * The label is drawn twice. `label` sits on the surface; `fillLabel` sits inside
+ * the clipped fill, laid out in `fillContent` at the button's measured width so
+ * both copies wrap the same and the wipe's edge cuts through a glyph rather
+ * than between two different layouts. The two differ only in colour — a test
+ * asserts it.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const progressButtonVariants = tv({
+	slots: {
+		root: "relative flex-row items-center justify-center overflow-hidden bg-secondary",
+		/** The surface layer: the resting label and anything composed beside it. */
+		content: "flex-row items-center justify-center gap-2",
+		fill: "absolute inset-y-0 start-0 overflow-hidden",
+		/** The fill's inner copy, laid out at the root's measured width. */
+		fillContent: "absolute inset-y-0 start-0 flex-row items-center justify-center gap-2",
+		label: "text-center font-semibold",
+		fillLabel: "text-center font-semibold",
+		/** Where the done mark sits: the whole box, on the fill. */
+		done: "absolute inset-y-0 start-0 items-center justify-center",
+		/** Edge length a composed `Icon`, and the default tick, inherit. */
+		icon: "",
+	},
+	variants: {
+		variant: {
+			primary: { fill: "bg-primary", label: "text-primary", fillLabel: "text-primary-foreground" },
+			secondary: {
+				fill: "bg-foreground",
+				label: "text-secondary-foreground",
+				fillLabel: "text-background",
+			},
+			destructive: {
+				fill: "bg-destructive",
+				label: "text-destructive",
+				fillLabel: "text-destructive-foreground",
+			},
+			success: { fill: "bg-success", label: "text-success", fillLabel: "text-success-foreground" },
+		},
+		// Written out rather than built: Tailwind scans source text, and a class
+		// assembled at runtime is never compiled.
+		size: {
+			sm: {
+				root: "h-button-sm px-3",
+				content: "gap-1.5",
+				fillContent: "gap-1.5 px-3",
+				label: "text-button-sm",
+				fillLabel: "text-button-sm",
+				icon: "size-icon-sm",
+			},
+			md: {
+				root: "h-button-md px-4",
+				fillContent: "px-4",
+				label: "text-button-md",
+				fillLabel: "text-button-md",
+				icon: "size-icon-md",
+			},
+			lg: {
+				root: "h-button-lg px-5",
+				fillContent: "px-5",
+				label: "text-button-lg",
+				fillLabel: "text-button-lg",
+				icon: "size-icon-lg",
+			},
+		},
+		// The pill's corner depends on the size, so it is a compound cell below.
+		shape: { pill: {}, rounded: { root: "rounded-lg" } },
+		isFullWidth: { true: { root: "w-full self-stretch" }, false: {} },
+		isDisabled: { true: { root: "opacity-50" }, false: {} },
+	},
+	compoundVariants: [
+		{ shape: "pill", size: "sm", class: { root: "rounded-button-sm" } },
+		{ shape: "pill", size: "md", class: { root: "rounded-button-md" } },
+		{ shape: "pill", size: "lg", class: { root: "rounded-button-lg" } },
+	],
+	defaultVariants: {
+		variant: "primary",
+		size: "md",
+		shape: "pill",
+		isFullWidth: false,
+		isDisabled: false,
+	},
+});
+
+export type ProgressButtonVariantProps = VariantProps<typeof progressButtonVariants>;
+
+/**
+ * How long a full hold takes, in milliseconds.
+ *
+ * Defaults to {@link PROGRESS_BUTTON_DEFAULT_HOLD_MS} and is floored at
+ * {@link PROGRESS_BUTTON_MIN_HOLD_MS}. A non-finite value — `NaN` from a
+ * division somewhere upstream — takes the default rather than a hold that
+ * completes instantly or never.
+ */
+export function resolveHoldDuration(ms?: number): number {
+	if (ms === undefined || !Number.isFinite(ms)) return PROGRESS_BUTTON_DEFAULT_HOLD_MS;
+	return Math.max(PROGRESS_BUTTON_MIN_HOLD_MS, ms);
+}
+
+/** How long a completed button waits before rewinding itself. Non-negative. */
+export function resolveAutoResetDelay(ms?: number): number {
+	if (ms === undefined || !Number.isFinite(ms)) return PROGRESS_BUTTON_DEFAULT_AUTO_RESET_MS;
+	return Math.max(0, ms);
+}
+
+/**
+ * How long the fill takes to travel from `progress` to its end, at the hold's rate.
+ *
+ * `forward` is what is left to fill — `holdDuration × (1 − p)` — so a second
+ * press resumes rather than restarting. `reverse` is what is filled —
+ * `holdDuration × p` — so a release plays the fill back at the same speed it
+ * went in, and the two at one point always sum to the whole hold.
+ *
+ * The worklet that drives the fill restates this inline, because a worklet body
+ * must be self-contained; this copy is the one the tests pin.
+ */
+export function resolveRemainingDuration({
+	holdDuration,
+	progress,
+	direction,
+}: {
+	holdDuration: number;
+	progress: number;
+	direction: "forward" | "reverse";
+}): number {
+	const p = Number.isFinite(progress) ? Math.min(1, Math.max(0, progress)) : 0;
+	return holdDuration * (direction === "forward" ? 1 - p : p);
+}
+
+/**
+ * The fill shown under reduced motion: `progress` rounded down to a step.
+ *
+ * Down, never to nearest, so the fill never shows more than the hold has
+ * earned — a full bar appears only at 1. The animated style restates this
+ * inline (worklet bodies must be self-contained); this copy is the tested one.
+ */
+export function resolveSteppedProgress(progress: number, steps: number = PROGRESS_BUTTON_REDUCED_MOTION_STEPS): number {
+	const p = Number.isFinite(progress) ? Math.min(1, Math.max(0, progress)) : 0;
+	if (p >= 1) return 1;
+	if (!(steps >= 1)) return 0;
+	const count = Math.floor(steps);
+	return Math.floor(p * count) / count;
+}
+
+/** What a screen reader is told about the button's state. Completed reads as checked. */
+export function resolveProgressButtonAccessibilityState({
+	isDisabled,
+	isCompleted,
+}: {
+	isDisabled: boolean;
+	isCompleted: boolean;
+}): { disabled: boolean; checked: boolean } {
+	return { checked: isCompleted, disabled: isDisabled };
+}