panelui-native 0.97.0 → 0.98.0

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

@@ -0,0 +1,1423 @@
+/**
+ * StackCard — a pile of cards, taken one at a time by throwing the top one off.
+ *
+ * ```tsx
+ * <StackCard className="h-[460px]" onSwipe={(direction, index) => decide(people[index], direction)}>
+ *   <StackCard.Stamp direction="right" color="success">Yes</StackCard.Stamp>
+ *   <StackCard.Stamp direction="left" color="destructive">No</StackCard.Stamp>
+ *   {people.map((person) => (
+ *     <StackCard.Card key={person.id}>
+ *       <Text>{person.name}</Text>
+ *     </StackCard.Card>
+ *   ))}
+ *   <StackCard.Empty>
+ *     <Text muted>Nobody left</Text>
+ *   </StackCard.Empty>
+ * </StackCard>
+ * ```
+ *
+ * For a queue of things each answered with one decision and then gone: a
+ * review queue, a set of flashcards, an inbox of suggestions. The gesture is
+ * the answer, which is what makes it quicker than a list of rows with buttons
+ * on them — and what makes it wrong for anything the reader has to compare,
+ * skim or come back to. A deck shows one card and hides the rest.
+ *
+ * For a run of slides the reader browses rather than disposes of, use
+ * [Carousel](../carousel); for one row's actions in a list, [Swipe](../swipe).
+ *
+ * ## The pile is one drag, read by everything
+ *
+ * The top card's `x` and `y` are the only values a gesture writes, and every
+ * other moving part is derived from them: each stamp fades in on how far the
+ * drag has carried the card toward its own direction, and the cards behind
+ * climb toward the top position on the furthest of those.
+ *
+ * That derivation is also what makes a dismissal seamless. By the time the top
+ * card has been carried far enough to leave, the second card is already
+ * exactly where the top card sits — so when the deck advances there is nothing
+ * left for it to move, and no frame in which the pile re-arranges itself.
+ *
+ * ## The deck moves on the UI thread, and React catches up
+ *
+ * Which card is on top is held twice: as React state, for what is mounted and
+ * for the callbacks, and as a shared value, for what is drawn. A throw is
+ * handled entirely on the UI thread — the card leaves on the frame the finger
+ * lets go, and once it is off the screen the top card, the offset and the fade
+ * all move in one step — and only then is the new index requested from React.
+ *
+ * Nothing on the screen waits for a render, so a busy JavaScript thread cannot
+ * stall a throw or leave a frame where the two halves disagree. What React
+ * renders afterwards is kept from showing before the UI thread agrees with it:
+ * a stamp is only drawn on the card the UI thread has on top.
+ *
+ * A controlled deck is still the owner's to decide. An owner that declines the
+ * new index gets the card back, flown in from the way it went; one that
+ * accepts it sees nothing move at all, because it already has.
+ *
+ * One card behind the pile's stated depth stays mounted so it can fade in as
+ * it takes the last visible place, and one card ahead of the top stays mounted
+ * so `undo` has something to fly back in. The rest are unmounted, which is
+ * what makes a deck of five hundred cost what a deck of five costs.
+ *
+ * ## A deck is not reachable by a gesture alone
+ *
+ * A throw is not available to a screen reader, and neither is a card that can
+ * only be answered by throwing it. So the top card publishes an accessibility
+ * action for every direction the deck accepts, and `StackCard.Action` renders
+ * the same decisions as ordinary buttons — which sighted people reach for too,
+ * on the card they are not sure about.
+ */
+import {
+  Children,
+  cloneElement,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useReducer,
+  useRef,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  View,
+  type AccessibilityActionEvent,
+  type LayoutChangeEvent,
+  type ViewProps,
+} from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, {
+  cancelAnimation,
+  Easing,
+  interpolate,
+  runOnJS,
+  runOnUI,
+  useAnimatedReaction,
+  useAnimatedStyle,
+  useDerivedValue,
+  useReducedMotion,
+  useSharedValue,
+  withSpring,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+import { useCSSVariable } from 'uniwind';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { IconColorProvider } from '../../icons';
+import { AnimatedPressable } from '../../primitives/animated-pressable';
+import { useControllableState } from '../../primitives/controllable-state';
+import { Text } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+import { impactKnock, selectionTick } from '../../utils/haptics';
+import {
+  depthOpacity,
+  directionProgress,
+  effectiveDepth,
+  exitDuration,
+  exitTarget,
+  lever,
+  releaseProgress,
+  releasedDirection,
+  resist,
+  tiltAngle,
+  type StackCardDirection,
+} from './stack-card-geometry';
+
+export type { StackCardDirection } from './stack-card-geometry';
+
+/** Puts a card back when the release did not send it anywhere. */
+const RETURN_SPRING = { damping: 20, stiffness: 220, mass: 0.7 } as const;
+
+/**
+ * Brings an undone card back in. Heavier than the one that recovers a drag: a
+ * card arriving from off the screen has further to travel and nothing under
+ * the finger to explain a fast stop.
+ */
+const ARRIVE_SPRING = { damping: 22, stiffness: 160, mass: 0.9 } as const;
+
+/*
+ * How a card leaves: a gentle ease-out that starts twice as fast as its
+ * average, timed so that start is the finger's speed.
+ *
+ * Not a spring. A spring pulls in proportion to how far it has to go, and a
+ * card's destination is off the screen, so it accelerated away from the finger
+ * and was gone in about 100ms — a throw that read as the card being snatched.
+ *
+ * Gentle, because only the first part of the curve is seen. The card is aimed
+ * well past the edge so it clears it tilted, and it is out of sight about two
+ * thirds of the way there; a steeper curve spends most of its time on the
+ * part nobody sees. The durations are set for what is visible — roughly a
+ * quarter of a second of card crossing the screen.
+ */
+const EXIT_EASE = Easing.bezier(0.33, 0.66, 0.4, 1);
+/** `EXIT_EASE`'s speed at its start, as a multiple of its average. */
+const EXIT_SLOPE = 2;
+/** The quickest a card may leave, however hard it was thrown, in milliseconds. */
+const EXIT_SHORTEST = 420;
+/** The longest a card takes to leave, and what a button's card takes. */
+const EXIT_LONGEST = 540;
+
+/** How long a fade stands in for a throw under reduce motion. */
+const FADE_DURATION = 160;
+
+/** How far a finger gets on an axis the deck does not accept, at most. */
+const LOCKED_AXIS_GIVE = 0.18;
+
+/*
+ * The default, out here rather than in the destructure. A literal in the
+ * parameter list is a new array on every render, and this one is a dependency
+ * of the pan gesture — so it would rebuild the gesture, and re-attach the
+ * handler, while a finger was still down on it.
+ */
+const SIDEWAYS: StackCardDirection[] = ['left', 'right'];
+
+/** Degrees the top card turns through at most. */
+const MAX_TILT = 14;
+
+/** How much lower each card behind the top one sits, in points. */
+const PEEK = 14;
+
+/** How much smaller each card behind the top one is drawn. */
+const SHRINK = 0.055;
+
+/** Degrees a fanned card is turned per place back in the pile. */
+const FAN_TILT = 4;
+
+/** Sideways splay of a fanned card per place back, in points. */
+const FAN_SPREAD = 10;
+
+/** Card sizes to fall back on before the pile has been measured. */
+const UNMEASURED_WIDTH = 320;
+const UNMEASURED_HEIGHT = 420;
+
+/* -------------------------------------------------------------------------- */
+/* Context                                                                    */
+/* -------------------------------------------------------------------------- */
+
+interface StackCardContextValue {
+  /** The top card's offset. Written only by the pan and the exit animation. */
+  x: SharedValue<number>;
+  y: SharedValue<number>;
+  /** The top card's opacity, which only reduce motion ever moves. */
+  fade: SharedValue<number>;
+  /** Which way the top card pivots, from where it was taken hold of. */
+  pivot: SharedValue<number>;
+  /** The furthest any accepted direction has been carried, 0 to 1. */
+  release: SharedValue<number>;
+  /** Which card is on top, as the UI thread draws it. */
+  active: SharedValue<number>;
+  width: SharedValue<number>;
+  height: SharedValue<number>;
+  threshold: number;
+  /** Where the deck is in React, which is what a caller reads. */
+  index: number;
+  count: number;
+  disabled: boolean;
+  canUndo: boolean;
+  send: (direction: StackCardDirection) => void;
+  undo: () => void;
+  reset: () => void;
+}
+
+const StackCardContext = createContext<StackCardContextValue | null>(null);
+
+/*
+ * Which card a stamp is drawn on.
+ *
+ * Stamps are handed to whichever card React has on top, and straight after a
+ * throw React is a render behind the UI thread — so for that render they sit
+ * on the next card while the offset still says the last one went all the way.
+ * A stamp reads it to show only on the card the UI thread is drawing on top.
+ */
+const StackCardSlotIndex = createContext<number | null>(null);
+
+function useStackCardContext(component: string) {
+  const context = useContext(StackCardContext);
+  if (!context) throw new Error(`${component} must be used within a <StackCard>`);
+  return context;
+}
+
+/**
+ * The deck's state, for a control that lives outside the pile — a counter, a
+ * progress bar, a button in a toolbar.
+ *
+ * `release` is a shared value running 0 to 1 as the top card is carried toward
+ * leaving, so something beside the deck can move with the drag rather than
+ * starting a second animation next to it.
+ */
+export function useStackCard() {
+  const { index, count, canUndo, release, send, undo, reset } =
+    useStackCardContext('useStackCard');
+  return {
+    /** How many cards have been answered, which is also the top card's index. */
+    index,
+    /** How many cards the deck was given. */
+    count,
+    /** How many are left, the top one included. */
+    remaining: Math.max(0, count - index),
+    /** Whether there is a card to bring back. */
+    canUndo,
+    release,
+    send,
+    undo,
+    reset,
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Root                                                                       */
+/* -------------------------------------------------------------------------- */
+
+/** How the cards behind the top one are arranged. */
+export type StackCardLayout = 'stack' | 'fan' | 'flat';
+
+export interface StackCardHandle {
+  /** Send the top card away as though it had been thrown that way. */
+  swipe: (direction: StackCardDirection) => void;
+  /** Bring the last card back, and with it the decision that removed it. */
+  undo: () => void;
+  /** Put every card back. */
+  reset: () => void;
+}
+
+const stackCardVariants = tv({
+  slots: {
+    root: 'w-full',
+    /*
+     * The cards are laid over each other, so the pile has no height of its
+     * own and takes what is left after anything else in the root. That is what
+     * lets a caller state one height for the whole control and get a row of
+     * buttons under a pile that fills the rest.
+     */
+    pile: 'relative w-full flex-1',
+    card: 'absolute inset-0',
+  },
+});
+
+export interface StackCardProps extends Omit<ViewProps, 'children'> {
+  /**
+   * A `StackCard.Card` for each card, plus any of `StackCard.Stamp`,
+   * `StackCard.Empty` and `StackCard.Actions`, in any order. Anything else is
+   * laid out under the pile.
+   */
+  children?: ReactNode;
+  /**
+   * Which card is on top, when the caller holds it. Leave unset to let the
+   * deck keep its own. A controlled deck that declines a request stays where
+   * it is and the thrown card comes back, so this is also how a decision is
+   * confirmed before it is taken.
+   */
+  index?: number;
+  /** Which card an uncontrolled deck starts on. */
+  defaultIndex?: number;
+  /** Fires whenever the deck asks to move, with the index it is asking for. */
+  onIndexChange?: (index: number) => void;
+  /**
+   * Fires when a card leaves, with the way it went and the index it was at.
+   * It fires before `onIndexChange` asks for the next index. Not called by
+   * `undo` — the index going back is what reports that.
+   */
+  onSwipe?: (direction: StackCardDirection, index: number) => void;
+  /** Fires once when the last card leaves. */
+  onEmpty?: () => void;
+  /**
+   * Which ways a card may be thrown. Left and right by default.
+   *
+   * A direction left out still follows the finger a little and then comes
+   * back, rather than refusing to move at all — a card that does not budge
+   * reads as a frozen screen.
+   */
+  directions?: readonly StackCardDirection[];
+  /**
+   * How the cards behind the top one are arranged. `stack` steps them down and
+   * back; `fan` turns them alternately, like a hand of cards; `flat` hides them
+   * entirely, for full-bleed cards where a peeking edge is only clutter.
+   */
+  layout?: StackCardLayout;
+  /** How many cards are drawn behind the top one. Two is a pile; five is a mess. */
+  depth?: number;
+  /**
+   * How far a card has to be taken for a release to send it away, as a
+   * fraction of the card. Momentum counts toward it, so a flick clears it
+   * without travelling.
+   */
+  threshold?: number;
+  /** Stop the deck taking a gesture, without changing how it looks. */
+  disabled?: boolean;
+  /** A tick when a drag first reaches the point of no return, and a knock as the card goes. */
+  haptics?: boolean;
+  /**
+   * What a screen reader is offered for each direction, in place of "Swipe
+   * left". Name the decision — `{ left: 'Skip', right: 'Save' }`.
+   */
+  directionLabels?: Partial<Record<StackCardDirection, string>>;
+  /** Classes for the whole control. Give it a height; the pile fills what is left. */
+  className?: string;
+  /** Classes for the box the cards are laid out in. */
+  pileClassName?: string;
+}
+
+const StackCardRoot = forwardRef<StackCardHandle, StackCardProps>(
+  (
+    {
+      children,
+      index: indexProp,
+      defaultIndex = 0,
+      onIndexChange,
+      onSwipe,
+      onEmpty,
+      directions = SIDEWAYS,
+      layout = 'stack',
+      depth = 2,
+      threshold = 0.3,
+      disabled = false,
+      haptics = true,
+      directionLabels,
+      className,
+      pileClassName,
+      ...props
+    },
+    ref
+  ) => {
+    const cards: ReactElement[] = [];
+    const stamps: ReactElement[] = [];
+    let empty: ReactNode = null;
+    const below: ReactNode[] = [];
+    for (const child of Children.toArray(children)) {
+      if (!isValidElement(child)) continue;
+      if (child.type === StackCardCard) cards.push(child);
+      else if (child.type === StackCardStamp) stamps.push(child);
+      else if (child.type === StackCardEmpty) empty = child;
+      else below.push(child);
+    }
+    const count = cards.length;
+
+    const { value: index, setValue: setIndex } = useControllableState({
+      value: indexProp,
+      defaultValue: defaultIndex,
+      onChange: onIndexChange,
+    });
+
+    const x = useSharedValue(0);
+    const y = useSharedValue(0);
+    const fade = useSharedValue(1);
+    const pivot = useSharedValue(1);
+    const active = useSharedValue(index);
+    const width = useSharedValue(0);
+    const height = useSharedValue(0);
+    const reduceMotion = useReducedMotion();
+
+    /*
+     * The accepted directions as one stable array, keyed on what is in it
+     * rather than on the identity of the prop.
+     *
+     * A caller writing `directions={['left', 'right']}` hands over a new array
+     * on every render, and the whole drag path hangs off this value: the
+     * gesture that reads it, the axis constraint built from it, and the
+     * accessibility actions published from it. Keyed on contents, all three
+     * are rebuilt when the directions genuinely change and at no other time.
+     *
+     * A plain array rather than a shared value, because a worklet may capture
+     * one directly — which is how every other gesture in the library reaches
+     * its configuration, and it costs no per-frame allocation across the
+     * bridge. The gesture is rebuilt when the contents change, which is also
+     * exactly when the axis constraint below has to be rebuilt anyway.
+     */
+    const directionKey = directions.join('');
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const allowed = useMemo(() => [...directions], [directionKey]);
+
+    const release = useDerivedValue(
+      () => releaseProgress(allowed, x.value, y.value, width.value, height.value, threshold),
+      [allowed, threshold]
+    );
+
+    /*
+     * Which way each answered card went, so `undo` can put one back out where
+     * it came from before bringing it in. A ref rather than state: nothing is
+     * rendered from it, and a decision recorded at the end of an animation
+     * must not schedule a render of its own.
+     */
+    const history = useRef<StackCardDirection[]>([]);
+    /** Set when a card should arrive rather than simply appear. */
+    const arriving = useRef<StackCardDirection | null>(null);
+    const reportedEmpty = useRef(false);
+
+    /**
+     * The card the UI thread is drawing on top, as far as this side knows. It
+     * runs ahead of `index` for the length of one render after every throw.
+     */
+    const drawn = useRef(index);
+    /** The throw React has been asked to accept, until the next render answers. */
+    const requested = useRef<{ from: number; direction: StackCardDirection } | null>(null);
+    /*
+     * Guarantees that render. An owner declining a request need not render at
+     * all, and without one the deck would never find out it had been declined.
+     */
+    const [, answer] = useReducer((renders: number) => renders + 1, 0);
+
+    /** A card is on its way out. One at a time, whoever asked. */
+    const leaving = useSharedValue(false);
+    /** Where the drag picked the card up, so it carries on from there. */
+    const originX = useSharedValue(0);
+    const originY = useSharedValue(0);
+
+    useEffect(
+      () => () => {
+        cancelAnimation(x);
+        cancelAnimation(y);
+        cancelAnimation(fade);
+      },
+      [fade, x, y]
+    );
+
+    /*
+     * Puts the deck at `next` in a single step on the UI thread: which card is
+     * on top, where the offset is, and whether it is showing.
+     *
+     * All of it in one worklet, because these are three shared values that
+     * the pile reads together. Written one at a time from React, each lands
+     * whenever the UI thread picks it up — and a frame that has the offset
+     * back at the middle while the old card is still the top one draws that
+     * card back in the middle of the screen, for as long as the gap lasts.
+     */
+    const settle = useCallback(
+      (next: number, fromX: number, fromY: number, arrive: boolean) => {
+        'worklet';
+        cancelAnimation(x);
+        cancelAnimation(y);
+        cancelAnimation(fade);
+        leaving.value = false;
+        active.value = next;
+        fade.value = 1;
+        if (!arrive) {
+          x.value = 0;
+          y.value = 0;
+          return;
+        }
+        x.value = fromX;
+        y.value = fromY;
+        x.value = withSpring(0, ARRIVE_SPRING);
+        y.value = withSpring(0, ARRIVE_SPRING);
+      },
+      [active, fade, leaving, x, y]
+    );
+
+    /*
+     * React catching up with the deck, after every render.
+     *
+     * A thrown card moves the deck on the UI thread before React hears about
+     * it, so by the time this runs an accepted throw has nothing left to do.
+     * What it handles is everything that did not start as a throw — `undo`,
+     * `reset`, an owner moving `index` — and a throw that was declined, which
+     * is already off the screen and has to be brought back the way it went.
+     */
+    useEffect(() => {
+      const asked = requested.current;
+      requested.current = null;
+      if (asked && index === asked.from) {
+        history.current.pop();
+        arriving.current = asked.direction;
+      }
+
+      if (drawn.current === index) return;
+      drawn.current = index;
+
+      const entrance = arriving.current;
+      arriving.current = null;
+      if (!entrance || reduceMotion) {
+        runOnUI(settle)(index, 0, 0, false);
+        return;
+      }
+
+      const from = exitTarget(
+        entrance,
+        width.value || UNMEASURED_WIDTH,
+        height.value || UNMEASURED_HEIGHT,
+        0,
+        0
+      );
+      runOnUI(settle)(index, from.x, from.y, true);
+    });
+
+    useEffect(() => {
+      if (index >= count && count > 0 && !reportedEmpty.current) {
+        reportedEmpty.current = true;
+        onEmpty?.();
+        return;
+      }
+      if (index < count) reportedEmpty.current = false;
+    }, [count, index, onEmpty]);
+
+    /*
+     * Runs once the outgoing card is off the screen, and the deck has already
+     * moved on. `onSwipe` goes first, so an owner deciding whether to accept
+     * the index has already heard which way the card went.
+     */
+    const requestNext = useCallback(
+      (direction: StackCardDirection, from: number) => {
+        drawn.current = from + 1;
+        requested.current = { from, direction };
+        history.current.push(direction);
+        onSwipe?.(direction, from);
+        setIndex(from + 1);
+        answer();
+        if (haptics) impactKnock();
+      },
+      [haptics, onSwipe, setIndex]
+    );
+
+    /*
+     * `requestNext` closes over the caller's `onSwipe`, which an owner passing
+     * an inline arrow makes a new function on every render. The throw below is
+     * part of the gesture, so reaching it through a ref is what lets the
+     * gesture be built once and keep the touch it already has.
+     */
+    const latestRequestNext = useRef(requestNext);
+    latestRequestNext.current = requestNext;
+    const reportGone = useCallback((direction: StackCardDirection, from: number) => {
+      latestRequestNext.current(direction, from);
+    }, []);
+
+    /*
+     * Sends the top card off, on the UI thread, whoever asked.
+     *
+     * A release calls this from inside the gesture, so the card keeps moving
+     * on the frame the finger lets go rather than waiting for the JavaScript
+     * thread to hear about it — which, in a development build or on a busy
+     * screen, was long enough to see the card stop and set off again, and
+     * long enough for a second finger to catch the card that had just left.
+     *
+     * A thrown card leaves at the speed the finger let go of it, and a card
+     * sent by a button at the pace of an unhurried throw. Both finish with the
+     * card clear of the screen, and the axis it leaves along decides when.
+     */
+    const launch = useCallback(
+      (direction: StackCardDirection, velocityX: number, velocityY: number) => {
+        'worklet';
+        const from = active.value;
+        if (leaving.value || from >= count) return;
+        leaving.value = true;
+
+        const gone = (finished?: boolean) => {
+          'worklet';
+          // Caught mid-flight: the finger has it now, and the deck has not moved.
+          if (!finished) {
+            leaving.value = false;
+            return;
+          }
+          settle(from + 1, 0, 0, false);
+          runOnJS(reportGone)(direction, from);
+        };
+
+        if (reduceMotion) {
+          // The throw is the part that moves, and moving is the part the
+          // setting is about. The card still goes; it goes by fading.
+          fade.value = withTiming(0, { duration: FADE_DURATION }, gone);
+          return;
+        }
+
+        const target = exitTarget(
+          direction,
+          width.value || UNMEASURED_WIDTH,
+          height.value || UNMEASURED_HEIGHT,
+          x.value,
+          y.value
+        );
+        const sideways = direction === 'left' || direction === 'right';
+        const distance = sideways ? target.x - x.value : target.y - y.value;
+        const along = sideways ? velocityX : velocityY;
+        // Only speed toward the way out counts; a card flicked back the other
+        // way and sent on by distance is leaving from a standstill.
+        const speed = along * distance > 0 ? Math.abs(along) : 0;
+        const timing = {
+          duration: exitDuration(distance, speed, EXIT_SLOPE, EXIT_SHORTEST, EXIT_LONGEST),
+          easing: EXIT_EASE,
+        };
+        x.value = withTiming(target.x, timing, sideways ? gone : undefined);
+        y.value = withTiming(target.y, timing, sideways ? undefined : gone);
+      },
+      [active, count, fade, height, leaving, reduceMotion, reportGone, settle, width, x, y]
+    );
+
+    const send = useCallback(
+      (direction: StackCardDirection) => {
+        runOnUI(launch)(direction, 0, 0);
+      },
+      [launch]
+    );
+
+    const undo = useCallback(() => {
+      // `drawn`, not `index`: straight after a throw React is a render behind.
+      const current = drawn.current;
+      if (current <= 0) return;
+      arriving.current = history.current.pop() ?? 'left';
+      setIndex(current - 1);
+    }, [setIndex]);
+
+    const reset = useCallback(() => {
+      history.current = [];
+      arriving.current = null;
+      requested.current = null;
+      drawn.current = 0;
+      runOnUI(settle)(0, 0, 0, false);
+      setIndex(0);
+      answer();
+    }, [setIndex, settle]);
+
+    useImperativeHandle(ref, () => ({ swipe: send, undo, reset }), [send, undo, reset]);
+
+    /** Stable for the life of the deck, for the accessibility actions below. */
+    const latestSend = useRef(send);
+    latestSend.current = send;
+    const dispatch = useCallback((direction: StackCardDirection) => {
+      latestSend.current(direction);
+    }, []);
+
+    /*
+     * One tick, when the drag first reaches the point where letting go would
+     * send the card. Latched on the reaction's own previous value, so dragging
+     * back and forth across the line does not rattle — and fired at the
+     * crossing rather than at the release, because the crossing is the moment
+     * worth knowing about while there is still a choice.
+     */
+    useAnimatedReaction(
+      () => release.value >= 1,
+      (past, wasPast) => {
+        if (wasPast === null || past === wasPast || !past) return;
+        runOnJS(tick)(haptics);
+      },
+      [haptics]
+    );
+
+    /**
+     * Whether a finger can take a card at all. A boolean, so it changes at
+     * most twice in a deck's life and the gesture keeps its identity across
+     * every advance.
+     */
+    const enabled = !disabled && index < count && allowed.length > 0;
+
+    const gesture = useMemo(() => {
+      /*
+       * Which axes the deck answers to. An activation constraint is part of
+       * how a gesture is constructed rather than something a handler can
+       * decide, so both are read here, from the array this memo is keyed on.
+       */
+      const sideways = allowed.indexOf('left') >= 0 || allowed.indexOf('right') >= 0;
+      const upright = allowed.indexOf('up') >= 0 || allowed.indexOf('down') >= 0;
+
+      /*
+       * Built as one chain from `Gesture.Pan()`, and each handler says
+       * `'worklet'` for itself. Both matter: the callbacks are only compiled
+       * for the UI thread when they can be recognised as a gesture's, and a
+       * handler that quietly stays on the JS thread is not an error anywhere
+       * — it is a drag that reports a frame late and writes shared values from
+       * the wrong side.
+       */
+      const pan = Gesture.Pan()
+        .enabled(enabled)
+        .onBegin((event) => {
+          'worklet';
+          pivot.value = lever(event.y, height.value);
+        })
+        .onStart((event) => {
+          'worklet';
+          /*
+           * Taken hold of here, when the pan activates, and not on touch-down.
+           * A finger that lands and lifts without moving is not a drag, and
+           * stopping the card on contact would leave a card that was on its
+           * way back frozen wherever the tap caught it.
+           *
+           * The origin is where the card is now, less the distance the finger
+           * travelled to activate the pan. Without it the card jumps by that
+           * distance on the first frame of every drag, and a card caught in
+           * flight jumps back under the finger's starting point.
+           */
+          cancelAnimation(x);
+          cancelAnimation(y);
+          // Under reduce motion a leaving card fades rather than flies, and a
+          // card caught while it fades has to stop going as well as moving.
+          cancelAnimation(fade);
+          fade.value = 1;
+          originX.value = x.value - event.translationX;
+          originY.value = y.value - event.translationY;
+        })
+        .onUpdate((event) => {
+          'worklet';
+          const nextX = originX.value + event.translationX;
+          const nextY = originY.value + event.translationY;
+          x.value = sideways ? nextX : resist(nextX, width.value, LOCKED_AXIS_GIVE);
+          y.value = upright ? nextY : resist(nextY, height.value, LOCKED_AXIS_GIVE);
+        })
+        .onEnd((event) => {
+          'worklet';
+          const direction = releasedDirection(
+            allowed,
+            x.value,
+            y.value,
+            event.velocityX,
+            event.velocityY,
+            width.value,
+            height.value,
+            threshold
+          );
+          if (direction) {
+            launch(direction, event.velocityX, event.velocityY);
+            return;
+          }
+          // The velocity goes into the spring, so there is no seam between
+          // the finger letting go and the card carrying on.
+          x.value = withSpring(0, { ...RETURN_SPRING, velocity: event.velocityX });
+          y.value = withSpring(0, { ...RETURN_SPRING, velocity: event.velocityY });
+        });
+
+      /*
+       * The axis constraint goes on last, after the chain the plugin had to
+       * see. A pan with no declared axis inside a scrolling screen wins every
+       * scroll that starts on the card, and the screen reads as broken in a
+       * way that looks like a scrolling bug rather than a gesture one. So a
+       * deck that answers to one axis says which, and a deck that answers to
+       * both declares nothing — it has no scroll to give way to that it would
+       * not also have to take a card from. Declaring a 1px threshold is not
+       * the same as declaring nothing: it activates on almost any movement and
+       * still takes the scroll.
+       */
+      if (sideways && !upright) return pan.activeOffsetX([-10, 10]);
+      if (upright && !sideways) return pan.activeOffsetY([-10, 10]);
+      return pan;
+    }, [
+      allowed,
+      enabled,
+      fade,
+      height,
+      launch,
+      originX,
+      originY,
+      pivot,
+      threshold,
+      width,
+      x,
+      y,
+    ]);
+
+    const context = useMemo<StackCardContextValue>(
+      () => ({
+        x,
+        y,
+        fade,
+        pivot,
+        release,
+        active,
+        width,
+        height,
+        threshold,
+        index,
+        count,
+        disabled,
+        canUndo: index > 0,
+        send,
+        undo,
+        reset,
+      }),
+      [
+        active,
+        count,
+        disabled,
+        fade,
+        height,
+        index,
+        pivot,
+        release,
+        reset,
+        send,
+        threshold,
+        undo,
+        width,
+        x,
+        y,
+      ]
+    );
+
+    const slots = stackCardVariants();
+
+    /*
+     * The window of cards that stay mounted: one behind the last visible
+     * place, so it fades in rather than appearing, and one ahead of the top,
+     * so `undo` has a card to fly back in.
+     */
+    const first = Math.max(0, index - 1);
+    const last = Math.min(count - 1, index + depth + 1);
+
+    /*
+     * Keyed on the labels themselves, for the same reason `allowed` is: a
+     * caller writing the labels inline hands over a new object every render,
+     * and this array is a prop of the card the drag is moving.
+     */
+    const labelKey = directions.map((direction) => directionLabels?.[direction] ?? '').join('');
+    const accessibilityActions = useMemo(
+      () =>
+        allowed.map((direction) => ({
+          name: direction,
+          label: directionLabels?.[direction] ?? DEFAULT_DIRECTION_LABELS[direction],
+        })),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [allowed, labelKey]
+    );
+
+    /** Stable for the life of the deck: `dispatch` closes over nothing. */
+    const onAccessibilityAction = useCallback(
+      (event: AccessibilityActionEvent) =>
+        dispatch(event.nativeEvent.actionName as StackCardDirection),
+      [dispatch]
+    );
+
+    return (
+      <StackCardContext.Provider value={context}>
+        <View {...props} className={slots.root({ className })}>
+          {/*
+           * One detector, on the pile, for the life of the deck.
+           *
+           * Not on the top card, which is the arrangement that reads as
+           * natural and is the one thing in this file that nothing else in the
+           * library does. A detector mounted per card moves as the deck
+           * advances, and a gesture object carries a single mutable handler
+           * tag that the detector registers on attach and reads back on
+           * cleanup — so the detector being unmounted can drop the tag the
+           * newly mounted one has just claimed, leaving a live detector
+           * pointing at a destroyed native handler. The next touch reaches
+           * freed memory, which is a crash with no JavaScript frames in it.
+           *
+           * On the pile it never moves, and the gesture has no reason to: it
+           * writes one offset that only the top card's style reads.
+           */}
+          <GestureDetector gesture={gesture}>
+            <View
+              onLayout={(event: LayoutChangeEvent) => {
+                width.value = event.nativeEvent.layout.width;
+                height.value = event.nativeEvent.layout.height;
+              }}
+              className={slots.pile({ className: pileClassName })}
+            >
+              {index >= count ? empty : null}
+              {cards.map((card, cardIndex) => {
+                if (cardIndex < first || cardIndex > last) return null;
+                const top = cardIndex === index;
+                const live = top && !disabled;
+                return (
+                  <StackCardSlot
+                    key={cardIndex}
+                    cardIndex={cardIndex}
+                    depth={depth}
+                    layout={layout}
+                    top={top}
+                    live={live}
+                    accessibilityActions={live ? accessibilityActions : undefined}
+                    onAccessibilityAction={live ? onAccessibilityAction : undefined}
+                  >
+                    {card}
+                    {top ? stamps : null}
+                  </StackCardSlot>
+                );
+              })}
+            </View>
+          </GestureDetector>
+          {below}
+        </View>
+      </StackCardContext.Provider>
+    );
+  }
+);
+
+/** What a screen reader is offered when the caller names nothing better. */
+const DEFAULT_DIRECTION_LABELS: Record<StackCardDirection, string> = {
+  left: 'Swipe left',
+  right: 'Swipe right',
+  up: 'Swipe up',
+  down: 'Swipe down',
+};
+
+/**
+ * Scheduled from the threshold reaction, so the question of whether haptics
+ * are wanted at all is answered off the UI thread.
+ */
+function tick(enabled: boolean) {
+  if (enabled) selectionTick();
+}
+
+/* -------------------------------------------------------------------------- */
+/* Slot                                                                       */
+/* -------------------------------------------------------------------------- */
+
+interface StackCardSlotProps {
+  cardIndex: number;
+  depth: number;
+  layout: StackCardLayout;
+  /** Whether this is the card on top, which is the only one a reader is shown. */
+  top: boolean;
+  /** Whether it also takes touches — false while the deck is disabled. */
+  live: boolean;
+  children: ReactNode;
+  accessibilityActions?: { name: string; label: string }[];
+  onAccessibilityAction?: (event: AccessibilityActionEvent) => void;
+}
+
+/**
+ * One place in the pile, and the rule that puts a card there.
+ *
+ * A slot styles itself from its own distance to the top rather than being told
+ * where to sit, so the deck advancing is one shared value changing and no
+ * re-render at all — and a card mid-flight is styled by the same rule as the
+ * pile behind it rather than by a second one that has to agree with it.
+ */
+function StackCardSlot({
+  cardIndex,
+  depth,
+  layout,
+  top,
+  live,
+  children,
+  accessibilityActions,
+  onAccessibilityAction,
+}: StackCardSlotProps) {
+  const { x, y, fade, pivot, release, active, width } = useStackCardContext('StackCard.Card');
+  const { card } = stackCardVariants();
+  /** Fixed per card, so a fan does not re-deal itself as the deck advances. */
+  const side = cardIndex % 2 === 0 ? 1 : -1;
+
+  /*
+   * Every branch returns the same four transforms in the same order, and says
+   * what it does not use with an identity value rather than by leaving the
+   * entry out. A card crosses between these branches as the deck advances, and
+   * a transform list that changes length or order between two commits is read
+   * natively as a different list — which is a crash, not a jump.
+   */
+  const style = useAnimatedStyle(() => {
+    const distance = cardIndex - active.value;
+
+    /*
+     * Answered, and still mounted only so `undo` has something to bring back.
+     * Drawn nowhere until it is asked for.
+     */
+    if (distance < 0) {
+      return {
+        opacity: 0,
+        zIndex: 0,
+        transform: [{ translateX: 0 }, { translateY: 0 }, { rotate: '0deg' }, { scale: 1 }],
+      };
+    }
+
+    if (distance === 0) {
+      return {
+        opacity: fade.value,
+        zIndex: 200,
+        transform: [
+          { translateX: x.value },
+          { translateY: y.value },
+          { rotate: `${tiltAngle(x.value, width.value, MAX_TILT, pivot.value)}deg` },
+          { scale: 1 },
+        ],
+      };
+    }
+
+    const behind = effectiveDepth(distance, release.value);
+    const opacity = depthOpacity(behind, depth);
+    const zIndex = Math.round(100 - behind * 10);
+
+    if (layout === 'flat') {
+      // Nothing is drawn behind the top card, so the next one waits exactly
+      // where the top card is and is simply uncovered as that one leaves.
+      return {
+        opacity: behind < 1 ? opacity : 0,
+        zIndex,
+        transform: [{ translateX: 0 }, { translateY: 0 }, { rotate: '0deg' }, { scale: 1 }],
+      };
+    }
+
+    if (layout === 'fan') {
+      return {
+        opacity,
+        zIndex,
+        transform: [
+          { translateX: side * behind * FAN_SPREAD },
+          { translateY: behind * PEEK * 0.35 },
+          { rotate: `${side * behind * FAN_TILT}deg` },
+          { scale: 1 - behind * SHRINK * 0.6 },
+        ],
+      };
+    }
+
+    return {
+      opacity,
+      zIndex,
+      transform: [
+        { translateX: 0 },
+        { translateY: behind * PEEK },
+        { rotate: '0deg' },
+        { scale: 1 - behind * SHRINK },
+      ],
+    };
+  });
+
+  return (
+    <Animated.View
+      style={style}
+      pointerEvents={live ? 'auto' : 'none'}
+      className={card()}
+      // Every card but the top one is out of the reading order. A pile is one
+      // card as far as a reader is concerned, and the rest are its shadow.
+      accessibilityElementsHidden={!top}
+      importantForAccessibility={top ? 'auto' : 'no-hide-descendants'}
+      // A view's custom actions are only offered when the view itself is an
+      // element a reader can focus, and a view full of text is not one. So the
+      // top card is: it is read as one card, with a direction for each action.
+      accessible={top}
+      accessibilityActions={accessibilityActions}
+      onAccessibilityAction={onAccessibilityAction}
+    >
+      <StackCardSlotIndex.Provider value={cardIndex}>{children}</StackCardSlotIndex.Provider>
+    </Animated.View>
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+/* Card                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface StackCardCardProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * One card. Filled, bordered and rounded out of the box, so a deck of plain
+ * content already reads as a deck, and restyled from `className` like anything
+ * else. It fills the pile on both axes: the pile's box is the card's size.
+ */
+const StackCardCard = forwardRef<View, StackCardCardProps>(({ className, ...props }, ref) => (
+  <View
+    ref={ref}
+    {...props}
+    className={cn(
+      'h-full w-full overflow-hidden rounded-3xl border border-border bg-card',
+      className
+    )}
+  />
+));
+
+/* -------------------------------------------------------------------------- */
+/* Stamp                                                                      */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A stamp is a filled block of colour with a word on it, turned a few degrees
+ * so it reads as pressed onto the card rather than laid out on it.
+ *
+ * The fill is the status colour at full strength rather than a tint of it: a
+ * stamp exists only for the moment it appears, and a six-per-cent wash of the
+ * card's own surface is a smudge rather than an answer. The word is carried in
+ * white, which is what the status colours are chosen to take — a status's
+ * `-foreground` token is its darker text form, meant for a neutral surface,
+ * and over the fill it is the same hue twice.
+ *
+ * It sits in the corner the card is being pulled away from, which is also the
+ * corner the thumb is not over.
+ */
+const stampVariants = tv({
+  slots: {
+    root: 'absolute inset-x-6 z-10',
+    pill: 'rounded-xl px-4 py-2',
+    label: 'text-lg font-bold uppercase tracking-widest',
+  },
+  variants: {
+    color: {
+      default: { pill: 'bg-muted-foreground', label: 'text-background' },
+      primary: { pill: 'bg-primary', label: 'text-primary-foreground' },
+      success: { pill: 'bg-success', label: 'text-success-solid-foreground' },
+      warning: { pill: 'bg-warning', label: 'text-warning-solid-foreground' },
+      info: { pill: 'bg-info', label: 'text-info-solid-foreground' },
+      destructive: {
+        pill: 'bg-destructive',
+        label: 'text-destructive-solid-foreground',
+      },
+    },
+    direction: {
+      left: { root: 'top-6 items-end', pill: 'rotate-12' },
+      right: { root: 'top-6 items-start', pill: '-rotate-12' },
+      up: { root: 'bottom-6 items-center' },
+      down: { root: 'top-6 items-center' },
+    },
+  },
+  defaultVariants: {
+    color: 'default',
+    direction: 'right',
+  },
+});
+
+export type StackCardStampColor =
+  | 'default'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'destructive';
+
+export interface StackCardStampProps
+  extends Omit<ViewProps, 'children'>,
+    VariantProps<typeof stampVariants> {
+  className?: string;
+  /** The word, or anything else to draw on the stamp. */
+  children?: ReactNode;
+  /** Which direction the stamp answers for. Also where on the card it goes. */
+  direction?: StackCardDirection;
+  /** Extra classes for the label, when the stamp is given a string. */
+  labelClassName?: string;
+}
+
+/**
+ * The answer a throw is about to give, faded in as the card is carried toward
+ * giving it.
+ *
+ * It reaches full strength exactly where letting go would commit, so a solid
+ * stamp and the haptic tick are the same statement made twice — which is the
+ * point, since the haptic is off for a lot of people and silent on most
+ * Android hardware.
+ */
+const StackCardStamp = forwardRef<View, StackCardStampProps>(
+  (
+    {
+      className,
+      labelClassName,
+      color = 'default',
+      direction = 'right',
+      children,
+      style: styleProp,
+      ...props
+    },
+    ref
+  ) => {
+    const { x, y, width, height, threshold, active } = useStackCardContext('StackCard.Stamp');
+    const slotIndex = useContext(StackCardSlotIndex);
+    const slots = stampVariants({ color, direction });
+
+    const style = useAnimatedStyle(() => {
+      // Not on a card the UI thread has not put on top yet. Outside a slot
+      // there is no card to disagree with, so it follows the drag as before.
+      const onTop = slotIndex === null || slotIndex === active.value;
+      const progress = onTop
+        ? directionProgress(direction, x.value, y.value, width.value, height.value, threshold)
+        : 0;
+      return {
+        opacity: progress,
+        // Landing rather than appearing: it is stamped on as the card commits.
+        transform: [{ scale: interpolate(progress, [0, 1], [0.8, 1]) }],
+      };
+    });
+
+    return (
+      <Animated.View
+        ref={ref}
+        {...props}
+        // The animation last, so a caller's style adds to it rather than
+        // replacing the opacity and scale that make it a stamp.
+        style={[styleProp, style]}
+        className={slots.root({ className })}
+      >
+        <View className={slots.pill()}>
+          {typeof children === 'string' || typeof children === 'number' ? (
+            <Text className={slots.label({ className: labelClassName })}>{children}</Text>
+          ) : (
+            children
+          )}
+        </View>
+      </Animated.View>
+    );
+  }
+);
+
+/* -------------------------------------------------------------------------- */
+/* Empty                                                                      */
+/* -------------------------------------------------------------------------- */
+
+export interface StackCardEmptyProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * What is under the deck once the last card has gone.
+ *
+ * Mounted only when the deck is exhausted, so a card flying off never crosses
+ * it. A deck with none of these leaves the empty box the cards were in, which
+ * is the right answer when something else on the screen already says the queue
+ * is finished.
+ */
+const StackCardEmpty = forwardRef<View, StackCardEmptyProps>(({ className, ...props }, ref) => (
+  <View
+    ref={ref}
+    {...props}
+    className={cn(
+      'absolute inset-0 items-center justify-center gap-2 rounded-3xl border border-dashed border-border p-6',
+      className
+    )}
+  />
+));
+
+/* -------------------------------------------------------------------------- */
+/* Actions                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export interface StackCardActionsProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The row of buttons under the pile. Laid out after it rather than over it, so
+ * the buttons are not competing with the card for the same touches.
+ */
+const StackCardActions = forwardRef<View, StackCardActionsProps>(
+  ({ className, ...props }, ref) => (
+    <View
+      ref={ref}
+      {...props}
+      className={cn('flex-row items-center justify-center gap-4 pt-5', className)}
+    />
+  )
+);
+
+const actionVariants = tv({
+  slots: {
+    root: 'items-center justify-center rounded-full border',
+  },
+  variants: {
+    color: {
+      default: { root: 'border-border bg-card' },
+      primary: { root: 'border-primary bg-primary' },
+      success: { root: 'border-success bg-success' },
+      warning: { root: 'border-warning bg-warning' },
+      info: { root: 'border-info bg-info' },
+      destructive: { root: 'border-destructive bg-destructive' },
+    },
+    size: {
+      sm: { root: 'h-10 w-10' },
+      md: { root: 'h-14 w-14' },
+      lg: { root: 'h-16 w-16' },
+    },
+  },
+  defaultVariants: {
+    color: 'default',
+    size: 'md',
+  },
+});
+
+/** How big a glyph is drawn on each button size. */
+const ACTION_ICON_SIZE = { sm: 18, md: 24, lg: 28 } as const;
+
+export interface StackCardActionProps
+  extends Omit<ViewProps, 'children'>,
+    VariantProps<typeof actionVariants> {
+  className?: string;
+  /** What pressing it does: send the top card that way, or bring the last one back. */
+  action: StackCardDirection | 'undo';
+  /** The glyph. Sized and tinted by the button — pass neither. */
+  icon?: ReactNode;
+  /**
+   * What a screen reader is offered. Falls back to "Undo", or to the plain
+   * name of the direction.
+   */
+  label?: string;
+  /** Run after the deck has been told, for a sound or a log. */
+  onPress?: () => void;
+}
+
+/**
+ * One decision as an ordinary button.
+ *
+ * This is the accessible path through a deck, and it is also the path a lot of
+ * sighted people take on the card they are unsure about: a throw looks
+ * irreversible in a way a tap does not, so the pair is not redundant.
+ *
+ * `undo` disables itself on the first card, where there is nothing to bring
+ * back, and every other action disables itself once the deck is empty — a
+ * button that still looks pressable over an exhausted deck is the commonest
+ * way one of these ends up feeling broken.
+ */
+const StackCardAction = forwardRef<View, StackCardActionProps>(
+  ({ className, action, icon, label, color = 'default', size = 'md', onPress, ...props }, ref) => {
+    const context = useStackCardContext('StackCard.Action');
+    const slots = actionVariants({ color, size });
+    const tint = useActionTint(color as StackCardStampColor);
+
+    const isUndo = action === 'undo';
+    const disabled =
+      context.disabled || (isUndo ? !context.canUndo : context.index >= context.count);
+
+    return (
+      <AnimatedPressable
+        ref={ref}
+        accessibilityRole="button"
+        accessibilityLabel={label ?? (isUndo ? 'Undo' : DEFAULT_DIRECTION_LABELS[action])}
+        accessibilityState={{ disabled }}
+        disabled={disabled}
+        onPress={() => {
+          if (isUndo) context.undo();
+          else context.send(action);
+          onPress?.();
+        }}
+        {...props}
+        className={slots.root({ className: cn(disabled && 'opacity-40', className) })}
+      >
+        <IconColorProvider color={tint}>{sizeIcon(icon, size ?? 'md')}</IconColorProvider>
+      </AnimatedPressable>
+    );
+  }
+);
+
+/**
+ * The glyph at button size, unless the caller asked for one. Sized here rather
+ * than at every call site, because a row of these reads as a set only while
+ * the icons in it match.
+ */
+function sizeIcon(icon: ReactNode, size: 'sm' | 'md' | 'lg'): ReactNode {
+  if (!isValidElement<{ size?: number }>(icon)) return icon;
+  if (icon.props.size !== undefined) return icon;
+  return cloneElement(icon, { size: ACTION_ICON_SIZE[size] });
+}
+
+/**
+ * The colour a glyph is drawn in on a button — the token that reads against
+ * its fill. Resolved from the theme wherever the theme has an answer, since a
+ * hex stops being right the moment the theme inverts; white is the exception,
+ * because a status fill is the same saturated colour in every theme and white
+ * is what it carries.
+ *
+ * Both tokens are read on every render because a hook cannot be called for one
+ * branch only. They are variable lookups, not work.
+ */
+function useActionTint(color: StackCardStampColor): string | undefined {
+  const foreground = useCSSVariable('--color-foreground');
+  const primary = useCSSVariable('--color-primary-foreground');
+
+  if (color === 'default') return typeof foreground === 'string' ? foreground : undefined;
+  if (color === 'primary') return typeof primary === 'string' ? primary : undefined;
+  return '#ffffff';
+}
+
+StackCardRoot.displayName = 'StackCard';
+StackCardCard.displayName = 'StackCard.Card';
+StackCardStamp.displayName = 'StackCard.Stamp';
+StackCardEmpty.displayName = 'StackCard.Empty';
+StackCardActions.displayName = 'StackCard.Actions';
+StackCardAction.displayName = 'StackCard.Action';
+
+export const StackCard = Object.assign(StackCardRoot, {
+  Card: StackCardCard,
+  Stamp: StackCardStamp,
+  Empty: StackCardEmpty,
+  Actions: StackCardActions,
+  Action: StackCardAction,
+});