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

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 };
+}

package/src/components/provider/AGENTS.md

@@ -15,14 +15,14 @@ everything — a root layout, an `App.tsx`.
 ## Design
 
 - **Five layers, outermost first**: `GestureHandlerRootView` →
-  `SafeAreaProvider` → `KeyboardProvider` → `<KeyboardStateSync />` beside the
-  children → `BottomSheetModalProvider` around them. The order is not stylistic.
-  The gesture root has to be an ancestor native view of every handler a
-  `Pressable` creates, and its absence is *silent* — no error, no warning,
-  presses simply stop landing. `KeyboardStateSync` has to be a CHILD of
-  `KeyboardProvider`, because it calls `useKeyboardContext()`, and it stays a
-  SIBLING of the modal provider rather than moving inside it: the repair is
-  global and has to outlive any layer that can remount.
+  `SafeAreaProvider` → `KeyboardProvider` → `<KeyboardStateSync />` beside
+  `CalmMotionProvider`, which wraps the children. The order is not stylistic. The gesture root has to be an ancestor
+  native view of every handler a `Pressable` creates, and its absence is
+  *silent* — no error, no warning, presses simply stop landing.
+  `KeyboardStateSync` has to be a CHILD of `KeyboardProvider`, because it calls
+  `useKeyboardContext()`, and it stays a SIBLING of the children rather than
+  wrapping them: the repair is global and has to outlive any layer that can
+  remount.
 - **`initialMetrics` defaults to `initialWindowMetrics`, and that is
   load-bearing.** `SafeAreaProvider` renders `null` — not unstyled children,
   *nothing* — until its native view reports the first `onInsetsChange`, so
@@ -44,25 +44,38 @@ everything — a root layout, an `App.tsx`.
   failure mode, which is the least debuggable outcome in the package. And a prop
   surface that names the layers changes shape every time a layer is added:
   `children`, `style` and `initialMetrics` say nothing about what is inside, so a
-  future `BottomSheetModalProvider` or portal host is an edit to one file rather
-  than a breaking change. An app that genuinely needs a different stack composes
+  future portal host or toast host is an edit to one file rather than a
+  breaking change. An app that genuinely needs a different stack composes
   the providers by hand — they are all public from their own packages, and this
   is a convenience, not a gate.
 - **A new layer goes innermost.** Anything that draws above the app — a
-  bottom-sheet modal provider, a portal host, a toast host — has to sit inside
-  every provider it reads, so it wraps `{children}` and nothing else moves. A
-  layer that brings a new native peer is a peer-dependency decision first.
-  `BottomSheetModalProvider` is the case this rule was written for and now the
-  case it governs: it reads the gesture root for its pan, the safe area for its
-  insets and the keyboard values a sheet's footer rides, so it is last.
-- **`@gorhom/bottom-sheet` is a required peer because of this component**, on
-  exactly the argument `react-native-keyboard-controller` already carries. It was
-  optional while nothing imported it. The recommended root now does, so every app
-  resolves it, and a flag saying otherwise would only suppress the install
-  warning that explains the Metro resolution error coming out of the app's root
-  layout. It is pure JavaScript over Reanimated and Gesture Handler — both
-  required peers already — so this costs an install and no native build. Rule 3's
-  promise survives intact: `/button` still pulls nothing sheet-related.
+  portal host, a toast host — has to sit inside every provider it reads, so it
+  wraps `{children}` and nothing else moves. A layer that brings a new native
+  peer is a peer-dependency decision first.
+- **`BottomSheetProvider` is the layer this component does not mount, and the
+  reason is the peer decision above.** The sheet's engine,
+  `@delacour/react-native-bottom-sheet`, is an **optional** peer of this
+  library, the way `@delacour/react-native-charts` is: an app with no sheet
+  never resolves it, and its native peer `react-native-teleport` never has to
+  be in that app's build. An import here would make every app resolve both,
+  sheet or no sheet. So the provider is exported beside `BottomSheet`, from the
+  sheet's own subpath, and the app mounts it itself, once,
+  inside `DelacourProvider` and around its navigator — innermost, exactly where
+  the rule above puts it, because it reads the gesture root for its pans, the
+  safe area for its insets and the keyboard values a sheet's footer rides.
+  `apps/playground/src/app/_layout.tsx` is the reference mount. Without it a
+  `BottomSheet.Portal` still renders, where it is written, as an inline sheet.
+  The previous sheet library was a required peer while this component mounted
+  its modal provider; nothing imports it any more.
+- **`isMotionCalm` is a behaviour prop, not a layer-named one.** It feeds
+  `CalmMotionProvider` (`hooks/use-calm-motion.tsx`), which `useCalmMotion()`
+  reads beside the OS reduce-motion setting. It exists for E2E builds: a runner
+  that waits for the screen to settle before each gesture (Argent waits up to
+  3 s) pays the whole wait on a screen holding a never-ending loop. Only
+  decorative loops ask — `Skeleton` today; `Spinner` and an indeterminate
+  `Progress` are the behaviour and keep moving. The context defaults to `false`,
+  so a component used without this provider (a `delacour add` copy in an app
+  with its own stack) still honours reduce motion.
 - **Deliberately not idempotent.** It does not detect an enclosing copy of
   itself. Nesting `GestureHandlerRootView` costs a `View`; nesting
   `SafeAreaProvider` seeds from the parent's insets and costs a native view;
@@ -83,7 +96,7 @@ everything — a root layout, an `App.tsx`.
   per-subpath and survives intact: `/button` still pulls nothing
   keyboard-related.
 - **Nothing here for `bun test`, and no `provider.variants.ts` to give it
-  some.** The component is four nested elements and one default parameter;
+  some.** The component is five nested elements and one default parameter;
   extracting a `resolveInitialMetrics()` would be a unit test of `??`. The rule
   that pure decisions live in a `*.variants.ts` has no decision here to
   relocate.