@delacour/react-native-ui 0.1.0-alpha.3

package/src/components/spinner/index.ts

@@ -0,0 +1,17 @@
+export { Spinner, type SpinnerProps } from "./spinner";
+export { useSpinner } from "./spinner.context";
+export {
+	resolveSpinnerColor,
+	resolveSpinnerRootClass,
+	SPINNER_COLOR_TOKEN,
+	SPINNER_COLORS,
+	SPINNER_DURATION_MS,
+	SPINNER_FALLBACK_COLOR,
+	SPINNER_FALLBACK_SIZE_CLASS,
+	SPINNER_GLYPH_SIZE_CLASS,
+	SPINNER_SIZES,
+	type SpinnerColor,
+	type SpinnerSize,
+	spinnerVariants,
+} from "./spinner.variants";
+export type { SpinnerContentProps } from "./spinner-content";

package/src/components/spinner/spinner-arc.tsx

@@ -0,0 +1,90 @@
+import { type ReactElement, useId } from "react";
+import Svg, { Circle, Defs, LinearGradient, Path, Stop } from "react-native-svg";
+import { useSpinnerContext } from "./spinner.context";
+import {
+	SPINNER_ARC_HEAD_OPACITY,
+	SPINNER_ARC_JOINT_OPACITY,
+	SPINNER_ARC_STROKE_WIDTH,
+	SPINNER_ARC_TAIL_OPACITY,
+	spinnerArcStops,
+} from "./spinner.variants";
+
+// The ring's geometry, in viewBox units. Everything below is derived from these
+// three numbers — the paths, the gradient axis, the head cap and the viewBox —
+// so the head cannot end up drawn somewhere the stroke no longer passes.
+const CENTRE = 12;
+const RADIUS = 10;
+const TOP = CENTRE - RADIUS;
+const BOTTOM = CENTRE + RADIUS;
+
+const VIEW_BOX = `0 0 ${CENTRE * 2} ${CENTRE * 2}`;
+const LEAD_PATH = `M ${CENTRE} ${TOP} A ${RADIUS} ${RADIUS} 0 0 1 ${CENTRE} ${BOTTOM}`;
+const TAIL_PATH = `M ${CENTRE} ${BOTTOM} A ${RADIUS} ${RADIUS} 0 0 1 ${CENTRE} ${TOP}`;
+
+const LEAD_STOPS = spinnerArcStops(SPINNER_ARC_HEAD_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+const TAIL_STOPS = spinnerArcStops(SPINNER_ARC_TAIL_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+
+/**
+ * The default glyph: a ring whose stroke fades from opaque to transparent
+ * around the circle.
+ *
+ * Drawn as two half-rings because a linear gradient only fades along one axis —
+ * one alone cannot carry the stroke all the way round. Central Icons has no
+ * loader glyph, so this is drawn from SVG primitives rather than imported.
+ *
+ * It carries no width or height on purpose. react-native-svg resolves both to
+ * `'100%'` when neither is set, so the arc fills whatever box the spinner root
+ * sized — one place decides the size instead of threading a number down. The
+ * viewBox stays fixed at 24, so the stroke stays proportional at every size
+ * with no geometry to recompute.
+ *
+ * **The caps are `butt`, and the round head is a separate `Circle`.** The two
+ * half-rings share the endpoint at the bottom of the ring, where both sit at
+ * `SPINNER_ARC_JOINT_OPACITY`. Round caps there stack, and two semi-transparent
+ * discs composite to roughly 0.8 alpha — a bright dot straddling the joint,
+ * opposite the head. Butt caps abut instead, and the one endpoint that actually
+ * wants a rounded end gets a disc of its own, drawn last so it sits on top. The
+ * tail terminates fully transparent at that same point, so its flat end is
+ * invisible and needs nothing. Do not put `strokeLinecap="round"` back.
+ *
+ * **The gradients run in user space.** The viewBox is fixed and the geometry is
+ * hard-coded, so `y = TOP … BOTTOM` is exact — where an object bounding box
+ * would leave open whether a given renderer includes the stroke, which shifts
+ * both endpoints off 0 and 1 and clips the head and the tail.
+ *
+ * Reads the spinner context optionally rather than through `useSpinner`: the
+ * arc is also the fallback glyph and must not throw outside a `<Spinner>`.
+ * Outside one there is no colour to resolve, and every paint here falls back to
+ * SVG's own black.
+ */
+export function SpinnerArc(): ReactElement {
+	const spinner = useSpinnerContext();
+	const resolvedColor = spinner?.color;
+
+	// An SVG gradient is referenced by id, and ids are global to the document.
+	// React 19 emits `«r1»`-style ids, whose delimiters are invalid in `url(#…)`.
+	const id = useId().replace(/[^a-zA-Z0-9]/g, "");
+	const leadId = `spinner-lead-${id}`;
+	const tailId = `spinner-tail-${id}`;
+
+	return (
+		<Svg fill="none" viewBox={VIEW_BOX}>
+			<Defs>
+				<LinearGradient gradientUnits="userSpaceOnUse" id={leadId} x1={0} x2={0} y1={TOP} y2={BOTTOM}>
+					{LEAD_STOPS.map((stop) => (
+						<Stop key={stop.offset} offset={stop.offset} stopColor={resolvedColor} stopOpacity={stop.opacity} />
+					))}
+				</LinearGradient>
+				<LinearGradient gradientUnits="userSpaceOnUse" id={tailId} x1={0} x2={0} y1={TOP} y2={BOTTOM}>
+					{TAIL_STOPS.map((stop) => (
+						<Stop key={stop.offset} offset={stop.offset} stopColor={resolvedColor} stopOpacity={stop.opacity} />
+					))}
+				</LinearGradient>
+			</Defs>
+			<Path d={LEAD_PATH} stroke={`url(#${leadId})`} strokeLinecap="butt" strokeWidth={SPINNER_ARC_STROKE_WIDTH} />
+			<Path d={TAIL_PATH} stroke={`url(#${tailId})`} strokeLinecap="butt" strokeWidth={SPINNER_ARC_STROKE_WIDTH} />
+			<Circle cx={CENTRE} cy={TOP} fill={resolvedColor} r={SPINNER_ARC_STROKE_WIDTH / 2} />
+		</Svg>
+	);
+}
+SpinnerArc.displayName = "DelacourUI.Spinner.Arc";

package/src/components/spinner/spinner-content.tsx

@@ -0,0 +1,63 @@
+import { type ComponentProps, type ReactElement, type ReactNode, useEffect } from "react";
+import Animated, {
+	cancelAnimation,
+	Easing,
+	ReduceMotion,
+	useAnimatedStyle,
+	useSharedValue,
+	withRepeat,
+	withTiming,
+} from "react-native-reanimated";
+import { useSpinner } from "./spinner.context";
+import { SPINNER_DURATION_MS, spinnerVariants } from "./spinner.variants";
+import { SpinnerArc } from "./spinner-arc";
+
+export type SpinnerContentProps = Omit<ComponentProps<typeof Animated.View>, "children"> & {
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * The rotating layer of a spinner.
+ *
+ * This is the part that turns, so a custom glyph or asset has to sit inside one
+ * to spin. The spinner wraps a bare child in it automatically, which leaves
+ * writing it out by hand for when the rotating layer itself needs styling.
+ *
+ * Colour and speed come from the spinner's context, and it fills the root
+ * rather than taking a size — there is nothing to pass down to it.
+ */
+export function SpinnerContent({ className, style, children, ...props }: SpinnerContentProps): ReactElement {
+	const { speed } = useSpinner();
+	const angle = useSharedValue(0);
+
+	useEffect(() => {
+		angle.value = withRepeat(
+			withTiming(360, {
+				duration: SPINNER_DURATION_MS / speed,
+				easing: Easing.linear,
+				// Deliberate. Under the default `System` policy `withTiming` completes
+				// instantly while the OS reduce-motion setting is on, so `withRepeat(-1)`
+				// would spin a zero-length animation forever. A status indicator is not
+				// decorative motion — it is the only thing saying work is in flight.
+				reduceMotion: ReduceMotion.Never,
+			}),
+			-1,
+			false
+		);
+
+		// Without this the repeat outlives the unmount when a button stops loading.
+		return () => cancelAnimation(angle);
+	}, [angle, speed]);
+
+	const animatedStyle = useAnimatedStyle(() => ({
+		transform: [{ rotate: `${angle.value}deg` }],
+	}));
+
+	return (
+		<Animated.View className={spinnerVariants().content({ className })} style={[animatedStyle, style]} {...props}>
+			{children ?? <SpinnerArc />}
+		</Animated.View>
+	);
+}
+SpinnerContent.displayName = "DelacourUI.Spinner.Content";

package/src/components/spinner/spinner.context.tsx

@@ -0,0 +1,52 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+
+export type SpinnerContextValue = {
+	/** Resolved colour value, ready for an SVG stroke. */
+	color: string | undefined;
+	/** Rotation speed multiplier. 1 is one full turn per 900ms. */
+	speed: number;
+	/** Whether the spinner is showing. */
+	isLoading: boolean;
+};
+
+const SpinnerContext = createContext<SpinnerContextValue | null>(null);
+
+/**
+ * Supplies the enclosing spinner's resolved colour and speed to its subtree.
+ *
+ * Lives in its own module, importing nothing at all, so the parts the spinner
+ * renders — `Spinner.Content` and the default arc glyph — can read it without
+ * importing `./spinner`. That import would close a cycle through `spinner.tsx`,
+ * and Metro serves a partially initialised module for a cycle, leaving the
+ * context `undefined` at import time. See AGENTS.md rule 3.
+ */
+export function SpinnerProvider({
+	value,
+	children,
+}: {
+	value: SpinnerContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SpinnerContext value={value}>{children}</SpinnerContext>;
+}
+SpinnerProvider.displayName = "DelacourUI.Spinner.Provider";
+
+/** The enclosing spinner's context, or null outside a `<Spinner>`. */
+export function useSpinnerContext(): SpinnerContextValue | null {
+	return use(SpinnerContext);
+}
+
+/**
+ * Reads the enclosing spinner's resolved colour and speed.
+ *
+ * Lets a custom glyph match the spinner without either being passed down to
+ * it. Size is not here: the root sizes itself and everything under it fills. Throws outside a `<Spinner>` — use {@link useSpinnerContext}
+ * where the enclosing spinner is optional.
+ */
+export function useSpinner(): SpinnerContextValue {
+	const context = useSpinnerContext();
+	if (!context) {
+		throw new Error("useSpinner must be called inside a <Spinner>.");
+	}
+	return context;
+}

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,128 @@
+import { Children, type ComponentProps, isValidElement, type ReactElement, type ReactNode, useMemo } from "react";
+import Animated, { Easing, FadeIn, FadeOut } from "react-native-reanimated";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { IconDefaultsProvider, useIconDefaults } from "../icon";
+import { type SpinnerContextValue, SpinnerProvider } from "./spinner.context";
+import {
+	resolveSpinnerColor,
+	resolveSpinnerRootClass,
+	SPINNER_GLYPH_SIZE_CLASS,
+	type SpinnerColor,
+	type SpinnerSize,
+} from "./spinner.variants";
+import { SpinnerContent } from "./spinner-content";
+
+const ENTERING = FadeIn.duration(200).easing(Easing.out(Easing.ease));
+const EXITING = FadeOut.duration(100);
+
+export type SpinnerProps = Omit<ComponentProps<typeof Animated.View>, "children" | "style"> & {
+	/** A named size, or an edge length in points. Defaults to the enclosing component's icon size. */
+	size?: SpinnerSize | number;
+	/**
+	 * A named colour, any theme token the active theme defines
+	 * (`primary-foreground`, `muted-foreground`) or a literal (`#EC4899`).
+	 * Defaults to the enclosing component's icon colour.
+	 */
+	color?: SpinnerColor | (string & {});
+	/** Whether the spinner is shown. Fades out when flipped off. */
+	isLoading?: boolean;
+	/** Rotation speed multiplier. 1 is one full turn per 900ms. */
+	speed?: number;
+	className?: string;
+	children?: ReactNode;
+};
+
+function SpinnerRoot({
+	size,
+	color,
+	isLoading = true,
+	speed = 1,
+	className,
+	children,
+	...props
+}: SpinnerProps): ReactElement | null {
+	// One inheritance path, not two. A Button wraps its whole subtree — the
+	// spinner it composes in included — in an `IconDefaultsProvider` carrying
+	// that button's icon class and its variant's foreground, so reading the
+	// button's own context here would recompute the same two values.
+	const iconDefaults = useIconDefaults();
+
+	// A number is not a class: Tailwind's scanner is static, so a runtime
+	// `size-[40px]` is never compiled. The numeric escape hatch rides `style`.
+	const numericSize = typeof size === "number" ? size : undefined;
+
+	const rootClassName = resolveSpinnerRootClass({ className, inherited: iconDefaults?.className, size });
+	const colorToken = resolveSpinnerColor(color, iconDefaults?.color);
+	const resolvedColor = useThemeColor(colorToken);
+
+	const context = useMemo<SpinnerContextValue>(
+		() => ({ color: resolvedColor, isLoading, speed }),
+		[resolvedColor, isLoading, speed]
+	);
+
+	// A glyph composed into the spinner adopts these unless told otherwise. It
+	// fills rather than taking a step, so it matches at a numeric size too.
+	const iconContext = useMemo(() => ({ className: SPINNER_GLYPH_SIZE_CLASS, color: colorToken }), [colorToken]);
+
+	const content = useMemo(() => wrapSpinnerChildren(children), [children]);
+
+	if (!isLoading) return null;
+
+	return (
+		<SpinnerProvider value={context}>
+			<Animated.View
+				accessibilityRole="progressbar"
+				accessibilityState={{ busy: true }}
+				className={rootClassName}
+				entering={ENTERING}
+				exiting={EXITING}
+				style={numericSize === undefined ? undefined : { height: numericSize, width: numericSize }}
+				{...props}
+			>
+				<IconDefaultsProvider value={iconContext}>{content}</IconDefaultsProvider>
+			</Animated.View>
+		</SpinnerProvider>
+	);
+}
+
+/**
+ * Wraps a bare glyph in a `Spinner.Content` so it rotates.
+ *
+ * Without this, `<Spinner><Icon … /></Spinner>` would render a motionless icon:
+ * the rotation lives on `Spinner.Content`, not on the root. A caller who passes
+ * `Spinner.Content` themselves is left alone, since they own the rotation.
+ */
+function wrapSpinnerChildren(children: ReactNode): ReactNode {
+	if (children === undefined || children === null) return <SpinnerContent />;
+
+	const items = Children.toArray(children);
+	const hasContent = items.some((child) => isValidElement(child) && child.type === SpinnerContent);
+
+	return hasContent ? children : <SpinnerContent>{children}</SpinnerContent>;
+}
+
+/**
+ * An animated loading indicator, composed from parts rather than configured by
+ * flags.
+ *
+ * Size and colour are inherited, not passed. Inside a `Button` the spinner
+ * reads that button's context and comes out at its icon size in its variant's
+ * foreground; elsewhere it falls back to the nearest `IconDefaultsProvider`,
+ * then to `md` on `foreground`. An explicit `size` or `color` always wins.
+ *
+ * Any child becomes the glyph and is wrapped in a `Spinner.Content` so it still
+ * rotates, so a custom icon or asset needs nothing but to be passed in.
+ *
+ * @example
+ * <Spinner size="lg" color="success" />
+ *
+ * @example
+ * <Spinner speed={0.7}>
+ *   <Icon icon={IconArrowsRepeat} />
+ * </Spinner>
+ */
+export const Spinner = Object.assign(SpinnerRoot, {
+	/** The rotating layer. Wraps a custom glyph or asset so it spins; applied automatically. */
+	Content: SpinnerContent,
+	displayName: "DelacourUI.Spinner",
+});

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

@@ -0,0 +1,273 @@
+import { describe, expect, test } from "bun:test";
+import { ICON_SIZE_TOKENS } from "../../styles/tokens";
+import {
+	isSpinnerSize,
+	resolveSpinnerColor,
+	resolveSpinnerRootClass,
+	SPINNER_ARC_HEAD_OPACITY,
+	SPINNER_ARC_JOINT_OPACITY,
+	SPINNER_ARC_STOP_COUNT,
+	SPINNER_ARC_STROKE_WIDTH,
+	SPINNER_ARC_TAIL_OPACITY,
+	SPINNER_COLOR_TOKEN,
+	SPINNER_COLORS,
+	SPINNER_FALLBACK_SIZE_CLASS,
+	SPINNER_GLYPH_SIZE_CLASS,
+	SPINNER_SIZES,
+	spinnerArcStops,
+	spinnerVariants,
+} from "./spinner.variants";
+
+/**
+ * Position of a class string's `size-icon-*` token on the shared icon scale.
+ *
+ * Compares by step rather than by points, so a test says what it means and
+ * survives a token being retuned in `tokens.css`. `tokens.test.ts` is what
+ * keeps that array ordered.
+ */
+function iconStep(cls: string): number {
+	const token = cls.match(/\bsize-(icon-[\w-]+)\b/)?.[1];
+	return ICON_SIZE_TOKENS.indexOf(token as (typeof ICON_SIZE_TOKENS)[number]);
+}
+
+describe("isSpinnerSize", () => {
+	test("separates a named size from an edge length", () => {
+		for (const size of SPINNER_SIZES) {
+			expect(isSpinnerSize(size)).toBe(true);
+		}
+		expect(isSpinnerSize(40)).toBe(false);
+		expect(isSpinnerSize(undefined)).toBe(false);
+	});
+});
+
+describe("resolveSpinnerRootClass", () => {
+	test("centres its content whatever it is given", () => {
+		for (const size of [undefined, "sm", 40] as const) {
+			expect(resolveSpinnerRootClass({ size })).toContain("items-center");
+		}
+	});
+
+	test("falls back only when there is nothing to inherit", () => {
+		expect(resolveSpinnerRootClass({})).toContain(SPINNER_FALLBACK_SIZE_CLASS);
+	});
+
+	test("an inherited class beats the fallback", () => {
+		expect(resolveSpinnerRootClass({ inherited: "size-icon-xs" })).toContain("size-icon-xs");
+	});
+
+	test("a named size beats an inherited class", () => {
+		expect(resolveSpinnerRootClass({ inherited: "size-icon-xs", size: "lg" })).toContain("size-icon-lg");
+	});
+
+	test("a className beats a named size", () => {
+		expect(resolveSpinnerRootClass({ className: "size-7", size: "sm" })).toContain("size-7");
+	});
+
+	test("gives every named size a distinct token, increasing with it", () => {
+		const steps = SPINNER_SIZES.map((size) => iconStep(resolveSpinnerRootClass({ size })));
+		expect(steps).not.toContain(-1);
+		expect(new Set(steps).size).toBe(SPINNER_SIZES.length);
+		expect([...steps]).toEqual([...steps].sort((a, b) => a - b));
+	});
+
+	// A number is not a class. `size-[40px]` built at runtime is never scanned by
+	// Tailwind, so it would compile to nothing — the root takes a numeric size
+	// through `style` instead, and the chain steps out of the way entirely rather
+	// than leaving a losing class behind to argue with it.
+	test("a numeric size emits no size class at all", () => {
+		expect(resolveSpinnerRootClass({ size: 40 })).not.toMatch(/\bsize-/);
+		expect(resolveSpinnerRootClass({ inherited: "size-icon-sm", size: 40 })).not.toMatch(/\bsize-/);
+	});
+
+	test("carries no colour", () => {
+		for (const size of SPINNER_SIZES) {
+			expect(resolveSpinnerRootClass({ size })).not.toMatch(/\b(text|bg|border)-/);
+		}
+	});
+});
+
+describe("SPINNER_GLYPH_SIZE_CLASS", () => {
+	// A composed glyph fills the spinner rather than taking a fixed class, so it
+	// still matches at a numeric size the class scale cannot express.
+	test("fills the spinner rather than pinning a step", () => {
+		expect(SPINNER_GLYPH_SIZE_CLASS).toBe("size-full");
+	});
+});
+
+describe("resolveSpinnerColor", () => {
+	test("maps each named colour to its token", () => {
+		for (const color of SPINNER_COLORS) {
+			expect(resolveSpinnerColor(color)).toBe(SPINNER_COLOR_TOKEN[color]);
+		}
+	});
+
+	test("gives every named colour a distinct token", () => {
+		const tokens = SPINNER_COLORS.map((color) => SPINNER_COLOR_TOKEN[color]);
+		expect(new Set(tokens).size).toBe(SPINNER_COLORS.length);
+	});
+
+	test("passes a literal colour through untouched", () => {
+		expect(resolveSpinnerColor("#EC4899")).toBe("#EC4899");
+		expect(resolveSpinnerColor("rgb(236, 72, 153)")).toBe("rgb(236, 72, 153)");
+	});
+
+	test("passes an unnamed theme token through untouched", () => {
+		expect(resolveSpinnerColor("emerald-500")).toBe("emerald-500");
+		expect(resolveSpinnerColor("primary-foreground")).toBe("primary-foreground");
+	});
+
+	test("takes the inherited token when none is given", () => {
+		expect(resolveSpinnerColor(undefined, "primary-foreground")).toBe("primary-foreground");
+	});
+
+	test("maps an inherited value that happens to be a named colour", () => {
+		expect(resolveSpinnerColor(undefined, "destructive")).toBe(SPINNER_COLOR_TOKEN.destructive);
+	});
+
+	test("falls back only when there is nothing to inherit", () => {
+		expect(resolveSpinnerColor(undefined)).toBe(SPINNER_COLOR_TOKEN.default);
+	});
+
+	test("an explicit colour beats the inherited one", () => {
+		expect(resolveSpinnerColor("#EC4899", "primary-foreground")).toBe("#EC4899");
+		expect(resolveSpinnerColor("destructive", "primary-foreground")).toBe(SPINNER_COLOR_TOKEN.destructive);
+	});
+});
+
+describe("spinnerVariants root slot", () => {
+	test("centres its content and carries no colour", () => {
+		const cls = spinnerVariants().root();
+		expect(cls).toContain("items-center");
+		expect(cls).toContain("justify-center");
+		expect(cls).not.toMatch(/\b(text|bg|border)-/);
+	});
+
+	test("takes no size until it is given one", () => {
+		expect(spinnerVariants().root()).not.toMatch(/\bsize-/);
+	});
+
+	test("gives every named size a distinct token, increasing with it", () => {
+		const steps = SPINNER_SIZES.map((size) => iconStep(spinnerVariants({ size }).root()));
+		expect(steps).not.toContain(-1);
+		expect(new Set(steps).size).toBe(SPINNER_SIZES.length);
+		expect([...steps]).toEqual([...steps].sort((a, b) => a - b));
+	});
+
+	test("merges an incoming className last", () => {
+		expect(spinnerVariants().root({ className: "opacity-80" })).toContain("opacity-80");
+	});
+});
+
+describe("spinnerVariants content slot", () => {
+	// Load-bearing, not tidiness. The arc is an <Svg> with no width or height,
+	// which react-native-svg resolves to '100%'. If this layer were content-sized
+	// that percentage would resolve against an indefinite parent and the whole
+	// glyph would collapse to zero.
+	test("fills the root, so the arc has a definite box to be 100% of", () => {
+		expect(spinnerVariants().content()).toContain("size-full");
+	});
+
+	test("does not take a size of its own", () => {
+		for (const size of SPINNER_SIZES) {
+			expect(spinnerVariants({ size }).content()).toBe(spinnerVariants().content());
+		}
+	});
+
+	test("carries no colour", () => {
+		expect(spinnerVariants().content()).not.toMatch(/\b(text|bg|border)-/);
+	});
+});
+
+/** The arc's geometry, restated here so a test compares against it rather than against itself. */
+const ARC_CENTRE = 12;
+const ARC_RADIUS = 10;
+
+/**
+ * Where a gradient running from `y = 2` to `y = 22` lands on the arc, a given
+ * fraction of a half-turn clockwise from the top.
+ *
+ * This is the arc's real position — `y = 12 - 10·cos θ` — not a restatement of
+ * the resolver's formula, so the linearity test below has something independent
+ * to check against.
+ */
+function arcOffsetAtHalfTurn(turn: number): number {
+	const y = ARC_CENTRE - ARC_RADIUS * Math.cos(Math.PI * turn);
+	return (y - (ARC_CENTRE - ARC_RADIUS)) / (ARC_RADIUS * 2);
+}
+
+describe("spinnerArcStops", () => {
+	test("spans the whole gradient axis, from one endpoint to the other", () => {
+		const stops = spinnerArcStops(1, 0.55);
+		expect(stops).toHaveLength(SPINNER_ARC_STOP_COUNT + 1);
+		expect(stops.at(0)).toEqual({ offset: 0, opacity: 1 });
+		expect(stops.at(-1)).toEqual({ offset: 1, opacity: 0.55 });
+	});
+
+	test("places every stop where the arc actually is at that angle", () => {
+		const stops = spinnerArcStops(SPINNER_ARC_HEAD_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		for (const [index, stop] of stops.entries()) {
+			expect(stop.offset).toBeCloseTo(arcOffsetAtHalfTurn(index / SPINNER_ARC_STOP_COUNT), 10);
+		}
+	});
+
+	// The whole point of the resolver. A two-stop gradient dims linearly in `y`,
+	// and the arc's `y` goes as -cos θ, so the fade stalls at the sides and races
+	// through the top and bottom — a white chunk beside a flat grey quadrant.
+	test("dims by a constant step per equal turn of the arc", () => {
+		const stops = spinnerArcStops(1, 0.55);
+		const deltas = stops.slice(1).map((stop, index) => stop.opacity - (stops[index]?.opacity ?? 0));
+		for (const delta of deltas) {
+			expect(delta).toBeCloseTo(-0.45 / SPINNER_ARC_STOP_COUNT, 10);
+		}
+	});
+
+	test("advances monotonically along both axes", () => {
+		const stops = spinnerArcStops(SPINNER_ARC_TAIL_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		for (const [index, stop] of stops.slice(1).entries()) {
+			const previous = stops[index];
+			expect(previous).toBeDefined();
+			expect(stop.offset).toBeGreaterThan(previous?.offset ?? 0);
+			expect(stop.opacity).toBeGreaterThan(previous?.opacity ?? 0);
+		}
+	});
+
+	// The two half-rings are painted by separate gradients on one shared axis, so
+	// a stop ladder that differed between them would kink the fade at the joint.
+	test("gives both half-rings one offset ladder", () => {
+		const lead = spinnerArcStops(SPINNER_ARC_HEAD_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		const tail = spinnerArcStops(SPINNER_ARC_TAIL_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		expect(tail.map((stop) => stop.offset)).toEqual(lead.map((stop) => stop.offset));
+	});
+
+	// The two ramps are drawn separately but read as one. Anything other than the
+	// midpoint gives them different slopes, and the ring creases at the joint —
+	// a soft bright wedge on one side of it, even though the alpha is continuous.
+	test("carries one straight ramp across both half-rings", () => {
+		const lead = spinnerArcStops(SPINNER_ARC_HEAD_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		const tail = spinnerArcStops(SPINNER_ARC_TAIL_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		const leadStep = (SPINNER_ARC_JOINT_OPACITY - SPINNER_ARC_HEAD_OPACITY) / SPINNER_ARC_STOP_COUNT;
+		const tailStep = (SPINNER_ARC_TAIL_OPACITY - SPINNER_ARC_JOINT_OPACITY) / SPINNER_ARC_STOP_COUNT;
+
+		expect(leadStep).toBeCloseTo(tailStep, 10);
+		expect(SPINNER_ARC_JOINT_OPACITY).toBeCloseTo((SPINNER_ARC_HEAD_OPACITY + SPINNER_ARC_TAIL_OPACITY) / 2, 10);
+		expect(lead.at(-1)?.opacity).toBe(tail.at(-1)?.opacity);
+	});
+
+	// Both halves terminate at the bottom of the ring. Meeting on one value is
+	// what lets their butt caps abut without a seam — and what makes the round
+	// caps they used to carry compound into a visible dot.
+	test("brings the two half-rings to the same opacity where they meet", () => {
+		const lead = spinnerArcStops(SPINNER_ARC_HEAD_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		const tail = spinnerArcStops(SPINNER_ARC_TAIL_OPACITY, SPINNER_ARC_JOINT_OPACITY);
+		expect(lead.at(-1)?.opacity).toBe(SPINNER_ARC_JOINT_OPACITY);
+		expect(tail.at(-1)?.opacity).toBe(SPINNER_ARC_JOINT_OPACITY);
+	});
+});
+
+describe("SPINNER_ARC_STROKE_WIDTH", () => {
+	// The head cap is a circle of half this radius drawn at the top of the ring,
+	// so an over-wide stroke would clip against the viewBox rather than warn.
+	test("leaves the ring inside the 24-unit viewBox", () => {
+		expect(ARC_RADIUS + SPINNER_ARC_STROKE_WIDTH / 2).toBeLessThanOrEqual(ARC_CENTRE);
+	});
+});