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

package/src/components/stack-card/stack-card.variants.ts

@@ -0,0 +1,360 @@
+import { Children, type ReactNode } from "react";
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** The four ways a card can leave the pile. */
+export const STACK_CARD_DIRECTIONS = ["left", "right", "up", "down"] as const;
+
+/**
+ * How the cards behind the top one are drawn. `stack` steps each one down and
+ * smaller, `fan` rotates them alternately about the bottom centre, `flat` hides
+ * them so only the top card shows.
+ */
+export const STACK_CARD_LAYOUTS = ["stack", "fan", "flat"] as const;
+
+/** The state colours a stamp may take — each a token declared in both themes. */
+export const STACK_CARD_STAMP_COLORS = ["primary", "success", "warning", "info", "destructive"] as const;
+
+export type StackCardDirection = (typeof STACK_CARD_DIRECTIONS)[number];
+export type StackCardLayout = (typeof STACK_CARD_LAYOUTS)[number];
+export type StackCardStampColor = (typeof STACK_CARD_STAMP_COLORS)[number];
+
+/** The directions a deck allows when it names none: a horizontal yes-or-no. */
+export const STACK_CARD_DEFAULT_DIRECTIONS: readonly StackCardDirection[] = ["left", "right"];
+
+/** What a screen reader calls each direction when the caller names none. */
+export const STACK_CARD_DEFAULT_DIRECTION_LABELS: Record<StackCardDirection, string> = {
+	down: "Swipe down",
+	left: "Swipe left",
+	right: "Swipe right",
+	up: "Swipe up",
+};
+
+/** The fraction of the card's size a drag must cover to throw it. */
+export const STACK_CARD_DEFAULT_THRESHOLD = 0.3;
+
+/** Degrees of tilt a card takes for every card-width it is dragged. */
+export const STACK_CARD_DRAG_ROTATION = 12;
+
+/** The tilt each stamp carries, by the direction it answers for. */
+export const STACK_CARD_STAMP_ROTATION: Record<StackCardDirection, number> = {
+	down: 0,
+	left: 12,
+	right: -12,
+	up: 0,
+};
+
+/**
+ * One slotted `tv()` for every part.
+ *
+ * `card` is a card's look — `bg-card border border-border rounded-lg`, the
+ * package's card-shaped surface (see the package AGENTS.md on `--radius`) —
+ * absolutely filling the pile, so every card in the deck occupies one box and a
+ * transform is the only thing that tells them apart. `stamp` is placed on the
+ * side it answers for: a right-hand "yes" sits top-start, where a card tilting
+ * right lifts it into view. The text colour lives on `stampLabel`, never on the
+ * stamp (rule 1).
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const stackCardVariants = tv({
+	slots: {
+		root: "gap-4",
+		pile: "relative flex-1",
+		card: "absolute inset-0 overflow-hidden rounded-lg border border-border bg-card",
+		stamp: "absolute rounded-md border-4 px-3 py-1",
+		stampLabel: "font-bold text-2xl uppercase tracking-widest",
+		empty: "absolute inset-0 items-center justify-center",
+		actions: "flex-row items-center justify-center gap-4",
+	},
+	variants: {
+		color: {
+			primary: { stamp: "border-primary", stampLabel: "text-primary" },
+			success: { stamp: "border-success", stampLabel: "text-success" },
+			warning: { stamp: "border-warning", stampLabel: "text-warning" },
+			info: { stamp: "border-info", stampLabel: "text-info" },
+			destructive: { stamp: "border-destructive", stampLabel: "text-destructive" },
+		},
+		direction: {
+			right: { stamp: "top-8 left-6" },
+			left: { stamp: "top-8 right-6" },
+			up: { stamp: "bottom-10 self-center" },
+			down: { stamp: "top-10 self-center" },
+		},
+	},
+	defaultVariants: {
+		color: "primary",
+		direction: "right",
+	},
+});
+
+export type StackCardVariantProps = VariantProps<typeof stackCardVariants>;
+
+/** What `partitionStackChildren` sorts a child into. */
+export type StackCardChildKind = "stamp" | "card" | "empty" | "actions";
+
+/**
+ * Sorts the root's children by part: stamps, cards in order, the empty state
+ * and the actions row.
+ *
+ * **Anything that is not a stamp, an empty state or an actions row is a card.**
+ * A caller who wraps `StackCard.Card` in a component of their own still gets a
+ * card, rather than a child silently dropped because its type is not the part's.
+ * The first `Empty` and the first `Actions` win; a second of either is ignored.
+ *
+ * `kindOf` is passed in rather than imported so this stays free of the parts it
+ * looks for, and of React Native with them.
+ */
+export function partitionStackChildren(
+	children: ReactNode,
+	kindOf: (node: ReactNode) => StackCardChildKind
+): { stamps: ReactNode[]; cards: ReactNode[]; empty: ReactNode | null; actions: ReactNode | null } {
+	const stamps: ReactNode[] = [];
+	const cards: ReactNode[] = [];
+	let empty: ReactNode | null = null;
+	let actions: ReactNode | null = null;
+
+	for (const child of Children.toArray(children)) {
+		const kind = kindOf(child);
+		if (kind === "stamp") stamps.push(child);
+		else if (kind === "empty") empty ??= child;
+		else if (kind === "actions") actions ??= child;
+		else cards.push(child);
+	}
+
+	return { actions, cards, empty, stamps };
+}
+
+/**
+ * Where a released card goes: a direction to throw it, or `null` to spring back.
+ *
+ * Momentum counts — the position is projected 0.15 s along the release velocity —
+ * so a flick throws from a short drag and a flick back toward the centre cancels
+ * a long one. Each axis is measured as a fraction of the card's own size along
+ * it, the larger fraction is the dominant axis, and that axis alone decides.
+ * A direction the deck does not allow gives `null`, as does a card not yet
+ * measured.
+ *
+ * A worklet, self-contained, so the pan's `onEnd` calls it on the UI thread.
+ */
+export function resolveStackRelease({
+	x,
+	y,
+	vx,
+	vy,
+	width,
+	height,
+	threshold,
+	directions,
+}: {
+	x: number;
+	y: number;
+	vx: number;
+	vy: number;
+	width: number;
+	height: number;
+	threshold: number;
+	directions: readonly StackCardDirection[];
+}): StackCardDirection | null {
+	"worklet";
+	if (width <= 0 || height <= 0) return null;
+	const px = x + vx * 0.15;
+	const py = y + vy * 0.15;
+	const fx = Math.abs(px) / width;
+	const fy = Math.abs(py) / height;
+	const isHorizontal = fx >= fy;
+	const fraction = isHorizontal ? fx : fy;
+	if (fraction < threshold) return null;
+	const direction: StackCardDirection = isHorizontal ? (px > 0 ? "right" : "left") : py > 0 ? "down" : "up";
+	return directions.includes(direction) ? direction : null;
+}
+
+/**
+ * The card's offset for a finger's translation.
+ *
+ * Toward an allowed direction it follows one to one. **Toward a disallowed one
+ * it still gives a quarter**, and springs back on release: a card that does not
+ * budge at all reads as frozen, where one that gives a little and returns reads
+ * as "not that way".
+ *
+ * A worklet, self-contained, so the pan's `onUpdate` calls it on the UI thread.
+ */
+export function resolveDragOffset({
+	translationX,
+	translationY,
+	directions,
+}: {
+	translationX: number;
+	translationY: number;
+	directions: readonly StackCardDirection[];
+}): { x: number; y: number } {
+	"worklet";
+	const xDirection: StackCardDirection = translationX > 0 ? "right" : "left";
+	const yDirection: StackCardDirection = translationY > 0 ? "down" : "up";
+	const x = directions.includes(xDirection) ? translationX : translationX * 0.25;
+	const y = directions.includes(yDirection) ? translationY : translationY * 0.25;
+	return { x, y };
+}
+
+/**
+ * How far the top card is toward leaving, 0 at rest and 1 at the threshold.
+ *
+ * The furthest axis, as a fraction of the card's size along it, clamped. The
+ * cards behind interpolate on this, which is what puts the next card exactly in
+ * place by the time a release can throw the top one.
+ *
+ * A worklet, self-contained.
+ */
+export function resolveDragProgress({
+	x,
+	y,
+	width,
+	height,
+	threshold,
+}: {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	threshold: number;
+}): number {
+	"worklet";
+	if (width <= 0 || height <= 0 || threshold <= 0) return 0;
+	const progress = Math.max(Math.abs(x) / (width * threshold), Math.abs(y) / (height * threshold));
+	return Math.min(1, progress);
+}
+
+/**
+ * A stamp's opacity: its progress toward its own direction, 0..1.
+ *
+ * Reaches 1 at the threshold, so a stamp at full strength means "let go and this
+ * is the answer". A stamp stays dark while the other axis is the dominant one,
+ * so a diagonal drag in a four-way deck shows one answer, not two — the same
+ * rule {@link resolveStackRelease} decides by.
+ *
+ * A worklet, self-contained.
+ */
+export function resolveStampOpacity({
+	x,
+	y,
+	width,
+	height,
+	direction,
+	threshold = 0.3,
+}: {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	direction: StackCardDirection;
+	threshold?: number;
+}): number {
+	"worklet";
+	if (width <= 0 || height <= 0 || threshold <= 0) return 0;
+	const fx = x / width;
+	const fy = y / height;
+	const isHorizontal = direction === "left" || direction === "right";
+	if (isHorizontal ? Math.abs(fy) > Math.abs(fx) : Math.abs(fx) > Math.abs(fy)) return 0;
+	const along = direction === "right" ? fx : direction === "left" ? -fx : direction === "down" ? fy : -fy;
+	return Math.min(1, Math.max(0, along / threshold));
+}
+
+/** A card's resting transform — rotation in degrees. */
+export type StackCardTransform = { translateY: number; scale: number; rotate: number; opacity: number };
+
+/**
+ * Where a card behind the top one sits, interpolated toward the slot ahead of it.
+ *
+ * `position` is how far behind the top it is (0 is the top), `progress` how far
+ * the top card is toward leaving. At `progress` 1 a card is exactly where the one
+ * ahead of it was at 0, so when the top card goes the next one is already in
+ * place and advancing moves nothing.
+ *
+ * - `stack`: `translateY = 8·i`, `scale = 1 − 0.04·i`.
+ * - `fan`: `rotate = ±3°·i`, alternating sign, about the bottom centre.
+ * - `flat`: every card behind is hidden.
+ *
+ * Positions `1..depth` are opaque; the one at `depth + 1` waits hidden and fades
+ * in as it moves up, so the deck never pops a card into view.
+ *
+ * A worklet, self-contained.
+ */
+export function resolveBehindTransform({
+	layout,
+	position,
+	progress,
+	depth,
+}: {
+	layout: StackCardLayout;
+	position: number;
+	progress: number;
+	depth: number;
+}): StackCardTransform {
+	"worklet";
+	const t = Math.min(1, Math.max(0, progress));
+	const at = (p: number): StackCardTransform => {
+		if (p <= 0) return { opacity: 1, rotate: 0, scale: 1, translateY: 0 };
+		const opacity = layout === "flat" || p > depth ? 0 : 1;
+		if (layout === "stack") return { opacity, rotate: 0, scale: 1 - 0.04 * p, translateY: 8 * p };
+		if (layout === "fan") return { opacity, rotate: (p % 2 === 1 ? 3 : -3) * p, scale: 1, translateY: 0 };
+		return { opacity, rotate: 0, scale: 1, translateY: 0 };
+	};
+	const from = at(position);
+	if (t === 0) return from;
+	const to = at(position - 1);
+	return {
+		opacity: from.opacity + (to.opacity - from.opacity) * t,
+		rotate: from.rotate + (to.rotate - from.rotate) * t,
+		scale: from.scale + (to.scale - from.scale) * t,
+		translateY: from.translateY + (to.translateY - from.translateY) * t,
+	};
+}
+
+/**
+ * Where a thrown card ends up: one and a half of its own size off in `direction`,
+ * which clears the pile at any tilt.
+ *
+ * A worklet, self-contained — the throw, an undo's fly-in and a declined card's
+ * return all start or end here.
+ */
+export function resolveExitOffset({
+	direction,
+	width,
+	height,
+}: {
+	direction: StackCardDirection;
+	width: number;
+	height: number;
+}): { x: number; y: number } {
+	"worklet";
+	if (direction === "right") return { x: width * 1.5, y: 0 };
+	if (direction === "left") return { x: -width * 1.5, y: 0 };
+	if (direction === "down") return { x: 0, y: height * 1.5 };
+	return { x: 0, y: -height * 1.5 };
+}
+
+/**
+ * The cards actually mounted, as `[from, to)`: one behind the top for undo, the
+ * top, the visible depth, and one beyond it so the next card can fade in.
+ *
+ * A deck of 500 therefore mounts what a deck of five does.
+ */
+export function resolveMountedWindow({
+	index,
+	count,
+	depth,
+}: {
+	index: number;
+	count: number;
+	depth: number;
+}): [number, number] {
+	const to = Math.max(0, Math.min(count, index + depth + 2));
+	const from = Math.max(0, Math.min(index - 1, to));
+	return [from, to];
+}
+
+/** The number of cards drawn behind the top: 2 by default, a whole number in 0..4. */
+export function resolveStackDepth(depth?: number): number {
+	if (depth === undefined || Number.isNaN(depth)) return 2;
+	return Math.min(4, Math.max(0, Math.round(depth)));
+}

package/src/components/steps/AGENTS.md

@@ -0,0 +1,153 @@
+# Steps
+
+A stepper for a multi-step flow. Compound root plus `Steps.Item`, `Steps.Indicator`,
+`Steps.Title`, `Steps.Description` and `Steps.Panel`; the connectors between steps are
+internal and drawn by the items themselves.
+
+`import { Steps } from "@delacour/react-native-ui/steps";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/steps` |
+| `steps.tsx` | Root — the value, the item count, and the `Object.assign` |
+| `steps-item.tsx` | `Steps.Item` — the outer box, the trigger (a `Pressable` or a `View`), and `splitChildren` |
+| `steps-track.tsx` | The track `[half] [circle] [half]`, and the rail beside a vertical panel — internal |
+| `steps-panel.tsx` | `Steps.Panel` — content outside the tap target |
+| `steps-indicator.tsx` | `Steps.Indicator` — the circle and its number, check, cross or spinner |
+| `steps-title.tsx` | `Steps.Title` |
+| `steps-description.tsx` | `Steps.Description` |
+| `steps-connector.tsx` | One half of the line between two steps — internal |
+| `steps.context.tsx` | The stepper's and the step's contexts, with their hooks |
+| `steps.variants.ts` | Pure `tv()` slots + every resolver, no RN imports |
+| `steps.variants.test.ts` | |
+
+## Design
+
+- **Variants**: `primary` (a completed step is solid, the current one a ring, the
+  steps ahead hollow) and `secondary` (every indicator filled — completed soft,
+  current solid, upcoming muted). **Sizes**: `sm`, `md`, `lg` — the circle's edge
+  (24/32/40), the number's type step, the glyph's icon step, the title's `Text`
+  step and the gaps, on one axis. **Orientations**: `horizontal` (titles centred
+  under the circles, equal-width columns) and `vertical` (titles beside, the line
+  running down).
+- **Three statuses, off one number.** `resolveStepStatus` reads the step's index
+  against the zero-based `value`: before it `completed`, at it `current`, after it
+  `upcoming`. A step's own `completed` overrides that — `true` wins everywhere
+  (the last step of a finished flow), `false` un-completes a passed step (a
+  skipped optional one) but never demotes the current step, which would leave a
+  stepper with nowhere the user is. `isCurrent` is kept beside the status for the
+  same reason: a completed current step is still where the user is, and it still
+  announces `selected`.
+- **Invalid and loading are flags, not statuses.** A step can be completed *and*
+  invalid (the payment failed on review), or current *and* loading. Folding them
+  into the status would make the status a list of every pair.
+  `resolveIndicatorGlyph` ranks what the circle draws: spinner over cross over
+  check over number — loading outranks invalid because a failed step being
+  retried is retrying.
+
+## The connectors are laid out, not measured
+
+- **The root counts its items and each item draws its own halves.** A horizontal
+  item is an equal `flex-1` column whose track is `[half] [circle] [half]`; the
+  line between two steps is one item's right half meeting the next item's left
+  half at the column boundary. The outer halves of the first and last steps are
+  transparent spacers, so every circle stays centred. A vertical item's track is
+  `[circle] [line]`, the line `flex-1` down whatever height the content gives it,
+  and the last step draws none. `resolveStepConnectors` is that whole decision.
+  Nothing calls `onLayout`, so a title that wraps to three lines moves nothing a
+  frame late — the failure a measured connector has on every first paint.
+- **Both halves of one line fill off the value, never off a step's status.**
+  `isConnectorComplete(step, value)` is `step < value`. Each half lives in a
+  different item and can see only its own step's `completed` override, so a line
+  coloured by status could be half filled. The value is the one thing both ends
+  agree on.
+- **The halves are square-ended.** Rounded ends meeting at the column boundary
+  pinch a two-point line visibly at every joint.
+- **Counting walks the direct children**, the way [`Tabs`](../tabs/AGENTS.md)
+  walks its panels. A `.map()` is flattened by `Children.toArray` and counts; an
+  item behind a wrapper component does not, and the root warns in development.
+  With no count every item looks like the last and no line is drawn, which is the
+  visible failure the warning names. An item also warns when its `step` falls
+  outside the count — the usual cause is one-based indices.
+- **A vertical title is padded down to sit level with its circle** — by half the
+  circle's edge less the title's line height. It is the one number derived from
+  another, and `steps.variants.test.ts` recomputes it from the slot classes, so a
+  retuned circle or title step fails the suite instead of drifting half a line.
+
+## Interaction
+
+- **Read-only is inferred from the props React already has.** A controlled
+  `value` with no `onValueChange` cannot move — a press would be thrown away —
+  so the steps render as plain `View`s and are not announced as buttons.
+  `isReadOnly` states it outright either way. `resolveStepsReadOnly` is the rule.
+- **`resolveStepInteraction` returns `static`, `pressable` or `blocked`.**
+  Blocked is still a `Pressable`, announced disabled: the step is disabled,
+  loading, or ahead of the value under `isLinear`, where the flow's own Continue
+  button is the only way forward and the steps behind stay open for going back.
+  A loading step is passed to `Pressable` as `busy` rather than `disabled`, so it
+  is announced busy, not dimmed.
+- **Re-pressing the current step does not call `onValueChange`** —
+  `shouldEmitStep`, the rule `Radio.Group` keeps.
+- **The fade lands on the circle and the content, never on the trigger.** The
+  trigger is `Pressable`'s own `Animated.View`, whose animated style writes `opacity`
+  every frame and silently overwrites an `opacity-50` class — see
+  [`Radio`](../radio/AGENTS.md). A root `isDisabled` wins over a step's own, the
+  radio group's ladder.
+
+## Accessibility
+
+- **One element per step.** The trigger is `accessible`, so the circle, title and
+  description merge into one stop. Its name is the title (the text it holds) and
+  its `accessibilityValue.text` is `resolveStepAccessibilityValue` — "Step 2 of 3,
+  completed", with ", has an error" and ", loading" appended. VoiceOver reads it
+  as "Payment, Step 2 of 3, completed". The current step is `selected`.
+- **The number does not scale with the OS text size.** The circle is a fixed
+  edge, so a scaled numeral would spill out of it, and the position it shows is
+  already in the accessibility value. The title and description scale as usual.
+- **The connectors are hidden from assistive technology**, like `Separator` —
+  they restate the status every step already announces.
+
+## Colour
+
+- **The number is a `Text` and the glyphs are SVG, and one test holds them
+  together.** The number takes its colour as a class from the `indicatorLabel`
+  slot (rule 1); the check, cross and spinner take theirs as a token through one
+  `IconDefaultsProvider`. `resolveIndicatorForeground` names the token and the
+  suite asserts, for every cell, that the slot emits `text-<that token>` and that
+  `theme.css` declares it — a drift would be a white numeral beside a black check.
+- **Every colour cell is a compound, invalid last.** `tv` emits compounds after
+  plain variants, so a plain `isInvalid` branch would lose to the status cells —
+  `radioVariants`' reason.
+- **The title follows the step; the description does not.** Upcoming titles are
+  muted, an invalid title is destructive. The description keeps `Text.Caption`'s
+  muted colour in every state: the circle and the title already say where the step
+  stands.
+- **The check and cross land with a short `ZoomIn`**, keyed by glyph so a change
+  of glyph replays it. Reduce motion is left at Reanimated's `System`, which snaps
+  it in — the state is the glyph's presence, not its motion.
+
+## The panel
+
+- **`Steps.Panel` exists because the trigger is one accessibility element.** A
+  form written inside the trigger was unreachable: `accessible` merges every
+  descendant into one VoiceOver stop, so its text field and its Continue button
+  could not be focused, and its button's tap gesture sat inside the step's own.
+  The item therefore splits its children — the indicator into the track, a panel
+  after the trigger, everything else into the text column — and a panel's
+  controls are ordinary elements that never move the stepper.
+- **A vertical panel sits beside a rail as wide as the circle**, which carries the
+  trailing line on past it, so the panel reads as part of its step and the line
+  still reaches the next circle. The gap before the next step moves from under
+  the title to under the panel; the suite pins both halves of that move.
+- **There is no "only while current".** A finished step's summary is as common a
+  panel as the current step's form, so the caller gates it on `value`.
+- **`className` styles the item's outer box; every other prop reaches the
+  trigger.** `testID`, `onPress`, `haptic` and the accessibility props all belong
+  to the thing that is pressed and announced.
+
+## What it does not do
+
+- **No `Steps.Separator`.** The connectors are derived from the count; exposing
+  them would reintroduce the dangling-line failure the count exists to prevent.

package/src/components/steps/index.ts

@@ -0,0 +1,45 @@
+export { Steps, type StepsProps } from "./steps";
+export {
+	type StepsContextValue,
+	type StepsItemContextValue,
+	StepsItemProvider,
+	StepsProvider,
+	useSteps,
+	useStepsContext,
+	useStepsItem,
+	useStepsItemContext,
+} from "./steps.context";
+export {
+	isConnectorComplete,
+	resolveIndicatorForeground,
+	resolveIndicatorGlyph,
+	resolveStepAccessibilityValue,
+	resolveStepConnectors,
+	resolveStepInteraction,
+	resolveStepStatus,
+	resolveStepsReadOnly,
+	STEP_STATUSES,
+	STEPS_DEFAULT_ORIENTATION,
+	STEPS_DEFAULT_SIZE,
+	STEPS_DEFAULT_VARIANT,
+	STEPS_DESCRIPTION_TEXT_SIZE,
+	STEPS_ORIENTATIONS,
+	STEPS_SIZES,
+	STEPS_TITLE_TEXT_SIZE,
+	STEPS_VARIANTS,
+	type StepConnectorSlot,
+	type StepIndicatorGlyph,
+	type StepInteraction,
+	type StepStatus,
+	type StepsOrientation,
+	type StepsSize,
+	type StepsVariant,
+	type StepsVariantProps,
+	shouldEmitStep,
+	stepsVariants,
+} from "./steps.variants";
+export type { StepsDescriptionProps } from "./steps-description";
+export type { StepsIndicatorChildrenProps, StepsIndicatorProps } from "./steps-indicator";
+export type { StepsItemProps } from "./steps-item";
+export type { StepsPanelProps } from "./steps-panel";
+export type { StepsTitleProps } from "./steps-title";

package/src/components/steps/steps-connector.tsx

@@ -0,0 +1,31 @@
+import type { ReactElement } from "react";
+import { View } from "react-native";
+import type { StepConnectorSlot, StepsOrientation } from "./steps.variants";
+import { stepsVariants } from "./steps.variants";
+
+export type StepsConnectorProps = {
+	slot: Exclude<StepConnectorSlot, "none">;
+	orientation: StepsOrientation;
+	isComplete: boolean;
+};
+
+/**
+ * One half of the line between two steps, or the invisible half that keeps an
+ * end indicator centred. Internal — nobody places one; see
+ * `resolveStepConnectors`.
+ *
+ * Hidden from assistive technology, like `Separator`: the line restates the
+ * status every step already announces.
+ */
+export function StepsConnector({ slot, orientation, isComplete }: StepsConnectorProps): ReactElement {
+	const slots = stepsVariants({ isConnectorComplete: isComplete, orientation });
+
+	return (
+		<View
+			accessibilityElementsHidden
+			className={slot === "spacer" ? slots.spacer() : slots.connector()}
+			importantForAccessibility="no-hide-descendants"
+		/>
+	);
+}
+StepsConnector.displayName = "DelacourUI.Steps.Connector";

package/src/components/steps/steps-description.tsx

@@ -0,0 +1,26 @@
+import type { ReactElement } from "react";
+import { Text, type TextPresetProps } from "../text";
+import { useStepsItemPart } from "./steps.context";
+import { STEPS_DESCRIPTION_TEXT_SIZE, stepsVariants } from "./steps.variants";
+
+export type StepsDescriptionProps = TextPresetProps;
+
+/**
+ * A line of supporting text under the title. Optional.
+ *
+ * Renders `Text.Caption` one size step below the title and keeps the preset's
+ * muted colour in every state — the indicator and the title already say where
+ * the step stands, and a third voice saying it would only be louder.
+ */
+export function StepsDescription({ className, size, ...props }: StepsDescriptionProps): ReactElement {
+	const item = useStepsItemPart("Steps.Description");
+
+	return (
+		<Text.Caption
+			className={stepsVariants({ orientation: item.orientation }).description({ className })}
+			size={size ?? STEPS_DESCRIPTION_TEXT_SIZE[item.size]}
+			{...props}
+		/>
+	);
+}
+StepsDescription.displayName = "DelacourUI.Steps.Description";