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

package/src/components/spinner/AGENTS.md

@@ -0,0 +1,73 @@
+# Spinner
+
+An animated loading indicator. Compound root plus `Spinner.Content`, the part
+that rotates.
+
+`import { Spinner } from "@delacour/react-native-ui/spinner";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/spinner` |
+| `spinner.tsx` | Root + the `Object.assign` compound surface |
+| `spinner-content.tsx` | `Spinner.Content`, the rotating layer |
+| `spinner-arc.tsx` | The default arc glyph |
+| `spinner.context.tsx` | `SpinnerContext`, `useSpinner()`, `useSpinnerContext()` |
+| `spinner.variants.ts` | Pure `tv()` slots + resolvers, no RN imports |
+| `spinner.variants.test.ts` | |
+
+## Design
+
+- **Sizes**: the icon scale, shared outright — `SPINNER_SIZES` *is*
+  `ICON_SIZES`, `xs`…`2xl` (14/16/18/20/24/32pt) — or an explicit number. A
+  spinner stands in for an icon, so the two must agree on what `md` means. **The root is the only sized box** — `Spinner.Content` is
+  `size-full` and the arc carries no width or height at all, because
+  react-native-svg resolves both to `'100%'` when neither is set. That
+  `size-full` is load-bearing: content-size the middle layer and the percentage
+  resolves against an indefinite parent, collapsing the glyph to zero.
+  **Colours**: `default`, `success`, `warning`, `destructive`, plus any token the
+  theme emits (`primary-foreground`, `muted-foreground`) or a literal
+  (`#EC4899`). A Tailwind palette name like `emerald-500` only resolves if some
+  utility class already pulled that variable into the build — otherwise the
+  token is unresolved and nothing is drawn. Prefer the semantic tokens.
+- **Size and colour are inherited, not passed** — through exactly one path, the
+  nearest `IconDefaultsProvider`, falling back to `md` on `foreground`. A
+  [`Button`](../button/AGENTS.md) already wraps the spinner it composes in with
+  its own icon class and variant foreground, so the spinner does **not** read
+  the button's context: a second path would recompute the same two values and
+  could drift from them. An explicit `size` or `color` always wins — the
+  precedence [`Icon`](../icon/AGENTS.md) follows.
+- **Any child is the glyph**, wrapped in a `Spinner.Content` automatically so it
+  still rotates — a custom icon or asset needs nothing but to be passed in.
+  `Spinner.Content` is the rotating layer itself, so write it out by hand only
+  when that layer needs styling.
+- **`speed` belongs to the root**, not to `Spinner.Content`. It rides the
+  spinner's context alongside the resolved size and colour, so every part of the
+  spinner turns at one rate and a caller never reaches past the root to set it:
+  `<Spinner speed={0.7}>` — 1 is one full turn per 900ms.
+- **The default glyph is drawn from SVG primitives**, not a Central Icon — the
+  set has no loader glyph. Rule 5 governs *icons*; primitives are fine.
+- **The arc's caps are `butt`, and its 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, at every size. Butt caps abut instead, and the one end that
+  wants rounding 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.
+  Do not put `strokeLinecap="round"` back.
+- **The gradient stops are angle-compensated, and run in user space.** A linear
+  gradient fades along its axis and that axis is `y`, but a point at angle θ
+  clockwise from the top sits at `y = 12 - 10·cos θ` — so two stops alone make
+  the fade stall near 3 and 9 o'clock and race through 12 and 6, and the ring
+  reads as a bright chunk beside a flat grey quadrant rather than as an even
+  comet. `spinnerArcStops` places each stop at the offset the arc actually
+  occupies at that angle while stepping the opacity evenly, which inverts the
+  skew; it is pure, so `bun test` pins the whole ladder.
+  `gradientUnits="userSpaceOnUse"` then keeps the endpoints exact, where an
+  object bounding box would leave open whether a given renderer includes the
+  stroke — which shifts both ends off 0 and 1 and clips the head and the tail.
+- **The rotation sets `ReduceMotion.Never` deliberately.** 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.

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",
+});