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

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

@@ -0,0 +1,245 @@
+import { describe, expect, test } from "bun:test";
+import {
+	resolveSkeletonAccessibility,
+	resolveSkeletonAnimation,
+	resolveSkeletonLineWidths,
+	SKELETON_ANIMATIONS,
+	SKELETON_FILL_CLASS,
+	SKELETON_LAST_LINE_WIDTH,
+	SKELETON_PULSE_MIN_OPACITY,
+	SKELETON_SHAPES,
+	SKELETON_SHIMMER_PEAK_OPACITY,
+	SKELETON_SHIMMER_STOPS,
+	skeletonPulseOpacity,
+	skeletonShimmerOffset,
+	skeletonVariants,
+} from "./skeleton.variants";
+
+describe("resolveSkeletonAnimation", () => {
+	test("passes every requested animation through when motion is allowed", () => {
+		for (const animation of SKELETON_ANIMATIONS) {
+			expect(resolveSkeletonAnimation(animation, false)).toBe(animation);
+		}
+	});
+
+	// The shape is the message. A placeholder that stops moving still reads as
+	// content on its way, so reduce-motion stills it rather than hiding it.
+	test("stills every animation under reduce motion", () => {
+		for (const animation of SKELETON_ANIMATIONS) {
+			expect(resolveSkeletonAnimation(animation, true)).toBe("none");
+		}
+	});
+
+	test("shimmers by default", () => {
+		expect(resolveSkeletonAnimation(undefined, false)).toBe("shimmer");
+	});
+});
+
+describe("skeletonPulseOpacity", () => {
+	test("starts and ends a cycle fully opaque, so the loop has no seam", () => {
+		expect(skeletonPulseOpacity(0)).toBeCloseTo(1, 10);
+		expect(skeletonPulseOpacity(1)).toBeCloseTo(1, 10);
+	});
+
+	test("reaches its floor half way through the cycle", () => {
+		expect(skeletonPulseOpacity(0.5)).toBeCloseTo(SKELETON_PULSE_MIN_OPACITY, 10);
+	});
+
+	test("never leaves the band between the floor and opaque", () => {
+		for (let step = 0; step <= 100; step++) {
+			const opacity = skeletonPulseOpacity(step / 100);
+			expect(opacity).toBeGreaterThanOrEqual(SKELETON_PULSE_MIN_OPACITY - 1e-9);
+			expect(opacity).toBeLessThanOrEqual(1 + 1e-9);
+		}
+	});
+
+	test("is symmetric, so it breathes in and out at one rate", () => {
+		expect(skeletonPulseOpacity(0.2)).toBeCloseTo(skeletonPulseOpacity(0.8), 10);
+	});
+
+	// A floor at zero would make the placeholder blink out of existence, which
+	// reads as a layout that is failing rather than one that is loading.
+	test("keeps the floor visible", () => {
+		expect(SKELETON_PULSE_MIN_OPACITY).toBeGreaterThan(0.3);
+		expect(SKELETON_PULSE_MIN_OPACITY).toBeLessThan(1);
+	});
+});
+
+describe("skeletonShimmerOffset", () => {
+	// Both ends of the sweep sit fully outside the placeholder, so the band
+	// enters from nothing and leaves to nothing and the loop has no visible jump.
+	test("starts wholly off the leading edge", () => {
+		expect(skeletonShimmerOffset(0, 200, 80)).toBe(-80);
+	});
+
+	test("ends wholly off the trailing edge", () => {
+		expect(skeletonShimmerOffset(1, 200, 80)).toBe(200);
+	});
+
+	test("advances linearly", () => {
+		const a = skeletonShimmerOffset(0.25, 200, 80);
+		const b = skeletonShimmerOffset(0.5, 200, 80);
+		const c = skeletonShimmerOffset(0.75, 200, 80);
+		expect(b - a).toBeCloseTo(c - b, 10);
+	});
+
+	test("stays off-screen before the placeholder has been measured", () => {
+		expect(skeletonShimmerOffset(0.5, 0, 80)).toBeLessThanOrEqual(0);
+	});
+});
+
+describe("SKELETON_SHIMMER_STOPS", () => {
+	test("fades in from nothing and back out to nothing", () => {
+		expect(SKELETON_SHIMMER_STOPS.at(0)).toEqual({ offset: 0, opacity: 0 });
+		expect(SKELETON_SHIMMER_STOPS.at(-1)).toEqual({ offset: 1, opacity: 0 });
+	});
+
+	test("peaks in the middle of the band", () => {
+		const peak = SKELETON_SHIMMER_STOPS.reduce((best, stop) => (stop.opacity > best.opacity ? stop : best));
+		expect(peak.offset).toBe(0.5);
+		expect(peak.opacity).toBe(SKELETON_SHIMMER_PEAK_OPACITY);
+	});
+
+	test("is symmetric about its centre", () => {
+		const offsets = SKELETON_SHIMMER_STOPS.map((stop) => stop.offset);
+		const mirrored = [...SKELETON_SHIMMER_STOPS].reverse().map((stop) => 1 - stop.offset);
+		expect(mirrored).toEqual(offsets);
+	});
+
+	test("advances along the band", () => {
+		for (const [index, stop] of SKELETON_SHIMMER_STOPS.slice(1).entries()) {
+			expect(stop.offset).toBeGreaterThan(SKELETON_SHIMMER_STOPS[index]?.offset ?? 1);
+		}
+	});
+});
+
+describe("resolveSkeletonLineWidths", () => {
+	test("gives one width per line", () => {
+		expect(resolveSkeletonLineWidths(4)).toHaveLength(4);
+	});
+
+	test("shortens only the last line, the way a paragraph ends", () => {
+		expect(resolveSkeletonLineWidths(3)).toEqual(["100%", "100%", `${SKELETON_LAST_LINE_WIDTH * 100}%`]);
+	});
+
+	test("takes a custom last-line fraction", () => {
+		expect(resolveSkeletonLineWidths(2, 0.4)).toEqual(["100%", "40%"]);
+	});
+
+	// A single line is a title or a label, and whoever wrote it knows how long
+	// it is. Shortening it would second-guess a width they did not ask for.
+	test("leaves a single line full width", () => {
+		expect(resolveSkeletonLineWidths(1)).toEqual(["100%"]);
+	});
+
+	test("draws nothing for a count below one or a fraction", () => {
+		expect(resolveSkeletonLineWidths(0)).toEqual([]);
+		expect(resolveSkeletonLineWidths(-2)).toEqual([]);
+		expect(resolveSkeletonLineWidths(2.7)).toHaveLength(2);
+	});
+
+	test("clamps the last-line fraction into the line", () => {
+		expect(resolveSkeletonLineWidths(2, 1.5)).toEqual(["100%", "100%"]);
+		expect(resolveSkeletonLineWidths(2, -1)).toEqual(["100%", "0%"]);
+	});
+});
+
+describe("resolveSkeletonAccessibility", () => {
+	test("hides an unlabelled placeholder from assistive technology", () => {
+		const a11y = resolveSkeletonAccessibility({ isLoading: true });
+		expect(a11y.kind).toBe("hidden");
+		expect(a11y.props.accessibilityElementsHidden).toBe(true);
+		expect(a11y.props.importantForAccessibility).toBe("no-hide-descendants");
+	});
+
+	test("announces a labelled placeholder once, as a busy status", () => {
+		const a11y = resolveSkeletonAccessibility({ isLoading: true, label: "Loading messages" });
+		expect(a11y.kind).toBe("status");
+		expect(a11y.props.accessible).toBe(true);
+		expect(a11y.props.accessibilityLabel).toBe("Loading messages");
+		expect(a11y.props.accessibilityRole).toBe("progressbar");
+		expect(a11y.props.accessibilityState).toEqual({ busy: true });
+	});
+
+	test("treats an empty label as no label", () => {
+		expect(resolveSkeletonAccessibility({ isLoading: true, label: "" }).kind).toBe("hidden");
+	});
+
+	// Once the content has landed it speaks for itself; the skeleton must not
+	// sit between it and a screen reader.
+	test("steps aside entirely once loaded", () => {
+		for (const label of [undefined, "Loading"]) {
+			const a11y = resolveSkeletonAccessibility({ isLoading: false, label });
+			expect(a11y.kind).toBe("content");
+			expect(a11y.props).toEqual({});
+		}
+	});
+});
+
+describe("skeletonVariants root slot", () => {
+	test("paints and clips only while loading", () => {
+		const loading = skeletonVariants({ isLoading: true }).root();
+		expect(loading).toContain(SKELETON_FILL_CLASS);
+		expect(loading).toContain("overflow-hidden");
+
+		const loaded = skeletonVariants({ isLoading: false }).root();
+		expect(loaded).not.toContain(SKELETON_FILL_CLASS);
+	});
+
+	test("gives every shape a corner", () => {
+		for (const shape of SKELETON_SHAPES) {
+			expect(skeletonVariants({ shape }).root()).toMatch(/\brounded-/);
+		}
+	});
+
+	test("draws a circle as a circle", () => {
+		expect(skeletonVariants({ shape: "circle" }).root()).toContain("rounded-full");
+	});
+
+	// With children the content sizes the placeholder, so a default size would
+	// only fight it — and would clip the content once it lands.
+	test("sizes a childless shape, and leaves a wrapping one to its content", () => {
+		for (const shape of SKELETON_SHAPES) {
+			expect(skeletonVariants({ shape, isEmpty: true }).root()).toMatch(/\b(h|size)-/);
+			expect(skeletonVariants({ shape, isEmpty: false }).root()).not.toMatch(/\b(h|w|size)-/);
+		}
+	});
+
+	test("lets a caller's size beat the shape's default", () => {
+		const cls = skeletonVariants({ shape: "circle", isEmpty: true }).root({ className: "size-16" });
+		expect(cls).toContain("size-16");
+		expect(cls).not.toContain("size-10");
+	});
+
+	test("lets a caller's corner beat the shape's", () => {
+		const cls = skeletonVariants({ shape: "rect" }).root({ className: "rounded-full" });
+		expect(cls).toContain("rounded-full");
+		expect(cls).not.toContain("rounded-lg");
+	});
+});
+
+describe("SKELETON_FILL_CLASS", () => {
+	// An opaque surface token sits too close to the light page to read. A tint
+	// of a foreground colour steps off any surface it lands on, in both themes.
+	test("is a translucent tint of a foreground colour", () => {
+		expect(SKELETON_FILL_CLASS).toMatch(/^bg-[\w-]*foreground\/\d+$/);
+	});
+});
+
+describe("skeletonVariants band slot", () => {
+	test("is pinned to the leading edge and spans the full height", () => {
+		const cls = skeletonVariants().band();
+		expect(cls).toContain("absolute");
+		expect(cls).toContain("left-0");
+		expect(cls).toContain("inset-y-0");
+	});
+
+	// A share of the placeholder, bounded both ways — and a class, so Yoga sizes
+	// it and no frame of the sweep has to write a layout prop.
+	test("takes its width from layout, as a bounded share of the placeholder", () => {
+		const cls = skeletonVariants().band();
+		expect(cls).toContain("w-3/5");
+		expect(cls).toContain("min-w-12");
+		expect(cls).toContain("max-w-60");
+	});
+});

package/src/components/skeleton/skeleton.variants.ts

@@ -0,0 +1,222 @@
+import { tv } from "../../lib/tv";
+
+export const SKELETON_SHAPES = ["rect", "line", "circle"] as const;
+export const SKELETON_ANIMATIONS = ["shimmer", "pulse", "none"] as const;
+
+export type SkeletonShape = (typeof SKELETON_SHAPES)[number];
+export type SkeletonAnimation = (typeof SKELETON_ANIMATIONS)[number];
+
+/**
+ * The placeholder's fill: the muted foreground at a fifth of its strength.
+ *
+ * Translucent on purpose. `bg-muted` sits within 0.015 lightness of the light
+ * page and vanished on it; a tint of a foreground colour instead lands a clear
+ * step off whatever surface it is on — page or card, light or dark — and still
+ * leaves room above it for the `elevated` glint.
+ */
+export const SKELETON_FILL_CLASS = "bg-muted-foreground/20";
+
+/** Animation used with no `animation` prop and nothing to inherit from. */
+export const SKELETON_FALLBACK_ANIMATION: SkeletonAnimation = "shimmer";
+
+/** One full cycle of the shared clock — a shimmer sweep, or one breath of a pulse. */
+export const SKELETON_CYCLE_MS = 1500;
+
+/** How long the content takes to fade in once it lands. */
+export const SKELETON_REVEAL_MS = 200;
+
+/**
+ * The lowest opacity a pulse dims to.
+ *
+ * Well above zero on purpose: a placeholder that blinks out of existence reads
+ * as a layout that is failing rather than one that is loading.
+ */
+export const SKELETON_PULSE_MIN_OPACITY = 0.5;
+
+/** Alpha at the centre of the shimmer band, over the `elevated` token. */
+export const SKELETON_SHIMMER_PEAK_OPACITY = 0.9;
+
+/** How far across the last line of a `Skeleton.Lines` paragraph runs. */
+export const SKELETON_LAST_LINE_WIDTH = 0.6;
+
+/** One `<Stop>` of the shimmer band's gradient. */
+export type SkeletonShimmerStop = { offset: number; opacity: number };
+
+/**
+ * The shimmer band's gradient, left to right.
+ *
+ * Transparent at both edges so the band has no visible boundary, and symmetric
+ * so it reads the same whichever way it is travelling. The quarter stops sit
+ * low rather than on a straight ramp, which keeps the highlight a soft glint
+ * instead of a triangle with a bright ridge down its middle.
+ */
+export const SKELETON_SHIMMER_STOPS: readonly SkeletonShimmerStop[] = [
+	{ offset: 0, opacity: 0 },
+	{ offset: 0.25, opacity: SKELETON_SHIMMER_PEAK_OPACITY * 0.35 },
+	{ offset: 0.5, opacity: SKELETON_SHIMMER_PEAK_OPACITY },
+	{ offset: 0.75, opacity: SKELETON_SHIMMER_PEAK_OPACITY * 0.35 },
+	{ offset: 1, opacity: 0 },
+];
+
+/**
+ * The animation a skeleton actually runs.
+ *
+ * Calm motion — the OS reduce-motion setting, or an app's `isMotionCalm` — stills
+ * every animation rather than hiding the placeholder: the shape is the message,
+ * and a shape that stops moving still reads as content on its way. The clock then
+ * never starts, which is also why the timing itself can set `ReduceMotion.Never` —
+ * see AGENTS.md.
+ */
+export function resolveSkeletonAnimation(animation: SkeletonAnimation | undefined, isCalm: boolean): SkeletonAnimation {
+	if (isCalm) return "none";
+	return animation ?? SKELETON_FALLBACK_ANIMATION;
+}
+
+/**
+ * A pulse's opacity at a point in the cycle — opaque at both ends, at the floor
+ * half way.
+ *
+ * A cosine rather than a triangle, so it eases into each turn instead of
+ * bouncing off it, and so 0 and 1 meet with no seam as the clock wraps.
+ *
+ * Marked `"worklet"` and written flat, calling nothing but `Math`, for the
+ * reason `switch.variants.ts` gives: a module-scope worklet that calls a sibling
+ * works only while that sibling happens to be declared first.
+ */
+export function skeletonPulseOpacity(progress: number): number {
+	"worklet";
+	const mid = (1 + SKELETON_PULSE_MIN_OPACITY) / 2;
+	const amplitude = (1 - SKELETON_PULSE_MIN_OPACITY) / 2;
+	return mid + amplitude * Math.cos(2 * Math.PI * progress);
+}
+
+/**
+ * Where the band's leading edge sits at a point in the sweep.
+ *
+ * Runs from wholly off the start edge to wholly off the end edge, so it enters
+ * from nothing and leaves to nothing and the wrap back to 0 is invisible.
+ * Before the placeholder is measured `width` is 0 and the band stays parked
+ * off-screen.
+ */
+export function skeletonShimmerOffset(progress: number, width: number, bandWidth: number): number {
+	"worklet";
+	return -bandWidth + (width + bandWidth) * progress;
+}
+
+/**
+ * The width of each line in a `Skeleton.Lines` paragraph.
+ *
+ * Only the last line is shortened, the way a paragraph ends — and only when
+ * there is more than one, since a single line is a title or a label whose
+ * length the caller already knows. A fractional count rounds down.
+ */
+export function resolveSkeletonLineWidths(lines: number, lastLineWidth = SKELETON_LAST_LINE_WIDTH): `${number}%`[] {
+	const count = Math.max(0, Math.floor(lines));
+	const last = Math.min(1, Math.max(0, lastLineWidth));
+
+	return Array.from({ length: count }, (_unused, index) =>
+		count > 1 && index === count - 1 ? (`${Math.round(last * 100)}%` as const) : ("100%" as const)
+	);
+}
+
+/** Accessibility props a skeleton spreads onto its root. A subset of React Native's `ViewProps`. */
+export type SkeletonAccessibilityProps = {
+	accessible?: boolean;
+	accessibilityLabel?: string;
+	accessibilityRole?: "progressbar";
+	accessibilityState?: { busy: boolean };
+	accessibilityElementsHidden?: boolean;
+	importantForAccessibility?: "no-hide-descendants";
+};
+
+/** What a skeleton is to assistive technology, and the props that make it so. */
+export type SkeletonAccessibility =
+	| { kind: "hidden"; props: SkeletonAccessibilityProps }
+	| { kind: "status"; props: SkeletonAccessibilityProps }
+	| { kind: "content"; props: SkeletonAccessibilityProps };
+
+/**
+ * How a skeleton presents to a screen reader.
+ *
+ * An unlabelled placeholder is a picture of content that is not there, so it is
+ * hidden outright — a screen of grey boxes would otherwise announce nothing
+ * worth hearing, many times over. A labelled one announces once, as a busy
+ * progress status. Once loaded the skeleton steps aside and the content speaks
+ * for itself.
+ */
+export function resolveSkeletonAccessibility({
+	label,
+	isLoading,
+}: {
+	label?: string;
+	isLoading: boolean;
+}): SkeletonAccessibility {
+	if (!isLoading) return { kind: "content", props: {} };
+
+	if (label) {
+		return {
+			kind: "status",
+			props: {
+				accessible: true,
+				accessibilityLabel: label,
+				accessibilityRole: "progressbar",
+				accessibilityState: { busy: true },
+			},
+		};
+	}
+
+	return {
+		kind: "hidden",
+		props: { accessibilityElementsHidden: true, importantForAccessibility: "no-hide-descendants" },
+	};
+}
+
+/**
+ * Styling for every part of a skeleton.
+ *
+ * `isEmpty` is whether the skeleton wraps content. A wrapping skeleton is sized
+ * by that content — rendered invisibly underneath while loading — so its shape
+ * contributes only a corner; a default height would fight the content and then
+ * clip it once it lands. A childless one needs a size of its own, and the
+ * shape supplies a sensible one that a caller's className overrides.
+ *
+ * The paint and the clip belong to the loading state alone, so the content is
+ * not left on a grey card, or cropped, once it is shown.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const skeletonVariants = tv({
+	slots: {
+		root: "",
+		content: "",
+		// Yoga sizes the band, never an animated style: 60% of the placeholder,
+		// held between 48 and 240pt so a chip still gets a visible glint and a
+		// full-bleed card does not get a wash. See `skeleton-shimmer.tsx`.
+		band: "absolute inset-y-0 left-0 w-3/5 min-w-12 max-w-60",
+	},
+	variants: {
+		shape: {
+			rect: { root: "rounded-lg" },
+			line: { root: "rounded-sm" },
+			circle: { root: "rounded-full" },
+		},
+		isLoading: {
+			true: { root: `overflow-hidden ${SKELETON_FILL_CLASS}` },
+			false: {},
+		},
+		isEmpty: {
+			true: {},
+			false: {},
+		},
+	},
+	compoundVariants: [
+		{ shape: "rect", isEmpty: true, className: { root: "h-24 w-full" } },
+		{ shape: "line", isEmpty: true, className: { root: "h-3.5 w-full" } },
+		{ shape: "circle", isEmpty: true, className: { root: "size-10" } },
+	],
+	defaultVariants: {
+		shape: "rect",
+		isLoading: true,
+		isEmpty: true,
+	},
+});

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

@@ -0,0 +1,122 @@
+# SlideButton
+
+A control confirmed by dragging a handle across a rail — "Slide to ship", "Slide
+to transfer $240". For an action that deserves deliberation where a dialog would
+be too much ceremony. Compound root plus `SlideButton.Label` and
+`SlideButton.Thumb`.
+
+`import { SlideButton } from "@delacour/react-native-ui/slide-button";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/slide-button` |
+| `slide-button.tsx` | Root, the gesture, the internal trail, and the `Object.assign` compound surface |
+| `slide-button-label.tsx` | `SlideButton.Label` |
+| `slide-button-thumb.tsx` | `SlideButton.Thumb`, and the internal chevron-to-tick glyph |
+| `slide-button.context.tsx` | `SlideButtonContext`, `useSlideButton` |
+| `slide-button.variants.ts` | The slotted `tv()`, the motion constants and the pure resolvers |
+| `slide-button.variants.test.ts` | |
+
+There is no `slide-button.types.ts`: every prop type has exactly one consumer.
+
+## Design
+
+- **Variants**: `secondary` (default), `destructive`, `success`. **Sizes**:
+  `sm`, `md`, `lg`. Plus `isFullWidth` and `isDisabled`.
+- **There is no `primary` variant.** The handle is neutral, so a primary rail
+  with a neutral handle draws the same picture as `secondary` in any theme whose
+  primary sits close to its foreground — the default palette included. Two names
+  for one look is a choice a caller cannot see the difference in.
+- **The rail is a button's box.** `h-button-*` and `rounded-button-*` at each
+  size, so a slide button stacks level with a `Button` or a progress button in
+  the same column. A test pins the classes; it names a TODO for the category
+  lead to compare against `progressButtonVariants` directly once that lands.
+- **The handle is neutral in every variant** — `bg-background` with a
+  `border-border` hairline, inset 4pt, about 1.6× as wide as it is tall. Only the
+  rail, the trail and the label carry the variant. A coloured handle on a
+  coloured trail would disappear into its own wake.
+- **The handle's width is measured, not tabulated.** `resolveSlideHandleWidth`
+  reads the rail's laid-out height, so a consumer who retunes
+  `--spacing-button-*` keeps the handle in proportion.
+- **The trail ends under the handle's middle, not at its rear edge.** A stadium's
+  rear is a curve; a trail stopping at the straight edge leaves a sliver of rail
+  above and below it. Ending under the handle reads as one shape — the handle
+  dragging its colour along — while still sharing an edge with it as seen.
+- **The trail is invisible at rest.** It fades in over the first 8pt of travel
+  (`resolveSlideTrailOpacity`). Ending under the handle's middle, it would
+  otherwise peek out behind the resting handle's rear curve — a coloured sliver
+  that makes an untouched control look half-started.
+- **The label changes colour where the trail covers it.** A second copy in the
+  trail's foreground (`labelOnTrail`) is clipped to the trail's width
+  (`resolveSlideTrailWidth`, shared with the trail). A state variant's trail is
+  its full colour, and the soft label colour on it is the same hue on the same
+  hue: the words vanished exactly where the trail reached them.
+- **The label keeps a handle's width clear on both sides**
+  (`resolveSlideLabelGutter`). Symmetric, so it stays centred; a long label
+  truncates before it runs under the resting handle.
+- **The label is centred in the whole rail and never fades or moves.** The handle
+  passes over it. A label that faded would leave the control saying nothing for
+  the second half of the gesture, the half where the hand most wants to know what
+  it is confirming.
+- **The handle tracks the finger 1:1; only the release is sprung.** Any easing on
+  the way out would make the handle lag the thumb, which reads as resistance.
+- **A release confirms on look-ahead *and* reach.** `resolveSlideRelease`
+  projects the release `velocity × 0.08s` ahead; it confirms only when that
+  projection reaches the threshold **and** the hand itself got within 0.25 of it.
+  The second condition is what stops a hard flick from halfway: the habit-driven
+  swipe this control exists to refuse.
+- **`threshold={1}` has no shortcut at all.** Only a release within half a point
+  of the far end confirms. That is the setting for something irreversible.
+- **`onComplete` fires the moment the release confirms**, alongside the handle's
+  spring to the end — not when the spring settles. A spring can be interrupted
+  (an unmount, a re-layout), and a confirmation that hung on its callback could
+  be silently lost.
+- **A requested completion holds the handle at the end.** Controlled, the release
+  reports `onCompletedChange(true)` and the handle waits at the end until
+  `isCompleted` answers. Springing back while the caller's work is in flight
+  would read as a refusal. `isCompleted` going false springs it home; true keeps
+  it there with the tick.
+- **A rejected promise takes the handle home.** `onComplete` may return a
+  promise. If it rejects, the button reports `onCompletedChange(false)` and the
+  handle springs back, so a failed request never looks confirmed and a
+  controlled caller has a way out of the pending state that does not need a
+  `true` it never meant.
+- **Disabled refuses the drag outright.** The handle does not move at all. A
+  handle that followed and sprang back would read as a failed slide rather than
+  a refused one.
+- **Disabled still claims the drag.** The pan stays enabled and every callback
+  returns early. A disabled recognizer lets the touch fall through to whatever
+  is behind it — inside a stack with a full-screen back swipe, dragging a
+  disabled slide navigated back. Found on the simulator.
+- **One `Gesture.Pan()` on the rail, `activeOffsetX ±8`, `failOffsetY ±12`.** A
+  vertical scroll that starts on the rail fails the pan first, so the control
+  survives inside a vertical `ScrollView`. A cancelled pan returns home.
+- **RTL flips with `I18nManager.isRTL`.** Every positioned part uses logical
+  insets (`start-*`), the translation and the drag are multiplied by `-1`, and
+  the chevron becomes `IconChevronLeft`.
+- **Haptics are off by default.** `haptic` names the tick played the first time
+  a drag crosses the threshold (re-armed if it drops back under); a `success`
+  knock follows on commit. Both are worklet calls, in the frame that earned them.
+- **Reduced motion keeps the travel.** Springs become a 180ms `withTiming`. The
+  handle still moves to the end: a confirmation control that showed nothing on
+  confirming would be broken.
+- **The chevron crosses into a tick** — opacity and a quarter turn, 180ms, off
+  one shared value. Children on `SlideButton.Thumb` replace both marks.
+- **Screen readers confirm with one action.** The rail is a `button` whose label
+  is the `SlideButton.Label` text (or an explicit `accessibilityLabel`), with an
+  `activate` action labelled by `accessibilityActionLabel` — default "Confirm";
+  pass an imperative that names the outcome, "Ship order". Activating moves the
+  handle to the end and fires `onComplete`. `accessibilityState` carries
+  `disabled` and `checked: isCompleted`.
+- **The thumb is drawn last however it was written**, and composed in when the
+  children hold none — `Switch`'s rule. Part detection checks `displayName` as
+  well as identity, for the reason `Switch` documents.
+
+## Out of scope
+
+- A `primary` variant — see above.
+- A vertical slide.
+- A label that changes on completion. The caller swaps the label's text from
+  `isCompleted` if they want one.

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

@@ -0,0 +1,43 @@
+export { SlideButton, type SlideButtonProps } from "./slide-button";
+export {
+	type SlideButtonContextValue,
+	SlideButtonProvider,
+	useSlideButton,
+	useSlideButtonContext,
+} from "./slide-button.context";
+export {
+	isSlideArmed,
+	resolveSlideHandleWidth,
+	resolveSlideLabelGutter,
+	resolveSlideRelease,
+	resolveSlideThreshold,
+	resolveSlideTrailOpacity,
+	resolveSlideTrailWidth,
+	resolveSlideTravel,
+	SLIDE_BUTTON_ACTIVE_OFFSET_X,
+	SLIDE_BUTTON_ARM_SLACK,
+	SLIDE_BUTTON_DEFAULT_AUTO_RESET_MS,
+	SLIDE_BUTTON_DEFAULT_SIZE,
+	SLIDE_BUTTON_DEFAULT_THRESHOLD,
+	SLIDE_BUTTON_DEFAULT_VARIANT,
+	SLIDE_BUTTON_FAIL_OFFSET_Y,
+	SLIDE_BUTTON_FAR_END_SLOP,
+	SLIDE_BUTTON_GLYPH_MS,
+	SLIDE_BUTTON_GLYPH_TOKEN,
+	SLIDE_BUTTON_HANDLE_RATIO,
+	SLIDE_BUTTON_INSET,
+	SLIDE_BUTTON_LOOKAHEAD,
+	SLIDE_BUTTON_MIN_THRESHOLD,
+	SLIDE_BUTTON_REDUCED_MOTION_MS,
+	SLIDE_BUTTON_SIZES,
+	SLIDE_BUTTON_SPRING,
+	SLIDE_BUTTON_TRAIL_FADE,
+	SLIDE_BUTTON_VARIANTS,
+	type SlideButtonSize,
+	type SlideButtonVariant,
+	type SlideButtonVariantProps,
+	type SlideRelease,
+	slideButtonVariants,
+} from "./slide-button.variants";
+export type { SlideButtonLabelProps } from "./slide-button-label";
+export type { SlideButtonThumbProps } from "./slide-button-thumb";