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

package/src/components/surface/surface.tsx

@@ -0,0 +1,87 @@
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { View, type ViewProps } from "react-native";
+import { type SurfaceContextValue, SurfaceProvider, useSurfaceContext } from "./surface.context";
+import {
+	resolveSurfacePlane,
+	resolveSurfaceVariant,
+	type SurfaceMaterial,
+	type SurfacePadding,
+	type SurfaceVariant,
+	surfaceVariants,
+} from "./surface.variants";
+
+export type SurfaceProps = ViewProps & {
+	/**
+	 * The fill. Omitted, a top-level surface is the `default` card and a nested
+	 * one steps to the next fill, so it never vanishes into the surface it sits on.
+	 */
+	variant?: SurfaceVariant;
+	/** Inner spacing. `none` also clips, for content bled to the corners. */
+	padding?: SurfacePadding;
+	/** `flat` by default. `etched` sets a highlight into the edge; `tray` is the muted frame that holds panels. */
+	material?: SurfaceMaterial;
+	className?: string;
+	children?: ReactNode;
+};
+
+/**
+ * A rounded container on one of the theme's surface fills — the plane a card,
+ * an alert or a settings panel is drawn on.
+ *
+ * The variants are a ladder rather than a palette. `default` is the card,
+ * hairlined so it holds its edge on the page; `secondary` and `tertiary` are
+ * the fills beneath it; `transparent` keeps the padding and corner and paints
+ * nothing. A surface that names no variant reads the one it sits in and steps
+ * to the next fill, so nesting builds depth without naming a colour.
+ *
+ * It publishes no text treatment. `Text`'s presets already carry their own
+ * colour, so a class cascade would reach only a bare `Text` — and
+ * would mark every `Text` beneath it as nested, which strips `Text.Code` of its
+ * chip. A caller that wants the fill's own token reads
+ * `SURFACE_FOREGROUND_TOKENS[useSurface().plane]`.
+ *
+ * @example
+ * <Surface>
+ *   <Text.Label>Account</Text.Label>
+ *   <Surface className="mt-3">
+ *     <Text color="muted">Signed in as sam@example.com</Text>
+ *   </Surface>
+ * </Surface>
+ *
+ * @example
+ * <Surface padding="none">
+ *   <Image className="h-40 w-full" source={cover} />
+ * </Surface>
+ */
+export function Surface({
+	variant,
+	padding = "md",
+	material = "flat",
+	className,
+	children,
+	...props
+}: SurfaceProps): ReactElement {
+	const parent = useSurfaceContext();
+	const parentPlane = parent?.plane ?? null;
+
+	const resolved = resolveSurfaceVariant({ parentPlane, variant });
+	const plane = resolveSurfacePlane({ material, parentPlane, variant: resolved });
+	const inTray = parent?.material === "tray";
+
+	const context = useMemo<SurfaceContextValue>(
+		() => ({ material, plane, variant: resolved }),
+		[material, plane, resolved]
+	);
+
+	return (
+		<SurfaceProvider value={context}>
+			<View
+				className={surfaceVariants({ inTray, material, padding, variant: resolved }).root({ className })}
+				{...props}
+			>
+				{children}
+			</View>
+		</SurfaceProvider>
+	);
+}
+Surface.displayName = "DelacourUI.Surface";

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

@@ -0,0 +1,227 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	resolveSurfacePlane,
+	resolveSurfaceVariant,
+	SURFACE_FILLED_VARIANTS,
+	SURFACE_FOREGROUND_TOKENS,
+	SURFACE_MATERIALS,
+	SURFACE_PADDINGS,
+	SURFACE_VARIANTS,
+	surfaceVariants,
+} from "./surface.variants";
+
+/** Every class string the variant function can produce, one per combination. */
+function everyRoot(): string[] {
+	return SURFACE_VARIANTS.flatMap((variant) =>
+		SURFACE_PADDINGS.map((padding) => surfaceVariants({ padding, variant }).root())
+	);
+}
+
+describe("surfaceVariants root slot", () => {
+	test("defaults to the card surface with md padding", () => {
+		const cls = surfaceVariants().root();
+		expect(cls).toContain("bg-card");
+		expect(cls).toContain("border-border");
+		expect(cls).toContain("p-4");
+	});
+
+	test("maps each variant to its fill", () => {
+		expect(surfaceVariants({ variant: "default" }).root()).toContain("bg-card");
+		expect(surfaceVariants({ variant: "secondary" }).root()).toContain("bg-secondary");
+		expect(surfaceVariants({ variant: "tertiary" }).root()).toContain("bg-tertiary");
+		expect(surfaceVariants({ variant: "transparent" }).root()).toContain("bg-transparent");
+	});
+
+	test("gives every variant a distinct surface", () => {
+		const seen = new Set(SURFACE_VARIANTS.map((variant) => surfaceVariants({ variant }).root()));
+		expect(seen.size).toBe(SURFACE_VARIANTS.length);
+	});
+
+	// A card on a page is white on near-white in light. The hairline is what
+	// holds its edge; the filled rungs below it are separated by their fill.
+	test("only the default variant draws a visible border", () => {
+		expect(surfaceVariants({ variant: "default" }).root()).toContain("border-border");
+		for (const variant of SURFACE_VARIANTS.filter((name) => name !== "default")) {
+			expect(surfaceVariants({ variant }).root()).not.toContain("border-border");
+		}
+	});
+
+	// Every variant carries the same one-point border box, so switching variant
+	// never moves the content by a pixel.
+	test("every variant reserves the same border width", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).toMatch(/(^|\s)border(\s|$)/);
+		}
+	});
+
+	test("is card-shaped, with a continuous corner, at every variant and padding", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).toContain("rounded-lg");
+			expect(cls).toContain("border-continuous");
+		}
+	});
+
+	test("maps each padding to its step", () => {
+		expect(surfaceVariants({ padding: "none" }).root()).toContain("p-0");
+		expect(surfaceVariants({ padding: "sm" }).root()).toContain("p-3");
+		expect(surfaceVariants({ padding: "md" }).root()).toContain("p-4");
+		expect(surfaceVariants({ padding: "lg" }).root()).toContain("p-6");
+	});
+
+	// `none` is for content that bleeds to the edge — an image, a chart — and
+	// that content has to take the corner with it.
+	test("clips only when its content touches the edge", () => {
+		expect(surfaceVariants({ padding: "none" }).root()).toContain("overflow-hidden");
+		for (const padding of SURFACE_PADDINGS.filter((name) => name !== "none")) {
+			expect(surfaceVariants({ padding }).root()).not.toContain("overflow-hidden");
+		}
+	});
+
+	// Rule 1: a React Native View does not cascade colour to a Text descendant.
+	test("carries no text treatment on the root", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).not.toMatch(/\btext-/);
+		}
+	});
+
+	test("draws no shadow anywhere", () => {
+		for (const cls of everyRoot()) {
+			expect(cls).not.toMatch(/shadow/);
+		}
+	});
+
+	test("merges an incoming className last", () => {
+		expect(surfaceVariants().root({ className: "mt-3" })).toContain("mt-3");
+		expect(surfaceVariants().root({ className: "bg-popover" })).not.toContain("bg-card");
+		expect(surfaceVariants().root({ className: "p-8" })).not.toMatch(/\bp-4\b/);
+	});
+
+	// `border-continuous` is Uniwind's, and a merger that read it as a colour
+	// would drop it the moment a caller tinted the border.
+	test("keeps its corner curve when a caller recolours the border", () => {
+		expect(surfaceVariants().root({ className: "border-destructive" })).toContain("border-continuous");
+	});
+});
+
+describe("SURFACE_FOREGROUND_TOKENS", () => {
+	test("names the X-foreground token for each fill", () => {
+		expect(SURFACE_FOREGROUND_TOKENS).toEqual({
+			default: "card-foreground",
+			secondary: "secondary-foreground",
+			tertiary: "tertiary-foreground",
+		});
+	});
+
+	// Every token named here has to exist, or the class compiles to nothing and
+	// the text keeps whatever colour it inherited.
+	test("every token is declared in theme.css", () => {
+		const css = readFileSync(join(import.meta.dir, "../../styles/theme.css"), "utf8");
+		for (const token of Object.values(SURFACE_FOREGROUND_TOKENS)) {
+			expect(css).toContain(`--color-${token}: var(--${token})`);
+		}
+	});
+});
+
+describe("resolveSurfaceVariant", () => {
+	test("an explicit variant always wins", () => {
+		for (const variant of SURFACE_VARIANTS) {
+			expect(resolveSurfaceVariant({ parentPlane: null, variant })).toBe(variant);
+			expect(resolveSurfaceVariant({ parentPlane: "secondary", variant })).toBe(variant);
+		}
+	});
+
+	test("a top-level surface is the default card", () => {
+		expect(resolveSurfaceVariant({ parentPlane: null })).toBe("default");
+	});
+
+	test("a nested surface steps to the next fill", () => {
+		expect(resolveSurfaceVariant({ parentPlane: "default" })).toBe("secondary");
+		expect(resolveSurfaceVariant({ parentPlane: "secondary" })).toBe("tertiary");
+		expect(resolveSurfaceVariant({ parentPlane: "tertiary" })).toBe("secondary");
+	});
+
+	// The point of the ladder: whatever depth it is nested at, a surface never
+	// resolves to the fill it is sitting on, or it would vanish into it.
+	test("never resolves to the fill of the plane it sits on", () => {
+		for (const parentPlane of SURFACE_FILLED_VARIANTS) {
+			expect(resolveSurfaceVariant({ parentPlane })).not.toBe(parentPlane);
+		}
+	});
+
+	test("never resolves to transparent on its own", () => {
+		for (const parentPlane of [null, ...SURFACE_FILLED_VARIANTS]) {
+			expect(resolveSurfaceVariant({ parentPlane })).not.toBe("transparent");
+		}
+	});
+});
+
+describe("resolveSurfacePlane", () => {
+	test("a filled surface is the plane its children sit on", () => {
+		for (const variant of SURFACE_FILLED_VARIANTS) {
+			expect(resolveSurfacePlane({ parentPlane: null, variant })).toBe(variant);
+			expect(resolveSurfacePlane({ parentPlane: "tertiary", variant })).toBe(variant);
+		}
+	});
+
+	// A transparent surface paints nothing, so what its children sit on is
+	// still whatever it sits on.
+	test("a transparent surface passes its parent's plane through", () => {
+		expect(resolveSurfacePlane({ parentPlane: null, variant: "transparent" })).toBeNull();
+		for (const parentPlane of SURFACE_FILLED_VARIANTS) {
+			expect(resolveSurfacePlane({ parentPlane, variant: "transparent" })).toBe(parentPlane);
+		}
+	});
+
+	test("a surface inside a transparent one steps from the plane beneath both", () => {
+		const through = resolveSurfacePlane({ parentPlane: "default", variant: "transparent" });
+		expect(resolveSurfaceVariant({ parentPlane: through })).toBe("secondary");
+	});
+});
+
+describe("surface materials", () => {
+	test("flat is the default and adds nothing", () => {
+		expect(surfaceVariants().root()).toBe(surfaceVariants({ material: "flat" }).root());
+		expect(surfaceVariants().root()).not.toMatch(/shadow/);
+	});
+
+	test("etched lifts the edge with the light and dark highlight", () => {
+		const cls = surfaceVariants({ material: "etched" }).root();
+		expect(cls).toContain("shadow-etched");
+		expect(cls).toContain("dark:shadow-etched-dark");
+		expect(cls).toContain("bg-card");
+	});
+
+	test("a tray is a muted, squarely padded 2xl frame", () => {
+		const cls = surfaceVariants({ material: "tray", padding: "md" }).root();
+		expect(cls).toContain("bg-muted/70");
+		expect(cls).toContain("rounded-2xl");
+		expect(cls).toContain("p-1");
+		expect(cls).not.toMatch(/\bp-4\b/);
+		expect(cls).not.toContain("bg-card");
+	});
+
+	test("a panel in a tray takes the xl corner", () => {
+		expect(surfaceVariants({ inTray: true }).root()).toContain("rounded-xl");
+		expect(surfaceVariants({ inTray: true }).root()).not.toContain("rounded-lg");
+	});
+
+	test("lists every material", () => {
+		expect(SURFACE_MATERIALS).toEqual(["flat", "etched", "tray"]);
+	});
+});
+
+describe("tray planes", () => {
+	// The tray paints its own muted fill, so what sits in it steps from nothing:
+	// a default card panel, not a secondary one on a muted ground.
+	test("a tray resets the plane so its panels resolve to the card fill", () => {
+		const through = resolveSurfacePlane({ parentPlane: "tertiary", variant: "default", material: "tray" });
+		expect(through).toBeNull();
+		expect(resolveSurfaceVariant({ parentPlane: through })).toBe("default");
+	});
+
+	test("other materials leave the plane alone", () => {
+		expect(resolveSurfacePlane({ parentPlane: null, variant: "secondary", material: "etched" })).toBe("secondary");
+	});
+});

package/src/components/surface/surface.variants.ts

@@ -0,0 +1,165 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+export const SURFACE_VARIANTS = ["default", "secondary", "tertiary", "transparent"] as const;
+
+export const SURFACE_PADDINGS = ["none", "sm", "md", "lg"] as const;
+
+/**
+ * What the surface is made of, orthogonal to which plane it fills.
+ *
+ * `flat` is the library default and draws nothing extra. `etched` sets a
+ * one-pixel highlight into the edge with a very soft drop — see the
+ * `--shadow-etched` tokens. `tray` is the muted frame that holds panels: a
+ * 2xl corner, 4pt of padding and a translucent muted fill, so the panels in it
+ * read as inset cards rather than as loose boxes on a page.
+ */
+export const SURFACE_MATERIALS = ["flat", "etched", "tray"] as const;
+
+export type SurfaceMaterial = (typeof SURFACE_MATERIALS)[number];
+export type SurfaceVariant = (typeof SURFACE_VARIANTS)[number];
+export type SurfacePadding = (typeof SURFACE_PADDINGS)[number];
+
+/** The variants that paint a fill — every one but `transparent`. */
+export const SURFACE_FILLED_VARIANTS = ["default", "secondary", "tertiary"] as const;
+
+/**
+ * A fill something can sit on. `transparent` is not one: it paints nothing, so
+ * whatever is inside it still sits on the plane beneath.
+ */
+export type SurfacePlane = (typeof SURFACE_FILLED_VARIANTS)[number];
+
+/**
+ * Theme token for content drawn on each fill — `X-foreground` on an `X`
+ * surface, per the package's token rule. A class is `text-${token}`; a value,
+ * for an icon or a gradient stop, is `useThemeColor(token)`.
+ */
+export const SURFACE_FOREGROUND_TOKENS = {
+	default: "card-foreground",
+	secondary: "secondary-foreground",
+	tertiary: "tertiary-foreground",
+} as const satisfies Record<SurfacePlane, string>;
+
+/**
+ * The fill a nested surface takes when it names none, keyed by the plane it
+ * sits on.
+ *
+ * `tertiary` is quieter than `secondary` — half a step back toward the page —
+ * so a third level returns to `secondary` rather than stopping. What matters is
+ * that each surface differs from its immediate parent; a strictly ascending
+ * ladder would run out of fills at the fourth level and start vanishing into
+ * its own parent.
+ */
+const NEXT_PLANE = {
+	default: "secondary",
+	secondary: "tertiary",
+	tertiary: "secondary",
+} as const satisfies Record<SurfacePlane, SurfacePlane>;
+
+/**
+ * Styling for a surface.
+ *
+ * The root is card-shaped — `rounded-lg`, the corner `--radius` names, see the
+ * corner-scale note in the package AGENTS.md — with `border-continuous`, which
+ * gives iOS's continuous corner rather than a circular arc. Android ignores it.
+ *
+ * Every variant reserves the same one-point `border`, transparent unless the
+ * variant colours it, so changing variant never moves the content. Only
+ * `default` colours it: `--card` sits a percent above `--background` in light,
+ * and without the hairline a card on a page is white on near-white. The filled
+ * rungs below it are told apart by their fill.
+ *
+ * `padding: "none"` clips, and nothing else does. It is the one step whose
+ * content touches the edge — an image or a chart bled to the corners — and that
+ * content has to take the corner with it. Clipping everywhere would crop
+ * anything a child draws past its own box.
+ *
+ * No shadow, on purpose. Nothing in this package casts one — React Native's
+ * shadow props disagree between platforms — so depth here is carried by fill.
+ *
+ * The root carries no `text-*`: a React Native `View` does not cascade colour
+ * to a `Text` descendant, so a class here would reach nothing.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const surfaceVariants = tv({
+	slots: {
+		root: "rounded-lg border border-continuous border-transparent",
+	},
+	variants: {
+		variant: {
+			default: { root: "border-border bg-card" },
+			secondary: { root: "bg-secondary" },
+			tertiary: { root: "bg-tertiary" },
+			transparent: { root: "bg-transparent" },
+		},
+		padding: {
+			none: { root: "overflow-hidden p-0" },
+			sm: { root: "p-3" },
+			md: { root: "p-4" },
+			lg: { root: "p-6" },
+		},
+		material: {
+			flat: {},
+			etched: { root: "shadow-etched dark:shadow-etched-dark" },
+			tray: {},
+		},
+		// A panel sitting in a tray: one corner step under the tray's own, so
+		// the gap between the two curves stays even round the edge.
+		inTray: { true: {}, false: {} },
+	},
+	compoundVariants: [
+		// Beats the padding axis, so a tray is `p-1` whatever `padding` says.
+		{ material: "tray", class: { root: "rounded-2xl border-transparent bg-muted/70 p-1" } },
+		{ inTray: true, class: { root: "rounded-xl" } },
+	],
+	defaultVariants: {
+		variant: "default",
+		padding: "md",
+		material: "flat",
+		inTray: false,
+	},
+});
+
+export type SurfaceVariantProps = VariantProps<typeof surfaceVariants>;
+
+/**
+ * The fill a surface draws.
+ *
+ * An explicit `variant` always wins. Without one, a surface at the top of the
+ * tree is the `default` card, and a surface nested in another steps to the next
+ * fill, so a panel inside a card is told apart from the card with nothing said
+ * at the call site — and a `Card` built on this gets the same for free.
+ */
+export function resolveSurfaceVariant({
+	parentPlane,
+	variant,
+}: {
+	parentPlane: SurfacePlane | null;
+	variant?: SurfaceVariant;
+}): SurfaceVariant {
+	if (variant) {
+		return variant;
+	}
+	return parentPlane ? NEXT_PLANE[parentPlane] : "default";
+}
+
+/**
+ * The plane a surface's children sit on: its own fill, or — for a transparent
+ * surface, which paints none — the plane it sits on itself.
+ */
+export function resolveSurfacePlane({
+	material = "flat",
+	parentPlane,
+	variant,
+}: {
+	material?: SurfaceMaterial;
+	parentPlane: SurfacePlane | null;
+	variant: SurfaceVariant;
+}): SurfacePlane | null {
+	// A tray paints its own muted fill, so what it holds steps from no plane at
+	// all and resolves to the card fill rather than the next rung down.
+	if (material === "tray") return null;
+	return variant === "transparent" ? parentPlane : variant;
+}

package/src/components/swipe/AGENTS.md

@@ -0,0 +1,140 @@
+# Swipe
+
+A row that slides aside to reveal actions behind it — delete, archive, snooze, mark done. Compound
+root plus `Swipe.Start`, `Swipe.End`, `Swipe.Action` and `Swipe.Group`, with `useSwipe()` and
+`useSwipeGroup()`. It acts on one row; for many rows at once, a selection mode is the pattern.
+
+`import { Swipe } from "@delacour/react-native-ui/swipe";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/swipe` |
+| `swipe.tsx` | Root — the partition, the pan, the release, the imperative handle and the accessibility actions |
+| `swipe-start.tsx` | `Swipe.Start`, a marker that renders nothing |
+| `swipe-end.tsx` | `Swipe.End`, a marker that renders nothing |
+| `swipe-action.tsx` | `Swipe.Action`, one tile, positioned by its own animated style |
+| `swipe-panel.tsx` | The layer behind one edge — internal, one per side that has tiles |
+| `swipe-group.tsx` | `Swipe.Group`, the registry that keeps one row open |
+| `swipe.context.tsx` | Row, tile and group contexts, `useSwipe()`, `useSwipeGroup()` |
+| `swipe.types.ts` | `SwipePanelProps`, shared by the two markers |
+| `swipe.variants.ts` | Pure `tv()` slots + the partition, release and tile-layout resolvers, no RN imports |
+| `swipe.variants.test.ts` | |
+
+## Design
+
+- **Colours**: `default`, `primary`, `success`, `warning`, `info`, `destructive` — Badge's set. A
+  tile is `bg-{color}` with its glyph and label in `{color}-foreground`; `default` is `bg-muted`
+  with `text-foreground`, since there is no `muted` surface ink stronger than that.
+- **Tiles are 72pt, all of them.** A panel's width is a count times `SWIPE_TILE_WIDTH`, so nothing
+  is measured and the release can be judged on the UI thread the moment the finger lifts. The
+  `tileContent` slot spells the same number as `w-18`, and a test pins the pair.
+- **The panel is exactly as wide as the gap the row has left.** Never wider, so it cannot paint
+  over a row that has no background of its own; never narrower, so no hole opens. The row slot
+  sets no `bg-*` and a test holds it to that — the two never overlap, so the row needs none.
+- **Past the tiles' total the outermost tile grows, and the panel wears its colour.** An overshoot
+  then reads as *more of that action* rather than as an empty strip. The outermost is the last
+  tile on `end` and the first on `start` — `resolveOutermostIndex`.
+- **Tiles emerge from under the row.** Short of fully open each is overlapped by the one outside
+  it, spread in proportion to the gap; they are whole and edge to edge exactly when the gap
+  reaches their total. `resolveTileLayout` is the rule, and a test sweeps it to prove the tiles
+  always cover the gap and never reach past it once open.
+- **A tile's content box is pinned to its inner edge**, so when the outermost grows its glyph
+  stays beside its neighbours rather than drifting to the middle of a widening slab.
+
+## Anatomy
+
+- **`Swipe.Start` and `Swipe.End` are markers, lifted out by element type.** Only the root knows
+  the gap, so only the root can lay the tiles out; a marker that rendered its own children would
+  need the offset passed back down to it anyway. Everything that is not a marker is the row, and
+  order does not matter.
+- **The match is on `displayName`, not on function identity.** The package ships raw source, so
+  React Compiler or a second module instance can hand the root an element whose `type` is a
+  different object standing for the same component — the failure
+  [Switch](../switch/AGENTS.md)'s thumb detection records. `partitionSwipeChildren` reads only
+  `type.displayName` and `props.children`, which is also what lets the test feed it plain objects.
+- **A tile has to be written directly inside its marker.** `Swipe.Action` reads a tile context the
+  root supplies as it lays each tile out, and throws by name if it is rendered anywhere else.
+  Wrapping actions in a custom component inside the marker therefore does not work — the wrapper
+  would be the tile. This is the trade the lift-out makes.
+- **The icon is a component prop, and that bends the house rule on purpose.** Icons are composed
+  everywhere else, but a tile has to size its glyph to `size-icon-md` and tint it to its
+  foreground. It takes the same `IconComponent` type `Icon`'s `icon` prop takes and renders
+  `<Icon icon={…} />` inside an `IconDefaultsProvider`, so the glyph still flows through the one
+  icon path the package has.
+
+## Gesture
+
+- **`activeOffsetX([-10, 10])` under `failOffsetY([-8, 8])`**, [Tabs](../tabs/AGENTS.md)' pairing.
+  The pan waits for clearly sideways intent and fails the moment the finger commits vertically, so
+  a list of rows scrolls normally. This is the opposite of [Slider](../slider/AGENTS.md)'s
+  `minDistance(0)`: a slider owns every touch on its track, a row owns only the sideways ones.
+- **A side with no panel rubber-bands at 0.2 and returns.** The row still answers the finger, so
+  the touch does not feel dead, but it never promises an action that is not there.
+- **The release is judged on a projection**: `offset + velocity × 0.1` against half the panel. A
+  projection that crosses the rest position closes rather than flinging the row open on the other
+  side.
+- **A full swipe needs the finger itself past the point.** `|offset| > panel + 0.35 × row`, with
+  the projection still beyond it. A flick alone never fires the outermost action, because that
+  action is routinely Delete; and pulling back from past the point before letting go cancels it.
+  This is the one reading of "or a projected equivalent" that cannot delete by accident. The
+  haptic ticks once at exactly that crossing and re-arms if the finger goes back, so the person
+  letting go knows what will happen.
+- **The fly-off fires the action when it lands, then brings the row back a beat later.** An action
+  that removes the row from state unmounts it during that beat, so it never visibly slides back
+  in; one that does not (Done, Archive into the same list) sees its row return closed.
+- **Tapping the open row closes it and swallows the tap.** A transparent shield covers the row
+  only while a side is open, behind its own `Gesture.Tap()`, so the row's own `Pressable`s never
+  see that tap.
+- **The release runs in `onFinalize`, gated on the pan having started.** `onFinalize` also fires
+  for a touch that never activated; without the gate a stray tap would re-judge, and stomp on, an
+  imperative `open()` still springing.
+- **Nothing re-renders during a drag.** The offset, the grab, the full-swipe latch and the measured
+  width are shared values; React state changes only when a release settles a side.
+- **Every worklet body is self-contained.** `resolveSwipeRelease`, `resolveSwipeDrag` and
+  `resolveTileLayout` are restated inside the gesture and the animated styles rather than called,
+  and the tests pin the pure versions. A module-scope worklet calling a sibling is the crash
+  [Slider](../slider/AGENTS.md) documents.
+
+## Group
+
+- **Rows register through context, never by the group walking its children.** A row nested in a
+  `ListGroup`, a `.map()` or a custom component still belongs. The registry is a ref, so joining
+  or leaving it re-renders nothing.
+- **The group closes only rows that are open.** A close aimed at a shut row would restart its
+  spring and cancel a drag already under way on it.
+- **`useSwipeGroup()` outside a group is a no-op, not a throw**, so a screen can call
+  `closeAll()` whether or not its rows are grouped.
+
+## Motion
+
+- **Under reduced motion every spring becomes a 160ms timing, and the fly-off becomes a fade.**
+  The row still follows the finger — direct manipulation is not decorative — and the fade keeps
+  the outcome visible rather than cutting.
+
+## RTL
+
+- **`I18nManager.isRTL` flips one sign — the row's translation and the pan's reading of it.** The
+  offset is held in logical points (positive reveals `start`), and the panels and tiles are pinned
+  with Yoga's logical `start` / `end`, which mirror on their own. `end` is always the edge text
+  runs toward.
+
+## Accessibility
+
+- **Every action is published on the row as an accessibility action**, named and labelled by its
+  `label`, and dispatched by name. A swipe is invisible to a screen reader, so without this the
+  actions would not exist for one.
+- **The row is a single accessibility element** (`accessible`), the shape a list row with custom
+  actions takes; `accessibilityLabel` and `accessibilityHint` passed to `Swipe` land on it. A row
+  that needs its own separately focusable controls is not a swipe row.
+- **Tiles are `button`s, hidden while the row is shut** (`accessibilityElementsHidden` and
+  `importantForAccessibility="no-hide-descendants"` on each panel), so a screen reader does not
+  walk into actions nobody can see.
+
+## Out of scope
+
+- A controlled `openSide` prop. The imperative handle and `onOpenChange` cover the cases that came
+  up; a controlled pair can follow through `useControllableState` if one appears.
+- Wrapped tiles (see Anatomy), per-tile widths, and vertical swipes.
+- Undo. A demo keeps local state; a toast belongs to the overlays.

package/src/components/swipe/index.ts

@@ -0,0 +1,31 @@
+export { Swipe, type SwipeHandle, type SwipeProps } from "./swipe";
+export {
+	type SwipeContextValue,
+	type SwipeGroupContextValue,
+	useSwipe,
+	useSwipeContext,
+	useSwipeGroup,
+} from "./swipe.context";
+export type { SwipePanelProps } from "./swipe.types";
+export {
+	partitionSwipeChildren,
+	resolveOutermostIndex,
+	resolveSwipeActionForegroundToken,
+	resolveSwipeDrag,
+	resolveSwipeRelease,
+	resolveTileLayout,
+	SWIPE_ACTION_COLORS,
+	SWIPE_ACTION_FOREGROUND_TOKEN,
+	SWIPE_SIDES,
+	SWIPE_TILE_WIDTH,
+	type SwipeActionColor,
+	type SwipeChildren,
+	type SwipeOpenSide,
+	type SwipeRelease,
+	type SwipeSide,
+	type SwipeVariantProps,
+	swipeVariants,
+	toPhysicalOffset,
+} from "./swipe.variants";
+export type { SwipeActionProps } from "./swipe-action";
+export type { SwipeGroupProps } from "./swipe-group";