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

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

@@ -0,0 +1,274 @@
+import { describe, expect, test } from "bun:test";
+import { ICON_SIZES } from "../icon/icon.variants";
+import {
+	FAB_DIAL_STAGGER,
+	FAB_FOREGROUND_TOKEN,
+	FAB_ICON_SIZE,
+	FAB_PLACEMENTS,
+	FAB_SIZES,
+	FAB_VARIANTS,
+	fabVariants,
+	resolveDialProgress,
+	resolveFabIconSize,
+	resolveFabPlacementStyle,
+	resolveLabelSide,
+} from "./fab.variants";
+
+describe("resolveDialProgress", () => {
+	const count = 4;
+	const stagger = FAB_DIAL_STAGGER;
+
+	test("every action is fully closed at 0 and fully open at 1", () => {
+		for (let index = 0; index < count; index++) {
+			expect(resolveDialProgress({ open: 0, index, count, stagger })).toBe(0);
+			expect(resolveDialProgress({ open: 1, index, count, stagger })).toBe(1);
+		}
+	});
+
+	test("rises monotonically with the spring, for every action", () => {
+		for (let index = 0; index < count; index++) {
+			let previous = -1;
+			for (let step = 0; step <= 100; step++) {
+				const value = resolveDialProgress({ open: step / 100, index, count, stagger });
+				expect(value).toBeGreaterThanOrEqual(previous);
+				previous = value;
+			}
+		}
+	});
+
+	test("stays within 0..1 when the spring overshoots either end", () => {
+		for (let index = 0; index < count; index++) {
+			expect(resolveDialProgress({ open: 1.15, index, count, stagger })).toBe(1);
+			expect(resolveDialProgress({ open: -0.1, index, count, stagger })).toBe(0);
+		}
+	});
+
+	test("staggers: the action nearest the trigger leads the one beyond it", () => {
+		const nearest = resolveDialProgress({ open: 0.3, index: 0, count, stagger });
+		const farthest = resolveDialProgress({ open: 0.3, index: count - 1, count, stagger });
+		expect(nearest).toBeGreaterThan(farthest);
+	});
+
+	test("the last action has not started before its window opens", () => {
+		const start = (count - 1) * stagger;
+		expect(resolveDialProgress({ open: start, index: count - 1, count, stagger })).toBe(0);
+	});
+
+	test("a lone action follows the spring exactly", () => {
+		for (const open of [0, 0.25, 0.5, 0.75, 1]) {
+			expect(resolveDialProgress({ open, index: 0, count: 1, stagger })).toBeCloseTo(open);
+		}
+	});
+
+	test("a stagger of zero puts every action on the spring", () => {
+		for (let index = 0; index < count; index++) {
+			expect(resolveDialProgress({ open: 0.4, index, count, stagger: 0 })).toBeCloseTo(0.4);
+		}
+	});
+
+	// A stagger wide enough to leave the last action no window would divide by
+	// zero or less, and a NaN written into a style freezes the action in place.
+	test("never yields NaN, even when the stagger eats the whole window", () => {
+		for (let index = 0; index < 20; index++) {
+			for (const open of [0, 0.5, 1]) {
+				const value = resolveDialProgress({ open, index, count: 20, stagger });
+				expect(Number.isNaN(value)).toBe(false);
+				expect(value).toBeGreaterThanOrEqual(0);
+				expect(value).toBeLessThanOrEqual(1);
+			}
+		}
+	});
+});
+
+describe("resolveFabPlacementStyle", () => {
+	test("pins bottom-end to the trailing edge, lifted by the offset and the inset", () => {
+		expect(resolveFabPlacementStyle({ placement: "bottom-end", offset: 16, insetBottom: 34 })).toEqual({
+			position: "absolute",
+			bottom: 50,
+			end: 16,
+		});
+	});
+
+	test("pins bottom-start to the leading edge", () => {
+		expect(resolveFabPlacementStyle({ placement: "bottom-start", offset: 16, insetBottom: 0 })).toEqual({
+			position: "absolute",
+			bottom: 16,
+			start: 16,
+		});
+	});
+
+	// Centred by spanning the row and centring inside it — `alignSelf` on an
+	// absolute child is read against the parent's cross axis, which is
+	// horizontal only in a column.
+	test("centres bottom-center by spanning the row", () => {
+		expect(resolveFabPlacementStyle({ placement: "bottom-center", offset: 24, insetBottom: 10 })).toEqual({
+			position: "absolute",
+			bottom: 34,
+			start: 0,
+			end: 0,
+			alignItems: "center",
+		});
+	});
+
+	test("uses logical edges only, so a right-to-left layout flips with no code", () => {
+		for (const placement of FAB_PLACEMENTS) {
+			const style = resolveFabPlacementStyle({ placement, offset: 16, insetBottom: 0 });
+			expect(style).not.toHaveProperty("left");
+			expect(style).not.toHaveProperty("right");
+		}
+	});
+});
+
+describe("resolveFabIconSize", () => {
+	test("maps sm to icon-md and both larger sizes to icon-lg", () => {
+		expect(resolveFabIconSize("sm")).toBe("md");
+		expect(resolveFabIconSize("md")).toBe("lg");
+		expect(resolveFabIconSize("lg")).toBe("lg");
+	});
+
+	test("the icon slot spells the same step as a class", () => {
+		for (const size of FAB_SIZES) {
+			expect(fabVariants({ size }).icon()).toBe(`size-icon-${resolveFabIconSize(size)}`);
+		}
+		expect(fabVariants({}).actionIcon()).toBe(`size-icon-${resolveFabIconSize("sm")}`);
+	});
+
+	test("names a step on the shared icon scale for every size", () => {
+		for (const size of FAB_SIZES) {
+			expect(ICON_SIZES).toContain(resolveFabIconSize(size));
+			expect(FAB_ICON_SIZE[size]).toBe(resolveFabIconSize(size));
+		}
+	});
+});
+
+describe("resolveLabelSide", () => {
+	test("puts the label chip on the side facing the screen", () => {
+		expect(resolveLabelSide("bottom-end")).toBe("start");
+		expect(resolveLabelSide("bottom-start")).toBe("end");
+		expect(resolveLabelSide("bottom-center")).toBe("top");
+	});
+});
+
+describe("FAB_FOREGROUND_TOKEN", () => {
+	test("pairs every variant with the foreground of its own surface", () => {
+		expect(FAB_FOREGROUND_TOKEN).toEqual({
+			primary: "primary-foreground",
+			secondary: "secondary-foreground",
+			surface: "elevated-foreground",
+			destructive: "destructive-foreground",
+		});
+	});
+});
+
+describe("fabVariants", () => {
+	const classes = (value: string) => value.split(/\s+/).filter(Boolean);
+
+	test("a round fab is a square footprint off the fab token, fully rounded", () => {
+		const sizes = { sm: "size-fab-sm", md: "size-fab-md", lg: "size-fab-lg" } as const;
+		for (const size of FAB_SIZES) {
+			const root = classes(fabVariants({ size }).root());
+			expect(root).toContain(sizes[size]);
+			expect(root).toContain("rounded-full");
+		}
+	});
+
+	test("an extended fab takes the height and pads its sides instead of fixing a width", () => {
+		const heights = { sm: "h-fab-sm", md: "h-fab-md", lg: "h-fab-lg" } as const;
+		for (const size of FAB_SIZES) {
+			const root = classes(fabVariants({ size, isExtended: true }).root());
+			expect(root).toContain(heights[size]);
+			expect(root).toContain("px-5");
+			expect(root).toContain("gap-2");
+			expect(root.some((name) => name.startsWith("size-"))).toBe(false);
+		}
+	});
+
+	test("fills each variant from its own semantic surface", () => {
+		const fills = {
+			primary: "bg-primary",
+			secondary: "bg-secondary",
+			surface: "bg-elevated",
+			destructive: "bg-destructive",
+		} as const;
+		for (const variant of FAB_VARIANTS) {
+			expect(classes(fabVariants({ variant }).root())).toContain(fills[variant]);
+		}
+		expect(classes(fabVariants({ variant: "surface" }).root())).toContain("border-border");
+	});
+
+	test("colours the label to match the variant's foreground token", () => {
+		for (const variant of FAB_VARIANTS) {
+			expect(classes(fabVariants({ variant }).label())).toContain(`text-${FAB_FOREGROUND_TOKEN[variant]}`);
+		}
+	});
+
+	// Rule 1: a View does not cascade colour to its Text.
+	test("puts no text colour on the root", () => {
+		for (const variant of FAB_VARIANTS) {
+			const root = classes(fabVariants({ variant }).root());
+			expect(root.some((name) => /^text-(primary|secondary|elevated|destructive)/.test(name))).toBe(false);
+		}
+	});
+
+	test("the label reads on the button's type scale", () => {
+		const label = classes(fabVariants({}).label());
+		expect(label).toContain("text-button-md");
+		expect(label).toContain("font-medium");
+	});
+
+	test("casts a shadow — the one floating thing in the kit", () => {
+		expect(classes(fabVariants({}).root())).toContain("shadow-lg");
+		expect(classes(fabVariants({}).actionButton())).toContain("shadow-lg");
+	});
+
+	test("fades when disabled", () => {
+		expect(classes(fabVariants({ isDisabled: true }).root())).toContain("opacity-50");
+		expect(classes(fabVariants({ isDisabled: false }).root())).not.toContain("opacity-50");
+	});
+
+	test("the scrim covers its container in the overlay token", () => {
+		const scrim = classes(fabVariants({}).scrim());
+		expect(scrim).toContain("absolute");
+		expect(scrim).toContain("inset-0");
+		expect(scrim).toContain("bg-overlay");
+	});
+
+	test("an action button is a small round surface", () => {
+		const button = classes(fabVariants({}).actionButton());
+		expect(button).toContain("size-fab-sm");
+		expect(button).toContain("rounded-full");
+		expect(button).toContain("bg-elevated");
+		expect(button).toContain("border-border");
+	});
+
+	test("an action's label chip sits on the popover surface", () => {
+		const chip = classes(fabVariants({}).actionLabel());
+		for (const name of ["bg-popover", "rounded-md", "px-2", "py-1"]) expect(chip).toContain(name);
+		expect(classes(fabVariants({}).actionLabelText())).toContain("text-popover-foreground");
+		expect(classes(fabVariants({}).actionLabelText())).toContain("text-sm");
+	});
+
+	test("the dial and each action are spaced by 12pt", () => {
+		expect(classes(fabVariants({}).dial())).toContain("gap-3");
+		expect(classes(fabVariants({}).action())).toContain("gap-3");
+	});
+
+	test("an action's anchor matches the trigger's width, so the two share a centre line", () => {
+		const anchors = { sm: "w-fab-sm", md: "w-fab-md", lg: "w-fab-lg" } as const;
+		for (const size of FAB_SIZES) {
+			expect(classes(fabVariants({ size }).actionAnchor())).toContain(anchors[size]);
+		}
+	});
+
+	test("lays an action out by the side its label sits on", () => {
+		expect(classes(fabVariants({ labelSide: "start" }).action())).toContain("flex-row");
+		expect(classes(fabVariants({ labelSide: "end" }).action())).toContain("flex-row-reverse");
+		expect(classes(fabVariants({ labelSide: "top" }).action())).toContain("flex-col");
+	});
+
+	test("aligns the dial with the trigger's edge", () => {
+		expect(classes(fabVariants({ labelSide: "start" }).dial())).toContain("items-end");
+		expect(classes(fabVariants({ labelSide: "end" }).dial())).toContain("items-start");
+		expect(classes(fabVariants({ labelSide: "top" }).dial())).toContain("items-center");
+	});
+});

package/src/components/fab/fab.variants.ts

@@ -0,0 +1,234 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { IconSize } from "../icon/icon.variants";
+
+/** 44, 56 and 64pt — `--spacing-fab-*` in `tokens.css`. */
+export const FAB_SIZES = ["sm", "md", "lg"] as const;
+
+export const FAB_VARIANTS = ["primary", "secondary", "surface", "destructive"] as const;
+
+/** Where a pinned fab sits along the bottom edge. Logical, so it flips under RTL. */
+export const FAB_PLACEMENTS = ["bottom-start", "bottom-center", "bottom-end"] as const;
+
+/** Which side of an action's button its label chip sits on. */
+export const FAB_LABEL_SIDES = ["start", "end", "top"] as const;
+
+export type FabSize = (typeof FAB_SIZES)[number];
+export type FabVariant = (typeof FAB_VARIANTS)[number];
+export type FabPlacement = (typeof FAB_PLACEMENTS)[number];
+export type FabLabelSide = (typeof FAB_LABEL_SIDES)[number];
+
+/** Distance from the screen's edges, before the safe-area inset. */
+export const FAB_DEFAULT_OFFSET = 16;
+
+/**
+ * How far behind the one before it each action starts, as a fraction of the
+ * dial's spring. 0.08 keeps a four-action dial's last window at three quarters
+ * of the spring, long enough to read as a cascade rather than a pop.
+ */
+export const FAB_DIAL_STAGGER = 0.08;
+
+/** The reduced-motion fade, and the glyph's turn under it, in ms. */
+export const FAB_REDUCED_MOTION_MS = 150;
+
+/** The glyph's turn at a fully open dial: a plus becomes a cross. */
+export const FAB_OPEN_ROTATION_DEG = 45;
+
+/**
+ * Theme token whose value colours a composed icon on each surface.
+ *
+ * Read through `useThemeColor` for an `Icon`'s `color`; the label reads the same
+ * token as a `text-*` class in {@link fabVariants}, and a test holds the two in
+ * step.
+ */
+export const FAB_FOREGROUND_TOKEN: Record<FabVariant, string> = {
+	primary: "primary-foreground",
+	secondary: "secondary-foreground",
+	surface: "elevated-foreground",
+	destructive: "destructive-foreground",
+};
+
+/**
+ * The step on the shared icon scale a fab's glyph is drawn at.
+ *
+ * Indexed rather than restated, the way a button's icon is: `sm` is a step
+ * down because a 44pt circle with a 20pt glyph reads as crowded, while 56 and 64
+ * both carry the larger glyph with room to spare.
+ */
+export const FAB_ICON_SIZE: Record<FabSize, IconSize> = {
+	sm: "md",
+	md: "lg",
+	lg: "lg",
+};
+
+export function resolveFabIconSize(size: FabSize): IconSize {
+	return FAB_ICON_SIZE[size];
+}
+
+/**
+ * The side of an action's button its label chip sits on: the side facing into
+ * the screen, so the chip never runs off the edge the dial is pinned to.
+ */
+export function resolveLabelSide(placement: FabPlacement): FabLabelSide {
+	switch (placement) {
+		case "bottom-start":
+			return "end";
+		case "bottom-center":
+			return "top";
+		default:
+			return "start";
+	}
+}
+
+export type FabPlacementStyle =
+	| { position: "absolute"; bottom: number; start: number }
+	| { position: "absolute"; bottom: number; end: number }
+	| { position: "absolute"; bottom: number; start: 0; end: 0; alignItems: "center" };
+
+/**
+ * The style of the box a pinned fab sits in.
+ *
+ * Bottom is the offset plus the safe-area inset, so a fab on a phone with a home
+ * indicator clears it by the same distance it clears the side.
+ *
+ * Centre spans the row and centres inside it rather than reaching for
+ * `alignSelf`: an absolute child's `alignSelf` is read on the parent's cross
+ * axis, which is horizontal only when the parent is a column — a fab written
+ * into a `flex-row` would centre vertically instead. Spanning costs touches
+ * nothing because the box is `pointerEvents="box-none"`.
+ *
+ * Logical edges only (`start` / `end`), so a right-to-left layout flips with no
+ * code here.
+ */
+export function resolveFabPlacementStyle({
+	placement,
+	offset,
+	insetBottom,
+}: {
+	placement: FabPlacement;
+	offset: number;
+	insetBottom: number;
+}): FabPlacementStyle {
+	const bottom = offset + insetBottom;
+	switch (placement) {
+		case "bottom-start":
+			return { position: "absolute", bottom, start: offset };
+		case "bottom-center":
+			return { position: "absolute", bottom, start: 0, end: 0, alignItems: "center" };
+		default:
+			return { position: "absolute", bottom, end: offset };
+	}
+}
+
+/**
+ * One action's share of the dial's spring, 0–1.
+ *
+ * One spring drives the whole dial; each action reads its own window of it,
+ * starting `index × stagger` in and running to the end. Index 0 is the action
+ * nearest the trigger, so the dial unfolds outward. Because every window is a
+ * pure function of the one value, reversing halfway through opening simply runs
+ * the same windows backwards — there are no per-action timers to fall out of
+ * step.
+ *
+ * Clamped at both ends because the spring overshoots, and floored on the window
+ * so a stagger too wide for the count degrades to a step rather than a NaN —
+ * a NaN written into a style freezes the action where it stands.
+ *
+ * A worklet, so the dial's animated styles call it on the UI thread.
+ */
+export function resolveDialProgress({
+	open,
+	index,
+	count,
+	stagger,
+}: {
+	open: number;
+	index: number;
+	count: number;
+	stagger: number;
+}): number {
+	"worklet";
+	const span = 1 - Math.max(count - 1, 0) * stagger;
+	const window = span > 0.0001 ? span : 0.0001;
+	const local = (open - index * stagger) / window;
+	return local < 0 ? 0 : local > 1 ? 1 : local;
+}
+
+/**
+ * Styling for every part of a fab and its dial.
+ *
+ * One slotted `tv()` so `size` and `variant` are declared once. A size names
+ * tokens: `size-fab-md` for a round fab, `h-fab-md` for an extended one, and the
+ * action anchor's `w-fab-md`, which centres a small action button on the
+ * trigger's own centre line. The values live in `tokens.css`.
+ *
+ * The root holds no `text-*` (rule 1); the label slot carries the colour, and a
+ * composed icon reads {@link FAB_FOREGROUND_TOKEN}.
+ *
+ * `shadow-lg` is deliberate and unique. Nothing else in the package casts a
+ * shadow; a fab is the one thing floating over content, and without one it
+ * reads as a sticker on the list rather than a control above it. No
+ * `overflow-hidden` on the root for the same reason — a clip would cut the
+ * shadow off on Android.
+ *
+ * Free of React Native imports so it stays unit-testable.
+ */
+export const fabVariants = tv({
+	slots: {
+		root: "flex-row items-center justify-center rounded-full shadow-lg",
+		label: "text-button-md font-medium",
+		/** Edge length an `Icon` composed into the fab inherits. */
+		icon: "",
+		scrim: "absolute inset-0 bg-overlay",
+		dial: "gap-3",
+		action: "items-center gap-3",
+		actionAnchor: "items-center",
+		actionButton: "size-fab-sm items-center justify-center rounded-full border border-border bg-elevated shadow-lg",
+		actionIcon: "size-icon-md",
+		actionLabel: "rounded-md bg-popover px-2 py-1",
+		actionLabelText: "text-popover-foreground text-sm",
+	},
+	variants: {
+		size: {
+			sm: { icon: "size-icon-md", actionAnchor: "w-fab-sm" },
+			md: { icon: "size-icon-lg", actionAnchor: "w-fab-md" },
+			lg: { icon: "size-icon-lg", actionAnchor: "w-fab-lg" },
+		},
+		variant: {
+			primary: { root: "bg-primary", label: "text-primary-foreground" },
+			secondary: { root: "bg-secondary", label: "text-secondary-foreground" },
+			surface: { root: "border border-border bg-elevated", label: "text-elevated-foreground" },
+			destructive: { root: "bg-destructive", label: "text-destructive-foreground" },
+		},
+		isExtended: {
+			true: { root: "gap-2 px-5" },
+			false: {},
+		},
+		isDisabled: {
+			true: { root: "opacity-50", actionButton: "opacity-50", actionLabel: "opacity-50" },
+			false: {},
+		},
+		labelSide: {
+			start: { dial: "items-end", action: "flex-row" },
+			end: { dial: "items-start", action: "flex-row-reverse" },
+			top: { dial: "items-center", action: "flex-col" },
+		},
+	},
+	compoundVariants: [
+		{ size: "sm", isExtended: false, class: { root: "size-fab-sm" } },
+		{ size: "md", isExtended: false, class: { root: "size-fab-md" } },
+		{ size: "lg", isExtended: false, class: { root: "size-fab-lg" } },
+		{ size: "sm", isExtended: true, class: { root: "h-fab-sm" } },
+		{ size: "md", isExtended: true, class: { root: "h-fab-md" } },
+		{ size: "lg", isExtended: true, class: { root: "h-fab-lg" } },
+	],
+	defaultVariants: {
+		size: "md",
+		variant: "primary",
+		isExtended: false,
+		isDisabled: false,
+		labelSide: "start",
+	},
+});
+
+export type FabVariantProps = VariantProps<typeof fabVariants>;

package/src/components/fab/index.ts

@@ -0,0 +1,37 @@
+export { Fab, type FabProps } from "./fab";
+export {
+	type FabContextValue,
+	type FabGroupContextValue,
+	FabProvider,
+	useFab,
+	useFabContext,
+	useFabGroup,
+	useFabGroupContext,
+} from "./fab.context";
+export type { FabSharedProps } from "./fab.types";
+export {
+	FAB_DEFAULT_OFFSET,
+	FAB_DIAL_STAGGER,
+	FAB_FOREGROUND_TOKEN,
+	FAB_ICON_SIZE,
+	FAB_LABEL_SIDES,
+	FAB_OPEN_ROTATION_DEG,
+	FAB_PLACEMENTS,
+	FAB_REDUCED_MOTION_MS,
+	FAB_SIZES,
+	FAB_VARIANTS,
+	type FabLabelSide,
+	type FabPlacement,
+	type FabPlacementStyle,
+	type FabSize,
+	type FabVariant,
+	type FabVariantProps,
+	fabVariants,
+	resolveDialProgress,
+	resolveFabIconSize,
+	resolveFabPlacementStyle,
+	resolveLabelSide,
+} from "./fab.variants";
+export type { FabActionProps } from "./fab-action";
+export type { FabGroupProps } from "./fab-group";
+export type { FabLabelProps } from "./fab-label";

package/src/components/feedback/AGENTS.md

@@ -0,0 +1,95 @@
+# Feedback
+
+A dialog for writing: "What should we fix first?", a bug report, a one-question survey. It is a
+[`Dialog`](../dialog/AGENTS.md) whose text field sits in a **recessed well** that says "type here",
+with the actions on the band around it. Compound root plus `Feedback.Trigger`, `Feedback.Content`,
+`Feedback.Panel`, `Feedback.Title`, `Feedback.Close`, `Feedback.Field`, `Feedback.Footer`,
+`Feedback.Action`, `Feedback.Cancel` and `Feedback.Submit`, and `useFeedback()`.
+
+`import { Feedback } from "@delacour/react-native-ui/feedback";`
+
+Not for confirmations or warnings — those are a `Dialog`. Like every overlay it draws through
+`Overlay.Portal`, so the app mounts `OverlayProvider` once at its root.
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/feedback` |
+| `feedback.tsx` | Root — the open state, the draft, the send state — wrapping a `Dialog`, and the `Object.assign` surface |
+| `feedback.context.tsx` | **Leaf.** `FeedbackProvider`, `useFeedback()`, `useFeedbackContext()`, `useFeedbackPart()` |
+| `feedback-trigger.tsx` | `Feedback.Trigger` — `Dialog.Trigger` |
+| `feedback-content.tsx` | `Feedback.Content` — `Dialog.Content` on the muted band, tighter padding |
+| `feedback-panel.tsx` | `Feedback.Panel` — the well, in a clip that eases to its measured height |
+| `feedback-title.tsx` | `Feedback.Title` — `Dialog.Title`; publishes a string title as the field's label |
+| `feedback-close.tsx` | `Feedback.Close` — `Dialog.Close`, in the well's corner |
+| `feedback-field.tsx` | `Feedback.Field` — a bare multiline `TextInput` bound to the draft |
+| `feedback-footer.tsx` | `Feedback.Footer` |
+| `feedback-action.tsx` | `Feedback.Action` — a `secondary` `Button` for custom actions |
+| `feedback-cancel.tsx` | `Feedback.Cancel` — closes, keeps the draft |
+| `feedback-submit.tsx` | `Feedback.Submit` — the gate, the trimmed value, the wait on a promise |
+| `feedback.variants.ts` | The slotted `tv()`, the row and motion constants, `canSubmitFeedback` and the field-height resolvers — no RN imports |
+| `feedback.variants.test.ts` | Slots, tokens in both themes, the submit gate, the field heights |
+
+## Design
+
+- **Everything a dialog does is Dialog's.** `Feedback` renders a `Dialog` and its parts *are*
+  Dialog's parts with classes merged over them — open state, portal, scrim, motion, the `modal`
+  band, the back button, the escape gesture, focus on open and return, and the keyboard lift that
+  keeps the footer above the keyboard. Nothing is restated, so a fix to Dialog is a fix here. The
+  import is `../dialog`: Dialog never imports Feedback, so there is no cycle to route around.
+- **The shell is the band; the panel is the well.** `Feedback.Content` merges `bg-muted` and `p-2`
+  over Dialog's `bg-popover` and `p-5` through the same `tv` merge, so the corner, hairline and
+  width cap stay Dialog's. `Feedback.Panel` is `bg-background` with `rounded-md` — one step down
+  the corner ramp from the card it sits in, so the two read as nested — and a hairline. The well's
+  page colour against the band's muted one is what says "type here" without a field border.
+- **The field has no box.** `Feedback.Field` is a raw `TextInput`, not an `Input`: the well is
+  its box, and an `Input` would draw a second border inside the first. It restates `font-sans` for
+  `Input`'s reason (a `TextInput` inherits nothing), sets `text-input-md` with paragraph leading
+  (`leading-6`, `FEEDBACK_FIELD_LINE_HEIGHT`, pinned by a test), and takes `Input`'s `accent-*`
+  placeholder, caret and selection classes from `input.variants` — a leaf, so no cycle.
+- **The field is floored at `minRows` and capped at `maxRows`.** Six rows and twelve by default,
+  as a style (`resolveFeedbackFieldHeightStyle`) because a runtime number cannot be a class.
+  Between the two React Native's multiline `TextInput` sizes itself. `maxRows` is not in the
+  original spec: without a cap a long message grows the card until Dialog's lift, which keeps the
+  title on screen first, has to give up the footer to the keyboard.
+- **The draft lives on the root, above `Dialog.Content`.** Content unmounts when the exit animation
+  ends; the root does not, so an uncontrolled draft survives a close and a reopen. Cancel, Close,
+  the scrim and back all keep it — a long message put down for a moment must not be thrown away.
+  `useFeedback().clear()` is the one way to empty it.
+- **Submit never closes.** `canSubmitFeedback` gates it (empty and whitespace are empty;
+  `canSubmitEmpty` lets an empty one through for chips or a rating; disabled outranks both), and
+  `onSubmit` gets the trimmed text. A returned promise turns on the button's loading state and
+  makes the field read-only until it settles — and the dialog is still open, so a failure can be
+  shown in the well with the draft intact. The caller closes and clears on success. A rejection is
+  not swallowed: handle failures inside `onSubmit`, or the app's unhandled-rejection reporting sees
+  it, which is better than a send that failed silently.
+- **The well eases between heights; the shell never jumps.** A multi-step flow (rating → text →
+  thanks) is the caller swapping the panel's and footer's children. `Feedback.Panel` measures the
+  well with `onLayout` and animates a clip around it to that height over `FEEDBACK_PANEL_RESIZE_MS`
+  (200ms). The spec named a Reanimated `LinearTransition` on the panel; that animates the panel's
+  frame inside a shell that has already snapped to its final size and re-centred, which is exactly
+  the jump to avoid. A real height changing on every frame moves the shell through ordinary layout
+  and keeps it centred — Accordion's reasoning for its own panel. The first layout lands without
+  animating, and under reduce motion every change does.
+- **The field's label is the title.** `Feedback.Title` publishes its children to the root when
+  they are a plain string, and `Feedback.Field` uses that as its default `accessibilityLabel`, so
+  a screen reader announces the question rather than only the placeholder. A non-string title
+  publishes nothing; pass `accessibilityLabel` then.
+- **Close sits in the well, not the shell.** `Feedback.Close` is `Dialog.Close` with its slot
+  re-pinned to the well's corner (`top-3 right-3`, against the panel's `p-4`); the title keeps
+  Dialog's `pr-8` clearance.
+- **No blur backdrop.** As for every overlay: frosted scrims need `expo-blur`, not a peer.
+
+## Testing
+
+`bun test` reaches `feedbackVariants`, the tokens in both themes, `canSubmitFeedback` and the
+field-height resolvers. Opening, the submit gate, the async send, the draft across close and
+reopen, the keyboard, the multi-step resize and every dismissal path are verified on a simulator
+through `/feedback` in the playground.
+
+Preview media is held back with the rest of the overlays (see `docs/plans/overlays/README.md`).
+When a capture tool is back, re-add `capture` with these settings and run
+`bun run previews -- -- --only feedback`: `basic` `{ flow: "feedback/basic", frame: "device", hero: true }`,
+and `sending`, `multi-step` `{ flow: "feedback/<id>", frame: "device" }`. The flows are in
+`.argent/flows/previews/feedback/`.

package/src/components/feedback/feedback-action.tsx

@@ -0,0 +1,16 @@
+import type { ReactElement } from "react";
+import { Button, type ButtonProps } from "../button";
+
+export type FeedbackActionProps = ButtonProps;
+
+/**
+ * A custom footer action — "Skip", "Back", "Attach screenshot" — as a
+ * `secondary` `Button`. Pass `variant` to change it.
+ *
+ * @example
+ * <Feedback.Action onPress={back}>Back</Feedback.Action>
+ */
+export function FeedbackAction({ variant = "secondary", ...props }: FeedbackActionProps): ReactElement {
+	return <Button variant={variant} {...props} />;
+}
+FeedbackAction.displayName = "DelacourUI.Feedback.Action";