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

package/src/components/skeleton/AGENTS.md

@@ -0,0 +1,120 @@
+# Skeleton
+
+A placeholder standing in for content that is still loading: a tinted shape
+with a glint sweeping across it, or a pulse, on the UI thread. Compound root plus
+`Skeleton.Group`, which synchronises the skeletons inside it, and
+`Skeleton.Lines`, a paragraph of placeholder lines.
+
+`import { Skeleton } from "@delacour/react-native-ui/skeleton";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/skeleton` |
+| `skeleton.tsx` | Root, `Skeleton.Lines` and the `Object.assign` compound surface |
+| `skeleton-group.tsx` | `Skeleton.Group` — the shared clock and loading flag |
+| `skeleton-shimmer.tsx` | The sweeping band, an internal leaf |
+| `skeleton-clock.ts` | `useSkeletonClock`, the 0 → 1 UI-thread loop both animations read |
+| `skeleton.context.tsx` | `SkeletonGroupProvider`, `useSkeletonGroup()` |
+| `skeleton.variants.ts` | Pure `tv()` slots + resolvers + worklets, no RN imports |
+| `skeleton.variants.test.ts` | |
+
+## Design
+
+- **Three shapes, and a shape is a corner plus a default size.** `rect` is a
+  card-shaped `rounded-lg` (see **Sizing** in the package doc for why a card is
+  that step), `line` is a line of text at `rounded-sm`, `circle` is an avatar at
+  `rounded-full`. A childless skeleton also takes a default size — `h-24 w-full`,
+  `h-3.5 w-full`, `size-10` — that a caller's `className` overrides, since
+  tailwind-merge sees both in one chain. The defaults exist so an unsized
+  skeleton is visible rather than a zero-height nothing.
+- **Children are the content, and they size the placeholder.** A skeleton that
+  wraps children renders them underneath at opacity 0 while loading, so the grey
+  shape is exactly the size the content will be and **nothing moves when it
+  lands**. The shape then contributes only its corner: a default height would
+  fight the content, then clip it once shown. Flip `isLoading` off and the fill
+  and the clip drop and the content fades in over `SKELETON_REVEAL_MS`. The
+  children are never unmounted between the two states, so their own state
+  survives the swap. `pointerEvents` is off on them while they are invisible —
+  an invisible button that still takes a tap is a trap.
+- **One clock drives both animations.** `useSkeletonClock` loops 0 → 1 every
+  `SKELETON_CYCLE_MS`. A shimmer reads it as the band's position
+  (`skeletonShimmerOffset`), a pulse as a point on a cosine
+  (`skeletonPulseOpacity`). That is what lets a `Skeleton.Group` hold a single
+  clock for every skeleton inside it without caring which each one draws.
+- **`Skeleton.Group` exists to keep a region in step.** Separate skeletons
+  start their clocks when they mount, so a list whose rows mount a frame apart
+  shimmers as a ripple of unrelated glints. Inside a group they read the
+  group's clock and move together, and one `isLoading` reveals the whole
+  region. A skeleton's own `isLoading` and `animation` still win over the
+  group's; it starts a clock of its own only when there is no running group
+  clock to share.
+- **The fill is a tint, `bg-muted-foreground/20`, not `bg-muted`.** `muted`
+  sits within 0.015 lightness of the light page, and a placeholder drawn in it
+  was verified on the simulator to all but vanish there. A fifth of the muted
+  foreground lands a clear step off whatever it sits on — page or card, light or
+  dark — because it is translucent, and it still leaves headroom above it for
+  the glint. `SKELETON_FILL_CLASS` names it and a test pins it to a tint.
+- **The glint is painted in `elevated`, not white.** `elevated` is the raised
+  surface in both themes — white in light, a lifted grey in dark — so it sits
+  above the tinted fill either way. White would glare on dark; a translucent
+  black would darken rather than lighten in light mode. Following the token
+  also means a pasted palette carries the glint with it. The band is
+  a react-native-svg gradient, transparent at both ends, with low quarter stops
+  so it reads as a soft glint rather than a ridge.
+- **The band sweeps from wholly off one edge to wholly off the other.**
+  `skeletonShimmerOffset(0)` is `-bandWidth`, `(1)` is the placeholder width, so
+  the band enters from nothing and leaves to nothing and the wrap back to 0 has
+  no visible jump. Its width is a share of the placeholder, bounded both ways —
+  a chip still gets a visible band and a full-bleed card does not get a wash.
+  The band is sized by Yoga from its class (`w-3/5 min-w-12 max-w-60`), and
+  both widths are read with `measure` inside the animated style, so the skeleton
+  never re-renders to animate and each frame writes only `transform` and
+  `opacity`. Until both are measured the band is transparent.
+- **The gradient is a unit viewBox stretched over an absolutely filled `Svg`.**
+  Found on the simulator: an `Svg` at `width="100%"` kept its first size when
+  the band resized, so when raising `Skeleton.Lines`' count turned the old last
+  line into a full one, that line's glint sat off-centre and swept visibly out
+  of step with the rest. `StyleSheet.absoluteFill` plus
+  `preserveAspectRatio="none"` makes the native view follow the band.
+- **Calm motion stills the skeleton, it does not hide it.**
+  `resolveSkeletonAnimation` returns `none` while `useCalmMotion()` is true — the
+  OS reduce-motion setting, or `DelacourProvider`'s `isMotionCalm` — and the
+  clock is never started. The second half is for E2E builds: a test runner that
+  waits for the screen to settle before each gesture pays its whole timeout on a
+  screen holding a shimmer that never ends. The shape is the message: a placeholder that stops
+  moving still reads as content on its way. The clock's own timing sets
+  `ReduceMotion.Never` because the decision has already been made one level up —
+  under the default `System` policy `withTiming` completes instantly and
+  `withRepeat(-1)` would spin a zero-length animation forever, the trap
+  [Spinner](../spinner/AGENTS.md) documents too.
+- **The pulse owns `opacity`.** Its animated style goes after the caller's
+  `style`, so an `opacity` passed there has no effect while it pulses. The floor
+  is `SKELETON_PULSE_MIN_OPACITY`, well above zero — a placeholder that blinks
+  out reads as a failing layout, not a loading one.
+- **Hidden from assistive technology unless labelled.** An unlabelled grey box
+  announces nothing worth hearing, and a screen of them announces it many times
+  over, so the default is `accessibilityElementsHidden` plus
+  `importantForAccessibility="no-hide-descendants"`. A `label` turns the
+  skeleton into one busy `progressbar` status. Label the one that stands for the
+  region — or the `Skeleton.Group`, or the `Skeleton.Lines` paragraph — never
+  each line. Once loaded the skeleton contributes no accessibility props at all
+  and the content speaks for itself. `resolveSkeletonAccessibility` returns a
+  discriminated union (`hidden` / `status` / `content`) so the three cases are
+  pinned in `bun test`.
+- **An unlabelled group takes no role.** It may hold real content beside its
+  placeholders, and hiding the group would hide that too; each skeleton already
+  hides itself.
+- **`Skeleton.Lines` lives in the root file.** It renders `SkeletonRoot`
+  directly, and a file of its own would have to import `./skeleton` and close a
+  cycle (package rule 3). Only the last line is shortened, and only with two or
+  more — a single line is a title whose length the caller already knows. Its
+  line keys are positional because lines never reorder. **Outside a group it is
+  a `Skeleton.Group` of its own.** Found on the simulator: with a clock per line,
+  a line added by raising `lines` started from zero and glinted out of step with
+  the rest. Inside a group it is a plain container, since the group's clock
+  already serves every line.
+- **A number is not a class here either.** An arbitrary height like `h-[200px]`
+  only exists once Tailwind has scanned it; pass a computed dimension through
+  `style`, which the root spreads before the pulse.

package/src/components/skeleton/index.ts

@@ -0,0 +1,15 @@
+export { Skeleton, type SkeletonLinesProps, type SkeletonProps } from "./skeleton";
+export { type SkeletonGroupContextValue, useSkeletonGroup } from "./skeleton.context";
+export {
+	resolveSkeletonAccessibility,
+	resolveSkeletonAnimation,
+	resolveSkeletonLineWidths,
+	SKELETON_ANIMATIONS,
+	SKELETON_CYCLE_MS,
+	SKELETON_SHAPES,
+	type SkeletonAccessibility,
+	type SkeletonAnimation,
+	type SkeletonShape,
+	skeletonVariants,
+} from "./skeleton.variants";
+export type { SkeletonGroupProps } from "./skeleton-group";

package/src/components/skeleton/skeleton-clock.ts

@@ -0,0 +1,48 @@
+import { useEffect } from "react";
+import {
+	cancelAnimation,
+	Easing,
+	ReduceMotion,
+	type SharedValue,
+	useSharedValue,
+	withRepeat,
+	withTiming,
+} from "react-native-reanimated";
+import { SKELETON_CYCLE_MS } from "./skeleton.variants";
+
+/**
+ * A 0 → 1 clock that loops on the UI thread while `isRunning`.
+ *
+ * Both animations read the same clock — a shimmer as the band's position, a
+ * pulse as a point on a cosine — which is what lets a `Skeleton.Group` hold one
+ * for every placeholder inside it, whatever each of them draws.
+ *
+ * The timing sets `ReduceMotion.Never` deliberately. Under the default
+ * `System` policy `withTiming` completes instantly while the OS setting is on,
+ * so `withRepeat(-1)` would spin a zero-length animation forever. Reduce-motion
+ * is honoured one level up instead, where `resolveSkeletonAnimation` stills the
+ * skeleton and this clock is never started.
+ */
+export function useSkeletonClock(isRunning: boolean): SharedValue<number> {
+	const progress = useSharedValue(0);
+
+	useEffect(() => {
+		if (!isRunning) {
+			cancelAnimation(progress);
+			progress.value = 0;
+			return;
+		}
+
+		progress.value = 0;
+		progress.value = withRepeat(
+			withTiming(1, { duration: SKELETON_CYCLE_MS, easing: Easing.linear, reduceMotion: ReduceMotion.Never }),
+			-1,
+			false
+		);
+
+		// Without this the repeat outlives the unmount when the content lands.
+		return () => cancelAnimation(progress);
+	}, [isRunning, progress]);
+
+	return progress;
+}

package/src/components/skeleton/skeleton-group.tsx

@@ -0,0 +1,64 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
+import { cn } from "../../lib/cn";
+import { type SkeletonGroupContextValue, SkeletonGroupProvider } from "./skeleton.context";
+import { resolveSkeletonAccessibility, resolveSkeletonAnimation, type SkeletonAnimation } from "./skeleton.variants";
+import { useSkeletonClock } from "./skeleton-clock";
+
+export type SkeletonGroupProps = Omit<ViewProps, "children"> & {
+	/** Whether the group's content is still loading. Every skeleton inside follows it unless told otherwise. Defaults to `true`. */
+	isLoading?: boolean;
+	/** The animation every skeleton inside runs unless it names its own. Defaults to `shimmer`. */
+	animation?: SkeletonAnimation;
+	/**
+	 * What is loading, for a screen reader. Announced once for the whole group, as
+	 * a busy status, while it loads. Leave the skeletons inside unlabelled.
+	 */
+	label?: string;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * Holds one clock for every skeleton inside it, and one loading flag.
+ *
+ * Separate placeholders each start their own clock when they mount, so a list
+ * whose rows arrive a frame apart shimmers out of step — a ripple of unrelated
+ * glints instead of one sweep. Inside a group they all read this clock, so they
+ * move together, and flipping one `isLoading` reveals the whole region at once.
+ *
+ * It lays nothing out; it is a plain `View` for the caller to arrange.
+ */
+export function SkeletonGroup({
+	isLoading = true,
+	animation,
+	label,
+	className,
+	children,
+	...props
+}: SkeletonGroupProps): ReactElement {
+	const isCalm = useCalmMotion();
+	const resolvedAnimation = resolveSkeletonAnimation(animation, isCalm);
+	const isRunning = isLoading && resolvedAnimation !== "none";
+	const progress = useSkeletonClock(isRunning);
+
+	const context = useMemo<SkeletonGroupContextValue>(
+		() => ({ animation: resolvedAnimation, isLoading, isRunning, progress }),
+		[resolvedAnimation, isLoading, isRunning, progress]
+	);
+
+	// Only a labelled group takes a role. An unlabelled one may hold real
+	// content beside its placeholders, and hiding it would hide that too — each
+	// skeleton already hides itself.
+	const accessibility = label ? resolveSkeletonAccessibility({ isLoading, label }).props : undefined;
+
+	return (
+		<SkeletonGroupProvider value={context}>
+			<View className={cn(className)} {...accessibility} {...props}>
+				{children}
+			</View>
+		</SkeletonGroupProvider>
+	);
+}
+SkeletonGroup.displayName = "DelacourUI.Skeleton.Group";

package/src/components/skeleton/skeleton-shimmer.tsx

@@ -0,0 +1,80 @@
+import { type ReactElement, useId } from "react";
+import { StyleSheet } from "react-native";
+import Animated, {
+	type AnimatedRef,
+	measure,
+	type SharedValue,
+	useAnimatedRef,
+	useAnimatedStyle,
+} from "react-native-reanimated";
+import Svg, { Defs, LinearGradient, Rect, Stop } from "react-native-svg";
+import { useThemeColor } from "../../hooks/use-theme-color";
+import { SKELETON_SHIMMER_STOPS, skeletonShimmerOffset, skeletonVariants } from "./skeleton.variants";
+
+/** The token the band is painted in — a surface that rises above the placeholder fill in both themes. */
+const SHIMMER_TOKEN = "elevated";
+
+/**
+ * The glint that sweeps across a loading skeleton.
+ *
+ * A band as tall as the skeleton and 60% as wide — bounded to 48–240pt by its
+ * class — carried from off one edge to off the other by the clock. The root clips
+ * it, so a circle's glint stays inside the circle.
+ *
+ * Painted in `elevated` rather than white or a translucent black. That token is
+ * the raised surface in both themes — white in light, a lifted grey in dark —
+ * so it lands above the skeleton's tinted fill either way, reads as a
+ * highlight, and follows a pasted palette with no support from here.
+ *
+ * Everything runs on the UI thread, so a skeleton never re-renders to animate.
+ */
+export function SkeletonShimmer({
+	progress,
+	container,
+}: {
+	progress: SharedValue<number>;
+	container: AnimatedRef<Animated.View>;
+}): ReactElement {
+	const color = useThemeColor(SHIMMER_TOKEN);
+	const band = useAnimatedRef<Animated.View>();
+
+	// Gradient ids are global to the document, and React 19's `«r1»`-style ids
+	// carry delimiters that are invalid inside `url(#…)`.
+	const id = `skeleton-shimmer-${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
+
+	// Both widths are measured on the UI thread, so the sweep always uses the
+	// layout as it is now and nothing round-trips through JavaScript. Only
+	// `transform` and `opacity` are written, so every frame takes Reanimated's
+	// fast path and never commits layout; Yoga sizes the band from its class.
+	const motionStyle = useAnimatedStyle(() => {
+		const outer = measure(container);
+		const inner = measure(band);
+		if (!outer || !inner) return { opacity: 0, transform: [{ translateX: 0 }] };
+
+		return {
+			opacity: 1,
+			transform: [{ translateX: skeletonShimmerOffset(progress.value, outer.width, inner.width) }],
+		};
+	});
+
+	// The gradient is drawn in a unit viewBox stretched over an absolutely
+	// filled Svg, never at `width="100%"`. On the simulator a percentage-sized
+	// Svg kept its first size when the band resized — the last line of a
+	// paragraph becoming a full one — so its bright centre sat off the band's
+	// centre and the line glinted out of step with its neighbours.
+	return (
+		<Animated.View className={skeletonVariants().band()} pointerEvents="none" ref={band} style={motionStyle}>
+			<Svg preserveAspectRatio="none" style={StyleSheet.absoluteFill} viewBox="0 0 1 1">
+				<Defs>
+					<LinearGradient id={id} x1="0" x2="1" y1="0" y2="0">
+						{SKELETON_SHIMMER_STOPS.map((stop) => (
+							<Stop key={stop.offset} offset={stop.offset} stopColor={color} stopOpacity={stop.opacity} />
+						))}
+					</LinearGradient>
+				</Defs>
+				<Rect fill={`url(#${id})`} height={1} width={1} x={0} y={0} />
+			</Svg>
+		</Animated.View>
+	);
+}
+SkeletonShimmer.displayName = "DelacourUI.Skeleton.Shimmer";

package/src/components/skeleton/skeleton.context.tsx

@@ -0,0 +1,45 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+import type { SharedValue } from "react-native-reanimated";
+import type { SkeletonAnimation } from "./skeleton.variants";
+
+export type SkeletonGroupContextValue = {
+	/** The group's clock, 0 → 1 once per cycle. Only meaningful while `isRunning`. */
+	progress: SharedValue<number>;
+	/** Whether the clock is ticking — the group is loading and has an animation to run. */
+	isRunning: boolean;
+	/** The animation the group resolved, reduce-motion already applied. */
+	animation: SkeletonAnimation;
+	/** Whether the group's content is still loading. */
+	isLoading: boolean;
+};
+
+const SkeletonGroupContext = createContext<SkeletonGroupContextValue | null>(null);
+
+/**
+ * Supplies a `Skeleton.Group`'s clock and loading state to every skeleton in
+ * its subtree.
+ *
+ * Lives in its own module, importing nothing but React and types, so the root
+ * and the group can both read it without importing each other. See AGENTS.md
+ * rule 3.
+ */
+export function SkeletonGroupProvider({
+	value,
+	children,
+}: {
+	value: SkeletonGroupContextValue;
+	children: ReactNode;
+}): ReactElement {
+	return <SkeletonGroupContext value={value}>{children}</SkeletonGroupContext>;
+}
+SkeletonGroupProvider.displayName = "DelacourUI.Skeleton.GroupProvider";
+
+/**
+ * The enclosing `Skeleton.Group`, or null outside one.
+ *
+ * Optional by design: a skeleton is complete on its own, and a group only
+ * synchronises the ones it holds.
+ */
+export function useSkeletonGroup(): SkeletonGroupContextValue | null {
+	return use(SkeletonGroupContext);
+}

package/src/components/skeleton/skeleton.tsx

@@ -0,0 +1,227 @@
+import { type ReactElement, type ReactNode, useEffect } from "react";
+import { View, type ViewProps } from "react-native";
+import Animated, { useAnimatedRef, useAnimatedStyle, useSharedValue, withTiming } from "react-native-reanimated";
+import { useCalmMotion } from "../../hooks/use-calm-motion";
+import { cn } from "../../lib/cn";
+import { useSkeletonGroup } from "./skeleton.context";
+import {
+	resolveSkeletonAccessibility,
+	resolveSkeletonAnimation,
+	resolveSkeletonLineWidths,
+	SKELETON_REVEAL_MS,
+	type SkeletonAnimation,
+	type SkeletonShape,
+	skeletonPulseOpacity,
+	skeletonVariants,
+} from "./skeleton.variants";
+import { useSkeletonClock } from "./skeleton-clock";
+import { SkeletonGroup } from "./skeleton-group";
+import { SkeletonShimmer } from "./skeleton-shimmer";
+
+export type SkeletonProps = Omit<ViewProps, "children"> & {
+	/** `rect` (a card or an image), `line` (a line of text) or `circle` (an avatar). Defaults to `rect`. */
+	shape?: SkeletonShape;
+	/**
+	 * `shimmer` sweeps a glint across the placeholder, `pulse` breathes its
+	 * opacity, `none` holds it still. Inherited from an enclosing `Skeleton.Group`,
+	 * then `shimmer`. Every animation stills under the OS reduce-motion setting, and under `DelacourProvider`'s `isMotionCalm`.
+	 */
+	animation?: SkeletonAnimation;
+	/**
+	 * Whether the content is still loading. Inherited from an enclosing
+	 * `Skeleton.Group`, then `true`. Flipped off, the placeholder gives way to its
+	 * children, which fade in.
+	 */
+	isLoading?: boolean;
+	/**
+	 * What is loading, for a screen reader. Setting it makes this skeleton
+	 * announce as a busy status; leaving it unset keeps the placeholder out of the
+	 * accessibility tree. Label the one skeleton standing for a region, not all of them.
+	 */
+	label?: string;
+	className?: string;
+	/**
+	 * The real content. Rendered invisibly underneath while loading, so the
+	 * placeholder takes its exact size and nothing moves when it lands.
+	 */
+	children?: ReactNode;
+};
+
+function SkeletonRoot({
+	shape = "rect",
+	animation,
+	isLoading,
+	label,
+	className,
+	style,
+	children,
+	...props
+}: SkeletonProps): ReactElement {
+	const group = useSkeletonGroup();
+	const isCalm = useCalmMotion();
+
+	const loading = isLoading ?? group?.isLoading ?? true;
+	const resolvedAnimation = resolveSkeletonAnimation(animation ?? group?.animation, isCalm);
+	const isAnimating = loading && resolvedAnimation !== "none";
+
+	// One clock drives either animation, so a group's clock serves every
+	// skeleton inside it whatever each of them draws. A skeleton starts its own
+	// only when there is no running group clock to share.
+	const groupClock = group?.isRunning ? group.progress : undefined;
+	const ownClock = useSkeletonClock(isAnimating && groupClock === undefined);
+	const progress = groupClock ?? ownClock;
+
+	const root = useAnimatedRef<Animated.View>();
+	const reveal = useSharedValue(loading ? 0 : 1);
+
+	useEffect(() => {
+		// Hidden at once when loading starts again; faded in when it stops. The
+		// default reduce-motion policy makes the fade instant under that setting.
+		reveal.value = loading ? 0 : withTiming(1, { duration: SKELETON_REVEAL_MS });
+	}, [loading, reveal]);
+
+	const isPulsing = isAnimating && resolvedAnimation === "pulse";
+
+	const pulseStyle = useAnimatedStyle(() => ({
+		opacity: isPulsing ? skeletonPulseOpacity(progress.value) : 1,
+	}));
+
+	const revealStyle = useAnimatedStyle(() => ({ opacity: reveal.value }));
+
+	const hasChildren = children !== undefined && children !== null && children !== false;
+	const slots = skeletonVariants({ isEmpty: !hasChildren, isLoading: loading, shape });
+	const accessibility = resolveSkeletonAccessibility({ isLoading: loading, label });
+
+	// The pulse owns opacity, so its style goes after the caller's.
+	return (
+		<Animated.View
+			className={slots.root({ className })}
+			ref={root}
+			style={[style, pulseStyle]}
+			{...accessibility.props}
+			{...props}
+		>
+			{hasChildren ? (
+				<Animated.View className={slots.content()} pointerEvents={loading ? "none" : "auto"} style={revealStyle}>
+					{children}
+				</Animated.View>
+			) : null}
+			{isAnimating && resolvedAnimation === "shimmer" ? <SkeletonShimmer container={root} progress={progress} /> : null}
+		</Animated.View>
+	);
+}
+
+export type SkeletonLinesProps = Omit<SkeletonProps, "shape" | "children" | "style"> & {
+	/** How many lines to draw. Defaults to 3. */
+	lines?: number;
+	/** How far across the last line runs, 0–1. Only applies with two or more lines. Defaults to 0.6. */
+	lastLineWidth?: number;
+	/** Classes for each line — a height to match the text it stands in for, say. */
+	lineClassName?: string;
+	/** The paragraph itself, shown in place of the lines once loaded. */
+	children?: ReactNode;
+};
+
+/**
+ * A paragraph of placeholder lines, the last one shortened the way prose ends.
+ *
+ * Lives in the root file because it composes `SkeletonRoot` directly — a file of
+ * its own would have to import `./skeleton` and close a cycle. Its lines read
+ * the enclosing group's clock, or one the paragraph holds itself when there is
+ * no group, so they always glint in step. The label goes on the paragraph,
+ * never on each line.
+ */
+function SkeletonLines({
+	lines = 3,
+	lastLineWidth,
+	lineClassName,
+	animation,
+	isLoading,
+	label,
+	className,
+	children,
+	...props
+}: SkeletonLinesProps): ReactElement {
+	const group = useSkeletonGroup();
+	const loading = isLoading ?? group?.isLoading ?? true;
+
+	if (!loading) {
+		return (
+			<View className={className} {...props}>
+				{children}
+			</View>
+		);
+	}
+
+	const widths = resolveSkeletonLineWidths(lines, lastLineWidth);
+	const containerClassName = cn("w-full gap-2", className);
+
+	// Lines are positional and never reorder, so the index is their identity.
+	const content = widths.map((width, index) => (
+		<SkeletonRoot
+			animation={animation}
+			className={lineClassName}
+			isLoading
+			key={`line-${index.toString()}`}
+			shape="line"
+			style={{ width }}
+		/>
+	));
+
+	// Inside a group the lines already share its clock, so the paragraph is a
+	// plain container. Alone, it becomes a group of its own — otherwise a line
+	// added later starts a clock of its own and glints out of step with the rest.
+	if (group) {
+		const accessibility = resolveSkeletonAccessibility({ isLoading: true, label });
+		return (
+			<View className={containerClassName} {...accessibility.props} {...props}>
+				{content}
+			</View>
+		);
+	}
+
+	return (
+		<SkeletonGroup animation={animation} className={containerClassName} label={label} {...props}>
+			{content}
+		</SkeletonGroup>
+	);
+}
+SkeletonLines.displayName = "DelacourUI.Skeleton.Lines";
+
+/**
+ * A placeholder standing in for content that is still loading.
+ *
+ * Drawn as a tinted shape — `rect`, `line` or `circle` — with a glint of
+ * `elevated` sweeping across it on the UI thread, or a pulse of its opacity.
+ * Under the OS reduce-motion setting it holds still: the shape is the message.
+ *
+ * Give it the size of the content it replaces, or pass that content as children
+ * and let it take the size itself — the content is rendered invisibly
+ * underneath, so nothing moves when `isLoading` flips off and it fades in.
+ *
+ * Hidden from screen readers unless given a `label`; label the one skeleton
+ * that stands for a region and leave the rest silent.
+ *
+ * @example
+ * <View className="flex-row items-center gap-3">
+ *   <Skeleton shape="circle" />
+ *   <Skeleton.Lines className="flex-1" lines={2} />
+ * </View>
+ *
+ * @example
+ * <Skeleton isLoading={!user} shape="circle">
+ *   <Avatar user={user} />
+ * </Skeleton>
+ *
+ * @example
+ * <Skeleton.Group isLoading={isFetching} label="Loading inbox">
+ *   {rows.map((row) => <Row key={row.id} row={row} />)}
+ * </Skeleton.Group>
+ */
+export const Skeleton = Object.assign(SkeletonRoot, {
+	/** One clock and one loading flag for every skeleton inside — they shimmer in step and reveal together. */
+	Group: SkeletonGroup,
+	/** A paragraph of placeholder lines, the last one shortened. */
+	Lines: SkeletonLines,
+	displayName: "DelacourUI.Skeleton",
+});