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

package/src/components/slider/slider-thumb.tsx

@@ -1,10 +1,12 @@
 import { type ComponentProps, type ReactElement, useCallback } from "react";
 import type { AccessibilityActionEvent, LayoutChangeEvent, ViewProps } from "react-native";
 import Animated, { useAnimatedStyle, useDerivedValue, withSpring } from "react-native-reanimated";
+import { useFieldContext } from "../field/field.context";
 import { useSliderPart } from "./slider.context";
 import {
 	formatSliderValue,
 	progressOf,
+	resolveThumbAccessibilityLabel,
 	SLIDER_THUMB_ANIMATION,
 	SLIDER_THUMB_SPRING,
 	sliderVariants,
@@ -16,6 +18,15 @@ const CONTINUOUS_ACCESSIBILITY_STEPS = 10;
 export type SliderThumbProps = Omit<ViewProps, "children" | "style"> & {
 	/** Which value this thumb drives. `0` unless the slider holds a range. */
 	index?: number;
+	/**
+	 * The name a screen reader reads before the value.
+	 *
+	 * Defaults to the enclosing `Field.Label`'s text — "Volume", or for a range
+	 * "Price range, minimum" and "Price range, maximum". Set it to name one thumb
+	 * yourself; it wins outright. A slider with no `Field` and no label here reads
+	 * only its value.
+	 */
+	accessibilityLabel?: string;
 	className?: string;
 	/**
 	 * Passed to the knob inside the capsule.
@@ -56,8 +67,21 @@ export type SliderThumbProps = Omit<ViewProps, "children" | "style"> & {
  * TalkBack read; the increment and decrement actions are what their swipe
  * gestures call. Without them a slider with no gesture on its thumb would have no
  * assistive path to its value at all.
+ *
+ * **The name comes from the `Field.Label` a row away.** The thumb is a capsule
+ * with no text, so a value alone — "40" — says nothing about what it is a value
+ * *of*. React Native has no `<label for>`, so the field's context carries the
+ * label's text down and `resolveThumbAccessibilityLabel` turns it into a name:
+ * the label itself for a lone thumb, the label plus the end it holds for a
+ * range. An `accessibilityLabel` written here wins over all of it.
  */
-export function SliderThumb({ index = 0, className, knobProps, ...props }: SliderThumbProps): ReactElement {
+export function SliderThumb({
+	index = 0,
+	accessibilityLabel,
+	className,
+	knobProps,
+	...props
+}: SliderThumbProps): ReactElement {
 	const {
 		positions,
 		trackSize,
@@ -75,6 +99,7 @@ export function SliderThumb({ index = 0, className, knobProps, ...props }: Slide
 		isDisabled,
 		updateValue,
 	} = useSliderPart("Slider.Thumb");
+	const field = useFieldContext();
 	const isVertical = orientation === "vertical";
 	const slots = sliderVariants({ color, isDisabled, isInvalid, orientation, size });
 
@@ -118,6 +143,12 @@ export function SliderThumb({ index = 0, className, knobProps, ...props }: Slide
 	const knobStyle = useAnimatedStyle(() => ({ transform: [{ scale: scale.value }] }));
 
 	const value = values[index] ?? minValue;
+	const label = resolveThumbAccessibilityLabel({
+		count: values.length,
+		index,
+		label: field?.label,
+		override: accessibilityLabel,
+	});
 	const nudge = step > 0 ? step : (maxValue - minValue) / CONTINUOUS_ACCESSIBILITY_STEPS;
 
 	const handleAccessibilityAction = useCallback(
@@ -131,6 +162,7 @@ export function SliderThumb({ index = 0, className, knobProps, ...props }: Slide
 	return (
 		<Animated.View
 			accessibilityActions={ACCESSIBILITY_ACTIONS}
+			accessibilityLabel={label}
 			accessibilityRole="adjustable"
 			accessibilityState={{ disabled: isDisabled }}
 			accessibilityValue={{

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

@@ -10,6 +10,7 @@ import {
 	nearestThumbIndex,
 	progressOf,
 	resolveSliderAxes,
+	resolveThumbAccessibilityLabel,
 	SLIDER_COLORS,
 	SLIDER_DEFAULT_COLOR,
 	SLIDER_DEFAULT_ORIENTATION,
@@ -23,6 +24,7 @@ import {
 	SLIDER_SIZES,
 	SLIDER_STEP,
 	SLIDER_THUMB_ANIMATION,
+	SLIDER_THUMB_NAMES,
 	SLIDER_THUMB_SPRING,
 	shouldTickHaptic,
 	sliderVariants,
@@ -802,3 +804,53 @@ describe("shouldTickHaptic", () => {
 		expect(shouldTickHaptic({ ...base, position: 0, lastPosition: SLIDER_HAPTIC_MIN_TRAVEL })).toBe(true);
 	});
 });
+
+describe("resolveThumbAccessibilityLabel", () => {
+	// A lone thumb *is* the control, so it takes the control's name and nothing
+	// more — "Volume", not "Volume, thumb".
+	test("names a lone thumb after the slider", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "Volume", index: 0, count: 1 })).toBe("Volume");
+	});
+
+	// Nothing to say is better than a made-up name: an unlabelled single slider
+	// falls through to the value alone, which is what the caller has to fix by
+	// wrapping it in a Field or passing a label.
+	test("names an unlabelled lone thumb nothing", () => {
+		expect(resolveThumbAccessibilityLabel({ label: null, index: 0, count: 1 })).toBeUndefined();
+		expect(resolveThumbAccessibilityLabel({ index: 0, count: 1 })).toBeUndefined();
+	});
+
+	test("tells a range's two thumbs apart by which end they hold", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "Price range", index: 0, count: 2 })).toBe("Price range, minimum");
+		expect(resolveThumbAccessibilityLabel({ label: "Price range", index: 1, count: 2 })).toBe("Price range, maximum");
+	});
+
+	// Two thumbs reading the same bare number would be indistinguishable, so a
+	// range names its ends even with no label to hang them on.
+	test("still tells an unlabelled range's thumbs apart", () => {
+		expect(resolveThumbAccessibilityLabel({ label: null, index: 0, count: 2 })).toBe(SLIDER_THUMB_NAMES.minimum);
+		expect(resolveThumbAccessibilityLabel({ label: null, index: 1, count: 2 })).toBe(SLIDER_THUMB_NAMES.maximum);
+	});
+
+	test("counts the thumbs of a range with more than two", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "Stops", index: 1, count: 3 })).toBe("Stops, 2 of 3");
+		expect(resolveThumbAccessibilityLabel({ label: null, index: 2, count: 3 })).toBe("Thumb 3 of 3");
+	});
+
+	test("lets an explicit name win over everything, even in a range", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "Price range", index: 0, count: 2, override: "Lowest price" })).toBe(
+			"Lowest price"
+		);
+		expect(resolveThumbAccessibilityLabel({ index: 0, count: 1, override: "Brightness" })).toBe("Brightness");
+	});
+
+	// An empty override is an absence, not a name — the `??`-not-`||` rule read the
+	// other way round, because a screen reader given "" reads nothing at all.
+	test("treats an empty override as no override", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "Volume", index: 0, count: 1, override: "" })).toBe("Volume");
+	});
+
+	test("ignores whitespace around the label it is handed", () => {
+		expect(resolveThumbAccessibilityLabel({ label: "  Volume ", index: 0, count: 1 })).toBe("Volume");
+	});
+});

package/src/components/slider/slider.variants.ts

@@ -167,8 +167,7 @@ export const SLIDER_RANGE_SEPARATOR = " – ";
  * wrong one.
  *
  * **The fade lands on the root**, which is a plain `View` here rather than a
- * `Pressable` — so unlike `Radio`, an `opacity-50` class on it is not overwritten
- * by an animated style writing `opacity` every frame.
+ * `Pressable`, so nothing animated shares the `opacity` property with it.
  *
  * No slot worn by a `View` carries `text-*` or `font-*`: `Slider.Output` renders
  * a `Text` preset and names a step — see {@link SLIDER_OUTPUT_TEXT_SIZE}.
@@ -604,4 +603,59 @@ export function resolveSliderAxes({ own, field }: { own?: SliderOwnAxes; field?:
 	};
 }
 
+/**
+ * What a range's thumbs are called when nothing names them.
+ *
+ * Written out once so the two ends and the counted form cannot drift apart, and
+ * so the playground and the docs can quote the same words.
+ */
+export const SLIDER_THUMB_NAMES = { minimum: "Minimum", maximum: "Maximum", thumb: "Thumb" } as const;
+
+/**
+ * The accessible name a `Slider.Thumb` announces.
+ *
+ * A thumb is a capsule with no text, so without this a screen reader reads a
+ * bare number and nothing about what it is a number *of*. The ladder is the one
+ * every prop in this package climbs: an explicit `accessibilityLabel` on the
+ * thumb wins, then the slider's name, then nothing — an empty override counts as
+ * no override, because a screen reader handed `""` reads nothing at all.
+ *
+ * A lone thumb *is* the control, so it takes the control's name unadorned. A
+ * range has to tell its two thumbs apart, so each is named for the end it holds
+ * — "Price range, minimum" — and that holds even with no name to hang it on,
+ * since two thumbs reading the same bare number are indistinguishable. Past two
+ * thumbs there are no ends to name, so they count: "Stops, 2 of 3".
+ *
+ * Pure, so the whole ladder is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveThumbAccessibilityLabel({
+	label,
+	index,
+	count,
+	override,
+}: {
+	/** The slider's own name — a `Field.Label`'s text, or nothing. */
+	label?: string | null;
+	/** Which thumb, in the order the values were given. */
+	index: number;
+	/** How many thumbs the slider holds. */
+	count: number;
+	/** An `accessibilityLabel` written on the thumb itself. */
+	override?: string;
+}): string | undefined {
+	const explicit = override?.trim();
+	if (explicit) return explicit;
+
+	const name = label?.trim() || undefined;
+	if (count <= 1) return name;
+
+	if (count === 2) {
+		const end = index === 0 ? SLIDER_THUMB_NAMES.minimum : SLIDER_THUMB_NAMES.maximum;
+		return name ? `${name}, ${end.toLowerCase()}` : end;
+	}
+
+	const position = `${index + 1} of ${count}`;
+	return name ? `${name}, ${position}` : `${SLIDER_THUMB_NAMES.thumb} ${position}`;
+}
+
 export type SliderVariantProps = VariantProps<typeof sliderVariants>;

package/src/components/stack-card/AGENTS.md

@@ -0,0 +1,169 @@
+# StackCard
+
+A pile of cards taken one at a time by **throwing the top one off**. Compound
+root plus `Card`, `Stamp`, `Empty`, `Actions` and `Action`. For a queue where
+each item gets one decision and is then gone — a review queue, flashcards,
+suggestions. It shows one card, so it is wrong for anything the reader must
+compare or skim: browsing wants a carousel, and one row's actions want a swipe
+row.
+
+`import { StackCard } from "@delacour/react-native-ui/stack-card";`
+
+```tsx
+<StackCard className="h-[460px]" onSwipe={(dir, i) => decide(people[i], dir)}>
+  <StackCard.Stamp direction="right" color="success">Yes</StackCard.Stamp>
+  <StackCard.Stamp direction="left" color="destructive">No</StackCard.Stamp>
+  {people.map((p) => <StackCard.Card key={p.id}>…</StackCard.Card>)}
+  <StackCard.Empty>All caught up</StackCard.Empty>
+  <StackCard.Actions>
+    <StackCard.Action action="left" icon={IconCrossSmall} label="Skip" />
+    <StackCard.Action action="undo" icon={IconArrowRotateCounterClockwise} />
+    <StackCard.Action action="right" icon={IconCheckmark2} label="Save" />
+  </StackCard.Actions>
+</StackCard>
+```
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/stack-card` |
+| `stack-card.tsx` | Root: partitions children, owns the pan, the throw, undo, decline, the mounted window |
+| `stack-card-slot.tsx` | Internal animated box one card sits in — reads the shared offset, places itself |
+| `stack-card-card.tsx` | `StackCard.Card` — the card's look, and the top card's accessibility actions |
+| `stack-card-stamp.tsx` | `StackCard.Stamp` — fades in with progress toward its direction |
+| `stack-card-empty.tsx` | `StackCard.Empty` |
+| `stack-card-actions.tsx` | `StackCard.Actions` — the centred row under the pile |
+| `stack-card-action.tsx` | `StackCard.Action` — a round `Button` that throws or undoes |
+| `stack-card.context.tsx` | `StackCardProvider`, `useStackCard()`, `useStackCardContext()`, `useStackCardPart()`, the slot context |
+| `stack-card.types.ts` | `StackCardHandle`, `StackCardState` — shared by the root and the context |
+| `stack-card.variants.ts` | The slotted `tv()` and every pure resolver, the gesture's worklets included — no RN imports |
+| `stack-card.variants.test.ts` | |
+
+## Axes
+
+- **`directions`**: any of `left`, `right`, `up`, `down`. Default left and right.
+- **`layout`** (the cards behind only): `stack` steps each down 8 and smaller by
+  4%; `fan` rotates them ±3° per step, alternating, about the bottom centre;
+  `flat` hides them.
+- **`depth`**: cards drawn behind the top, 0..4, default 2.
+- **`threshold`**: the fraction of the card's width (or height) a drag must
+  cover, default 0.3.
+- **Stamp `color`**: `primary`, `success`, `warning`, `info`, `destructive` —
+  each a token declared in both themes, which the test checks.
+
+## Design
+
+- **One shared value drives everything: the top card's `{x, y}`.** The top card
+  follows it and tilts `x / width · 12°`, the stamps read progress toward their
+  direction from it, and the cards behind interpolate toward the slot ahead of
+  them on the furthest progress (`resolveDragProgress`). A drag writes shared
+  values and nothing else, so **nothing re-renders during a drag** — React only
+  hears about a throw after it lands.
+- **The card behind is in place at the moment of release.** Progress reaches 1
+  at the threshold, and `resolveBehindTransform` at progress 1 is exactly the
+  transform of the slot ahead — a test asserts it for every layout. So when the
+  top card is thrown, the next card is already where the top was, and advancing
+  moves nothing. Without it the pile would jump a step on every throw.
+- **The top moves on the UI thread, ahead of React.** `top` is a shared value the
+  throw sets the frame it lands; every slot places itself from `cardIndex − top`.
+  Waiting for React to re-render the new index would leave a frame where the
+  thrown card is gone and the next one has not been promoted.
+- **Each worklet is self-contained**, and the resolvers it calls each carry
+  `"worklet"` and call no other module helper (see
+  [Pressable](../pressable/AGENTS.md) for the crash a module-scope helper
+  causes). `resolveBehindTransform`'s inner `at` is declared inside its body for
+  that reason.
+- **Release:** `resolveStackRelease` projects the position 0.15 s along the
+  release velocity, so a flick throws from a short drag and a flick back cancels
+  a long one. Each axis is measured as a fraction of the card's own size along
+  it, and the dominant axis alone decides. A direction the deck does not allow
+  gives `null` and the card springs back.
+- **A disallowed direction still gives a quarter** (`resolveDragOffset`) and
+  returns. A card that does not budge at all reads as frozen, where one that
+  gives and returns reads as "not that way".
+- **A horizontal-only deck lets vertical drags through** — `activeOffsetX` and
+  `failOffsetY`, so it sits inside a vertical `ScrollView`. Vertical-only is the
+  mirror. A deck that throws all four ways claims both axes with `minDistance`
+  and **must not be nested in a scroller** — the doc comment says so. This is
+  the opposite of `Slider`'s `minDistance(0)`: a slider must win every touch on
+  its track, a deck must give up the ones that are scrolls.
+- **A controlled deck that does not move `index` declines.** A throw calls
+  `onSwipe`, then `onIndexChange`, and records the throw as pending. The effect
+  after the next render compares: an index that moved is accepted and pushed to
+  the undo history; an index that stayed put flies the card back in from the
+  side it left. The pending record is state, not a ref, so the deck re-renders
+  and checks even when the parent's `onIndexChange` changes nothing. A confirm
+  step is built on this: decline, ask, and on "yes" call `ref.swipe(dir)` again
+  and accept it — the `controlled-decline` demo.
+- **Undo restores from the side it left.** The deck keeps a history of the
+  directions it threw; `undo` pops one, steps the index back and flies the card
+  in from that side. `onSwipe` is not called for an undo. An index changed from
+  outside (a refill) clears the history, since the cards it remembers may not be
+  the ones now in the deck.
+- **A card returns on a critically damped spring.** An underdamped return
+  overshoots rest to the other side, and the stamp for the opposite direction
+  fades in there — a card undone from the left would land flashing the
+  right-hand answer. The damping sits just above `2·√(stiffness·mass)`, so the
+  card arrives without crossing.
+- **Only a window is mounted:** `[index − 1, index + depth + 1]` —
+  one behind for undo, one beyond the visible depth so the next card fades in
+  rather than popping. A deck of 500 mounts what a deck of five does
+  (`resolveMountedWindow`). The one beyond starts at opacity 0 and reaches the
+  last visible slot's opacity at progress 1.
+- **Slots render deepest first**, so the top card draws over the ones behind and
+  the card just thrown — kept mounted for undo, hidden — draws over everything
+  when it flies back in.
+- **Every transform pivots on the bottom centre.** That is what makes `fan` fan,
+  and what makes a smaller `stack` card's lower edge peek out below the one in
+  front. The pile keeps `depth · 8` points clear under the cards in `stack` so
+  that edge is not clipped by whatever sits below.
+- **Anything that is not a `Stamp`, `Empty` or `Actions` 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 for having the wrong type
+  (`partitionStackChildren` takes the predicate as an argument to stay free of
+  the parts and of React Native).
+- **Stamps are declared once on the deck and drawn on the top card**, on the side
+  they answer for — a right-hand stamp sits top-start, tilted −12°, where a card
+  leaning right lifts it into view. A stamp stays dark while the other axis
+  dominates, so a diagonal drag in a four-way deck shows one answer, not two.
+  Their text colour is on `stampLabel`, never on the stamp (rule 1).
+- **An action's glyph takes the colour of its direction's stamp**, so the button
+  and the stamp read as one answer. `undo` is a `ghost` button; the directions
+  are `secondary`; all are `icon-lg` circles. A direction button works whether or
+  not the gesture allows that direction — a button is an explicit answer.
+- **Haptics default to `selection`**, which is a deliberate departure from the
+  package's off-by-default: the tick when a drag crosses the threshold is the
+  feedback that says "let go now", and a deck without it feels uncertain. It
+  re-arms when the drag crosses back. A throw knocks with `medium`. `haptic={false}`
+  silences both.
+
+## Reduced motion
+
+- **A card leaves by fading, not flying**, and an undone or declined card fades
+  back in at rest. Which card is on top is the information, so the swap itself
+  is kept.
+- **The pile swaps without stepping:** under reduced motion the cards behind do
+  not interpolate during a drag; they take their new places when the throw lands.
+- A short drag released returns at once rather than springing.
+
+## Accessibility
+
+- **The top card is one `accessible` element** with a custom action per allowed
+  direction — named by `directionLabels[dir]`, or "Swipe left" and so on — plus
+  "Undo" while there is a card to bring back. No role is set: it is not
+  `adjustable`, since the actions are not a value going up and down.
+- **Every card but the top is hidden** — `importantForAccessibility="no-hide-descendants"`
+  on Android, `accessibilityElementsHidden` on iOS — and takes no touches.
+- Because the top card is one element, a control inside it is not separately
+  reachable. The deck's controls belong in `StackCard.Actions`, whose buttons
+  carry the same labels.
+- Stamps are hidden from assistive technology; the actions say the same thing in
+  words.
+
+## Out of scope
+
+- A carousel or any browsing mode: one card shows, by design.
+- RTL mirroring of stamp placement — the stamps sit by physical side, because the
+  direction they answer for is physical too.
+- A render callback per card, or virtualising beyond the mounted window.

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

@@ -0,0 +1,37 @@
+export { StackCard, type StackCardProps } from "./stack-card";
+export {
+	type StackCardContextValue,
+	StackCardProvider,
+	useStackCard,
+	useStackCardContext,
+} from "./stack-card.context";
+export type { StackCardHandle, StackCardState } from "./stack-card.types";
+export {
+	partitionStackChildren,
+	resolveBehindTransform,
+	resolveDragOffset,
+	resolveDragProgress,
+	resolveExitOffset,
+	resolveMountedWindow,
+	resolveStackDepth,
+	resolveStackRelease,
+	resolveStampOpacity,
+	STACK_CARD_DEFAULT_DIRECTION_LABELS,
+	STACK_CARD_DEFAULT_DIRECTIONS,
+	STACK_CARD_DEFAULT_THRESHOLD,
+	STACK_CARD_DIRECTIONS,
+	STACK_CARD_LAYOUTS,
+	STACK_CARD_STAMP_COLORS,
+	type StackCardChildKind,
+	type StackCardDirection,
+	type StackCardLayout,
+	type StackCardStampColor,
+	type StackCardTransform,
+	type StackCardVariantProps,
+	stackCardVariants,
+} from "./stack-card.variants";
+export type { StackCardActionProps } from "./stack-card-action";
+export type { StackCardActionsProps } from "./stack-card-actions";
+export type { StackCardCardProps } from "./stack-card-card";
+export type { StackCardEmptyProps } from "./stack-card-empty";
+export type { StackCardStampProps } from "./stack-card-stamp";

package/src/components/stack-card/stack-card-action.tsx

@@ -0,0 +1,66 @@
+import { type ReactElement, useCallback } from "react";
+import { Button } from "../button";
+import { Icon, type IconComponent } from "../icon";
+import { useStackCardPart } from "./stack-card.context";
+import type { StackCardDirection } from "./stack-card.variants";
+
+export type StackCardActionProps = {
+	/** Throw the top card this way, or bring the last one back. */
+	action: StackCardDirection | "undo";
+	icon: IconComponent;
+	/**
+	 * What a screen reader calls the button. Defaults to the deck's
+	 * `directionLabels` for the direction, or "Undo".
+	 */
+	label?: string;
+	/** Called before the deck acts. */
+	onPress?: () => void;
+	className?: string;
+	testID?: string;
+};
+
+/**
+ * A round button that answers for the top card without a drag.
+ *
+ * A direction throws the card exactly as a release would — `onSwipe`, then
+ * `onIndexChange` — and `undo` brings the last one back. A direction's glyph is
+ * tinted with the colour of the stamp answering for that direction, so the
+ * button and the stamp read as one answer. `undo` is a quiet ghost button,
+ * disabled while there is nothing to bring back; the directions disable once
+ * the deck is empty.
+ */
+export function StackCardAction({
+	action,
+	icon,
+	label,
+	onPress,
+	className,
+	testID,
+}: StackCardActionProps): ReactElement {
+	const { swipe, undo, canUndo, index, count, isDisabled, labelFor, stampColors } =
+		useStackCardPart("StackCard.Action");
+	const isUndo = action === "undo";
+	const isActionDisabled = isDisabled || (isUndo ? !canUndo : index >= count);
+	const color = isUndo ? undefined : stampColors[action];
+
+	const handlePress = useCallback(() => {
+		onPress?.();
+		if (action === "undo") undo();
+		else swipe(action);
+	}, [action, onPress, swipe, undo]);
+
+	return (
+		<Button
+			accessibilityLabel={label ?? (action === "undo" ? "Undo" : labelFor(action))}
+			className={className}
+			isDisabled={isActionDisabled}
+			onPress={handlePress}
+			size="icon-lg"
+			testID={testID}
+			variant={isUndo ? "ghost" : "secondary"}
+		>
+			<Icon color={color} icon={icon} />
+		</Button>
+	);
+}
+StackCardAction.displayName = "DelacourUI.StackCard.Action";

package/src/components/stack-card/stack-card-actions.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { stackCardVariants } from "./stack-card.variants";
+
+export type StackCardActionsProps = ViewProps & {
+	className?: string;
+};
+
+/**
+ * A centred row of `StackCard.Action` buttons under the pile.
+ *
+ * Wherever it is written among the deck's children, the deck renders it below
+ * the pile, which takes the height left over.
+ */
+export function StackCardActions({ className, ...props }: StackCardActionsProps): ReactElement {
+	return <View className={stackCardVariants().actions({ className })} {...props} />;
+}
+StackCardActions.displayName = "DelacourUI.StackCard.Actions";

package/src/components/stack-card/stack-card-card.tsx

@@ -0,0 +1,71 @@
+import { type ReactElement, useCallback, useMemo } from "react";
+import { type AccessibilityActionEvent, type AccessibilityActionInfo, View, type ViewProps } from "react-native";
+import { useStackCardPart, useStackCardSlot } from "./stack-card.context";
+import { STACK_CARD_DIRECTIONS, type StackCardDirection, stackCardVariants } from "./stack-card.variants";
+
+export type StackCardCardProps = ViewProps & {
+	className?: string;
+};
+
+const UNDO_ACTION = "undo";
+
+/** The accessibility action name a direction is announced under. */
+function actionName(direction: StackCardDirection): string {
+	return `swipe-${direction}`;
+}
+
+/**
+ * One card in the deck.
+ *
+ * A card's look — the card fill, a hairline and the card corner — absolutely
+ * filling the pile, so every card occupies one box and only a transform tells
+ * them apart. Its position, tilt and opacity are the deck's, applied by the slot
+ * around it; the card itself holds no gesture.
+ *
+ * The top card is one `accessible` element whose custom actions are the deck's
+ * allowed directions — named by `directionLabels`, or "Swipe left" and so on —
+ * plus "Undo" while there is a card to bring back. A screen reader swipes the
+ * deck from the actions rotor rather than by dragging. Because the card is one
+ * element, a control inside it is not separately reachable: put the deck's
+ * controls in `StackCard.Actions`, not on the card.
+ */
+export function StackCardCard({ className, children, ...props }: StackCardCardProps): ReactElement {
+	const { directions, labelFor, swipe, undo, canUndo } = useStackCardPart("StackCard.Card");
+	const slot = useStackCardSlot();
+	const isTop = slot?.isTop ?? false;
+
+	const actions = useMemo<AccessibilityActionInfo[]>(() => {
+		const list: AccessibilityActionInfo[] = directions.map((direction) => ({
+			label: labelFor(direction),
+			name: actionName(direction),
+		}));
+		if (canUndo) list.push({ label: "Undo", name: UNDO_ACTION });
+		return list;
+	}, [canUndo, directions, labelFor]);
+
+	const handleAction = useCallback(
+		(event: AccessibilityActionEvent) => {
+			const name = event.nativeEvent.actionName;
+			if (name === UNDO_ACTION) {
+				undo();
+				return;
+			}
+			const direction = STACK_CARD_DIRECTIONS.find((candidate) => actionName(candidate) === name);
+			if (direction) swipe(direction);
+		},
+		[swipe, undo]
+	);
+
+	return (
+		<View
+			accessibilityActions={isTop ? actions : undefined}
+			accessible={isTop}
+			className={stackCardVariants().card({ className })}
+			onAccessibilityAction={isTop ? handleAction : undefined}
+			{...props}
+		>
+			{children}
+		</View>
+	);
+}
+StackCardCard.displayName = "DelacourUI.StackCard.Card";

package/src/components/stack-card/stack-card-empty.tsx

@@ -0,0 +1,30 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { Text } from "../text";
+import { stackCardVariants } from "./stack-card.variants";
+
+export type StackCardEmptyProps = ViewProps & {
+	className?: string;
+};
+
+/**
+ * What the pile shows once every card has gone — centred where the cards were.
+ *
+ * Rendered by the deck only while its index has reached the card count, so an
+ * `EmptyState` or a refill button goes here rather than behind the cards. Bare
+ * text is wrapped in a muted paragraph.
+ */
+export function StackCardEmpty({ className, children, ...props }: StackCardEmptyProps): ReactElement {
+	return (
+		<View className={stackCardVariants().empty({ className })} {...props}>
+			{typeof children === "string" ? (
+				<Text align="center" color="muted" variant="paragraph">
+					{children}
+				</Text>
+			) : (
+				children
+			)}
+		</View>
+	);
+}
+StackCardEmpty.displayName = "DelacourUI.StackCard.Empty";