@delacour/react-native-ui 0.1.0-alpha.20261007125731 → 0.1.0-alpha.20261007130133

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@delacour/react-native-ui",
-	"version": "0.1.0-alpha.20261007125731",
+	"version": "0.1.0-alpha.20261007130133",
 	"description": "React Native UI components — Uniwind, Reanimated, Gesture Handler",
 	"type": "module",
 	"license": "MIT",
@@ -48,6 +48,7 @@
 		"./dialog": "./src/components/dialog/index.ts",
 		"./drawer": "./src/components/drawer/index.ts",
 		"./empty-state": "./src/components/empty-state/index.ts",
+		"./feedback": "./src/components/feedback/index.ts",
 		"./field": "./src/components/field/index.ts",
 		"./icon": "./src/components/icon/index.ts",
 		"./input": "./src/components/input/index.ts",
@@ -108,8 +109,8 @@
 	},
 	"peerDependencies": {
 		"@central-icons-react-native/round-outlined-radius-1-stroke-1.5": "^1.1",
-		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261007125731",
-		"@delacour/react-native-charts": "0.1.0-alpha.20261007125731",
+		"@delacour/react-native-bottom-sheet": "0.1.0-alpha.20261007130133",
+		"@delacour/react-native-charts": "0.1.0-alpha.20261007130133",
 		"@legendapp/list": ">=3.3",
 		"expo-linear-gradient": ">=15",
 		"expo-router": ">=57",

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";

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

@@ -0,0 +1,34 @@
+import { type ReactElement, useCallback } from "react";
+import { Button, type ButtonProps } from "../button";
+import { useFeedbackPart } from "./feedback.context";
+
+export type FeedbackCancelProps = ButtonProps;
+
+/**
+ * Closes the dialog and keeps the draft — a `secondary` `Button` labelled
+ * "Cancel" unless given children. Clearing on cancel would throw away a long
+ * message the user only meant to put down for a moment.
+ *
+ * @example
+ * <Feedback.Cancel />
+ */
+export function FeedbackCancel({
+	variant = "secondary",
+	children = "Cancel",
+	onPress,
+	...props
+}: FeedbackCancelProps): ReactElement {
+	const { close } = useFeedbackPart("Feedback.Cancel");
+
+	const handlePress = useCallback(() => {
+		close();
+		onPress?.();
+	}, [close, onPress]);
+
+	return (
+		<Button onPress={handlePress} variant={variant} {...props}>
+			{children}
+		</Button>
+	);
+}
+FeedbackCancel.displayName = "DelacourUI.Feedback.Cancel";

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

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import { Dialog, type DialogCloseProps } from "../dialog";
+import { feedbackVariants } from "./feedback.variants";
+
+export type FeedbackCloseProps = DialogCloseProps;
+
+/**
+ * The ✕ in the well's top-right corner — `Dialog.Close`, positioned against
+ * the panel rather than the shell. `Feedback.Title`'s `pr-8` reserves its
+ * clearance. Labelled `"Close"`; the draft is kept.
+ *
+ * With `asChild` it donates the close to its child, as `Dialog.Close` does.
+ *
+ * @example
+ * <Feedback.Close />
+ */
+export function FeedbackClose(props: FeedbackCloseProps): ReactElement {
+	if (props.asChild) return <Dialog.Close {...props} />;
+	return <Dialog.Close {...props} className={feedbackVariants().close({ className: props.className })} />;
+}
+FeedbackClose.displayName = "DelacourUI.Feedback.Close";

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

@@ -0,0 +1,24 @@
+import type { ReactElement } from "react";
+import { Dialog, type DialogContentProps } from "../dialog";
+import { feedbackVariants } from "./feedback.variants";
+
+export type FeedbackContentProps = DialogContentProps;
+
+/**
+ * The shell — a `Dialog.Content` on the muted band.
+ *
+ * Portal, scrim, motion, keyboard lift, back button, escape and focus are all
+ * Dialog's. This only swaps the card's fill for `bg-muted` and tightens its
+ * padding, so the `Feedback.Panel` inside reads as a well sunk into it and the
+ * footer's actions sit on the band around it.
+ *
+ * @example
+ * <Feedback.Content>
+ *   <Feedback.Panel>…</Feedback.Panel>
+ *   <Feedback.Footer>…</Feedback.Footer>
+ * </Feedback.Content>
+ */
+export function FeedbackContent({ className, ...props }: FeedbackContentProps): ReactElement {
+	return <Dialog.Content className={feedbackVariants().content({ className })} {...props} />;
+}
+FeedbackContent.displayName = "DelacourUI.Feedback.Content";

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

@@ -0,0 +1,70 @@
+import { type ReactElement, useCallback } from "react";
+import { TextInput, type TextInputProps } from "react-native";
+import { resolvePlaceholderAccentClass, resolveSelectionAccentClass } from "../input/input.variants";
+import { useFeedbackPart } from "./feedback.context";
+import { feedbackVariants, resolveFeedbackFieldHeightStyle } from "./feedback.variants";
+
+export type FeedbackFieldProps = Omit<TextInputProps, "value" | "onChangeText" | "multiline"> & {
+	className?: string;
+	/** Rows before it grows. Default 6. */
+	minRows?: number;
+	/** Rows it grows to before it scrolls. Default 12. */
+	maxRows?: number;
+	/** Read-only — while sending, say. A send in flight makes it read-only on its own. */
+	isDisabled?: boolean;
+};
+
+/**
+ * Where the message is written: a bare multiline `TextInput` with no box of
+ * its own, because the well around it is the box.
+ *
+ * The draft is the root's — `value` and `onChangeText` are withheld — so it
+ * survives the dialog closing and reopening, and `useFeedback().clear()` is
+ * the one way to empty it. It is floored at `minRows` and grows to `maxRows`
+ * before it scrolls (`resolveFeedbackFieldHeightStyle`), as a style, since a
+ * runtime number cannot be a Tailwind class.
+ *
+ * While a promise from `Feedback.Submit` is in flight it is read-only, so what
+ * is being sent is what stays on screen. Its label defaults to the title's
+ * text when the title is a plain string.
+ *
+ * Placeholder, caret and selection take `Input`'s `accent-*` defaults.
+ *
+ * @example
+ * <Feedback.Field placeholder="Tell us what got in your way" />
+ */
+export function FeedbackField({
+	className,
+	minRows,
+	maxRows,
+	isDisabled = false,
+	accessibilityLabel,
+	editable,
+	style,
+	...props
+}: FeedbackFieldProps): ReactElement {
+	const { value, setValue, isSending, titleText } = useFeedbackPart("Feedback.Field");
+	const isReadOnly = isDisabled || isSending;
+	const selectionAccent = resolveSelectionAccentClass({});
+
+	const handleChangeText = useCallback((text: string) => setValue(text), [setValue]);
+
+	return (
+		<TextInput
+			accessibilityLabel={accessibilityLabel ?? titleText}
+			accessibilityState={{ disabled: isReadOnly }}
+			className={feedbackVariants().field({ className })}
+			cursorColorClassName={selectionAccent}
+			placeholderTextColorClassName={resolvePlaceholderAccentClass()}
+			selectionColorClassName={selectionAccent}
+			style={[resolveFeedbackFieldHeightStyle({ maxRows, minRows }), style]}
+			textAlignVertical="top"
+			{...props}
+			editable={isReadOnly ? false : editable}
+			multiline
+			onChangeText={handleChangeText}
+			value={value}
+		/>
+	);
+}
+FeedbackField.displayName = "DelacourUI.Feedback.Field";

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

@@ -0,0 +1,21 @@
+import type { ReactElement } from "react";
+import { View, type ViewProps } from "react-native";
+import { feedbackVariants } from "./feedback.variants";
+
+export type FeedbackFooterProps = ViewProps & { className?: string };
+
+/**
+ * The actions, on the band under the well — an end-aligned row, inset less
+ * than the well so the buttons line up with the shell's edge rather than the
+ * well's text.
+ *
+ * @example
+ * <Feedback.Footer>
+ *   <Feedback.Cancel />
+ *   <Feedback.Submit onSubmit={send} />
+ * </Feedback.Footer>
+ */
+export function FeedbackFooter({ className, ...props }: FeedbackFooterProps): ReactElement {
+	return <View className={feedbackVariants().footer({ className })} {...props} />;
+}
+FeedbackFooter.displayName = "DelacourUI.Feedback.Footer";

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

@@ -0,0 +1,54 @@
+import { type ReactElement, useCallback } from "react";
+import { type LayoutChangeEvent, View, type ViewProps } from "react-native";
+import Animated, { useAnimatedStyle, useReducedMotion, useSharedValue, withTiming } from "react-native-reanimated";
+import { FEEDBACK_PANEL_RESIZE_MS, feedbackVariants } from "./feedback.variants";
+
+export type FeedbackPanelProps = ViewProps & { className?: string };
+
+/** No height measured yet: the clip wraps its content until the first layout. */
+const UNMEASURED = -1;
+
+/**
+ * The recessed well the title, the close and the field sit in.
+ *
+ * **Its height is measured and animated, never laid out.** The well is drawn
+ * inside a clip whose height follows the well's own `onLayout` on a short
+ * timing, so when a multi-step flow swaps the panel's children — a rating, then
+ * a message, then thanks — the clip eases to the new height. The shell grows
+ * with it through ordinary layout and stays centred on every frame, so it never
+ * jumps; a layout transition on the panel alone would animate the panel inside
+ * a shell that had already snapped to its final size. The first layout lands
+ * without animating, and under reduce motion every change does.
+ *
+ * @example
+ * <Feedback.Panel>
+ *   <Feedback.Title>What should we fix first?</Feedback.Title>
+ *   <Feedback.Close />
+ *   <Feedback.Field placeholder="Tell us what got in your way" />
+ * </Feedback.Panel>
+ */
+export function FeedbackPanel({ className, onLayout, ...props }: FeedbackPanelProps): ReactElement {
+	const isReduced = useReducedMotion();
+	const height = useSharedValue(UNMEASURED);
+
+	const handleLayout = useCallback(
+		(event: LayoutChangeEvent) => {
+			const next = event.nativeEvent.layout.height;
+			height.value =
+				height.value === UNMEASURED || isReduced ? next : withTiming(next, { duration: FEEDBACK_PANEL_RESIZE_MS });
+			onLayout?.(event);
+		},
+		[height, isReduced, onLayout]
+	);
+
+	const clipStyle = useAnimatedStyle(() => (height.value === UNMEASURED ? {} : { height: height.value }));
+
+	const slots = feedbackVariants();
+
+	return (
+		<Animated.View className={slots.clip()} style={clipStyle}>
+			<View className={slots.panel({ className })} onLayout={handleLayout} {...props} />
+		</Animated.View>
+	);
+}
+FeedbackPanel.displayName = "DelacourUI.Feedback.Panel";

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

@@ -0,0 +1,74 @@
+import { type ReactElement, useCallback } from "react";
+import { Button, type ButtonProps } from "../button";
+import { useFeedbackPart } from "./feedback.context";
+import { canSubmitFeedback } from "./feedback.variants";
+
+export type FeedbackSubmitProps = Omit<ButtonProps, "onPress"> & {
+	/** Receives the trimmed message. Does NOT close — sending has to finish first. */
+	onSubmit: (value: string) => void | Promise<void>;
+	/** Allow submitting an empty message (e.g. when chips were picked). Default false. */
+	canSubmitEmpty?: boolean;
+};
+
+/** Whether a value is a promise, without trusting `instanceof` across realms. */
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+	return typeof value === "object" && value !== null && typeof (value as PromiseLike<unknown>).then === "function";
+}
+
+/**
+ * Sends the message — a primary `Button` labelled "Send" unless given children.
+ *
+ * Disabled while `canSubmitFeedback` says no: an empty or whitespace draft,
+ * unless `canSubmitEmpty`. `onSubmit` receives the trimmed text.
+ *
+ * **It never closes the dialog.** When `onSubmit` returns a promise the button
+ * shows its loading state and the field turns read-only until the promise
+ * settles, and then the dialog is still open — so a failure can be shown in
+ * the well with the draft intact. Close and clear from `onSubmit` on success,
+ * through `useFeedback()` or controlled state. Handle a failure inside
+ * `onSubmit`: a rejection is not caught here, so it still reaches the app's
+ * unhandled-rejection reporting rather than vanishing.
+ *
+ * @example
+ * <Feedback.Submit
+ *   onSubmit={async (message) => {
+ *     await send(message);
+ *     clear();
+ *     close();
+ *   }}
+ * />
+ */
+export function FeedbackSubmit({
+	onSubmit,
+	canSubmitEmpty = false,
+	isDisabled = false,
+	isLoading = false,
+	children = "Send",
+	...props
+}: FeedbackSubmitProps): ReactElement {
+	const { value, isSending, setSending } = useFeedbackPart("Feedback.Submit");
+	const canSubmit = canSubmitFeedback({ canSubmitEmpty, isDisabled, value });
+
+	const handlePress = useCallback(() => {
+		if (!canSubmit || isSending) return;
+		const result = onSubmit(value.trim());
+		if (!isPromiseLike(result)) return;
+
+		setSending(true);
+		const settle = () => setSending(false);
+		void Promise.resolve(result).finally(settle);
+	}, [canSubmit, isSending, onSubmit, setSending, value]);
+
+	return (
+		<Button
+			isDisabled={!canSubmit}
+			isLoading={isLoading || isSending}
+			onPress={handlePress}
+			variant="primary"
+			{...props}
+		>
+			{children}
+		</Button>
+	);
+}
+FeedbackSubmit.displayName = "DelacourUI.Feedback.Submit";

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

@@ -0,0 +1,34 @@
+import { type ReactElement, useEffect } from "react";
+import { Dialog, type DialogTitleProps } from "../dialog";
+import { useFeedbackPart } from "./feedback.context";
+import { feedbackVariants } from "./feedback.variants";
+
+export type FeedbackTitleProps = DialogTitleProps;
+
+/**
+ * The question the dialog asks — a `Dialog.Title`, inside the well.
+ *
+ * It is what the dialog is labelled by and where accessibility focus lands on
+ * open, exactly as in a `Dialog`. When its children are a plain string, that
+ * string also becomes `Feedback.Field`'s default `accessibilityLabel`, so the
+ * field announces the question rather than only its placeholder.
+ *
+ * @example
+ * <Feedback.Title>What should we fix first?</Feedback.Title>
+ */
+export function FeedbackTitle({ className, children, ...props }: FeedbackTitleProps): ReactElement {
+	const { setTitleText } = useFeedbackPart("Feedback.Title");
+	const text = typeof children === "string" ? children : undefined;
+
+	useEffect(() => {
+		setTitleText(text);
+		return () => setTitleText(undefined);
+	}, [setTitleText, text]);
+
+	return (
+		<Dialog.Title className={feedbackVariants().title({ className })} {...props}>
+			{children}
+		</Dialog.Title>
+	);
+}
+FeedbackTitle.displayName = "DelacourUI.Feedback.Title";

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

@@ -0,0 +1,20 @@
+import type { ReactElement } from "react";
+import { Dialog, type DialogTriggerProps } from "../dialog";
+
+export type FeedbackTriggerProps = DialogTriggerProps;
+
+/**
+ * The control that opens the feedback dialog — `Dialog.Trigger`, unchanged.
+ *
+ * `asChild` donates the open to a `Button` rather than wrapping it, for the
+ * reason `Dialog.Trigger` gives: two tap gestures nested are not simultaneous.
+ *
+ * @example
+ * <Feedback.Trigger asChild>
+ *   <Button variant="secondary">Give feedback</Button>
+ * </Feedback.Trigger>
+ */
+export function FeedbackTrigger(props: FeedbackTriggerProps): ReactElement {
+	return <Dialog.Trigger {...props} />;
+}
+FeedbackTrigger.displayName = "DelacourUI.Feedback.Trigger";

package/src/components/feedback/feedback.context.tsx

@@ -0,0 +1,73 @@
+import { createContext, type ReactElement, type ReactNode, use } from "react";
+
+export type FeedbackContextValue = {
+	/** The draft as typed — untrimmed. */
+	value: string;
+	/** Replaces the draft. Reports through `onValueChange`. */
+	setValue: (value: string) => void;
+	/** Whether the dialog is open. */
+	isOpen: boolean;
+	/** Closes the dialog. The draft is kept. */
+	close: () => void;
+	/** Empties the draft — after a successful send, say. */
+	clear: () => void;
+};
+
+/** What the parts share that a caller has no use for. */
+export type FeedbackInternalValue = FeedbackContextValue & {
+	/** Whether a promise `onSubmit` returned is still in flight. */
+	isSending: boolean;
+	setSending: (isSending: boolean) => void;
+	/** The title's text when it is a plain string — the field's default label. */
+	titleText: string | undefined;
+	setTitleText: (text: string | undefined) => void;
+};
+
+const FeedbackContext = createContext<FeedbackInternalValue | null>(null);
+
+/**
+ * Supplies the feedback dialog's draft and send state to its parts.
+ *
+ * Its own module, importing nothing but React, so a part can read it without
+ * importing `./feedback` — that import would close a cycle, and Metro serves a
+ * partially initialised module for one.
+ */
+export function FeedbackProvider({
+	value,
+	children,
+}: {
+	value: FeedbackInternalValue;
+	children: ReactNode;
+}): ReactElement {
+	return <FeedbackContext value={value}>{children}</FeedbackContext>;
+}
+FeedbackProvider.displayName = "DelacourUI.Feedback.Provider";
+
+/** The enclosing feedback dialog's context, or null outside a `<Feedback>`. */
+export function useFeedbackContext(): FeedbackContextValue | null {
+	return use(FeedbackContext);
+}
+
+/**
+ * Reads the enclosing feedback dialog's draft, its setters and its open state.
+ *
+ * Lets a custom child — a row of chips, a rating step — read or replace the
+ * draft, and lets an `onSubmit` close and clear once the send has gone through.
+ * Throws outside a `<Feedback>`.
+ */
+export function useFeedback(): FeedbackContextValue {
+	const context = use(FeedbackContext);
+	if (!context) {
+		throw new Error("useFeedback must be called inside a <Feedback>.");
+	}
+	return context;
+}
+
+/** The full context, for a part that cannot work without one. Internal. */
+export function useFeedbackPart(component: string): FeedbackInternalValue {
+	const context = use(FeedbackContext);
+	if (!context) {
+		throw new Error(`${component} must be rendered inside a <Feedback>.`);
+	}
+	return context;
+}

package/src/components/feedback/feedback.tsx

@@ -0,0 +1,135 @@
+import { type ReactElement, type ReactNode, useCallback, useMemo, useState } from "react";
+import { useControllableState } from "../../hooks/use-controllable-state";
+import { Dialog } from "../dialog";
+import { type FeedbackInternalValue, FeedbackProvider } from "./feedback.context";
+import { FeedbackAction } from "./feedback-action";
+import { FeedbackCancel } from "./feedback-cancel";
+import { FeedbackClose } from "./feedback-close";
+import { FeedbackContent } from "./feedback-content";
+import { FeedbackField } from "./feedback-field";
+import { FeedbackFooter } from "./feedback-footer";
+import { FeedbackPanel } from "./feedback-panel";
+import { FeedbackSubmit } from "./feedback-submit";
+import { FeedbackTitle } from "./feedback-title";
+import { FeedbackTrigger } from "./feedback-trigger";
+
+export type FeedbackProps = {
+	/** Whether the dialog is open. Pass it to control the dialog; omit it and the dialog holds its own state. */
+	isOpen?: boolean;
+	/** Whether an uncontrolled dialog starts open. Default false. */
+	defaultOpen?: boolean;
+	/** Called with the new value whenever the dialog opens or closes, from any path. */
+	onOpenChange?: (isOpen: boolean) => void;
+	/** The draft. Pass it to control the text; omit it and the dialog keeps its own draft. */
+	value?: string;
+	/** The draft an uncontrolled dialog starts with. Default "". */
+	defaultValue?: string;
+	/** Called with the draft on every keystroke, and on `clear()`. */
+	onValueChange?: (value: string) => void;
+	/** Whether a scrim tap, Android back and the iOS escape gesture close it. Default true. */
+	isDismissible?: boolean;
+	children: ReactNode;
+};
+
+function FeedbackRoot({
+	isOpen,
+	defaultOpen = false,
+	onOpenChange,
+	value,
+	defaultValue = "",
+	onValueChange,
+	isDismissible = true,
+	children,
+}: FeedbackProps): ReactElement {
+	const [open, setOpen] = useControllableState({ defaultValue: defaultOpen, onChange: onOpenChange, value: isOpen });
+	const [draft, setDraft] = useControllableState({ defaultValue, onChange: onValueChange, value });
+	const [isSending, setSending] = useState(false);
+	const [titleText, setTitleText] = useState<string | undefined>(undefined);
+
+	const close = useCallback(() => {
+		if (open) setOpen(false);
+	}, [open, setOpen]);
+	const clear = useCallback(() => setDraft(""), [setDraft]);
+
+	const context = useMemo<FeedbackInternalValue>(
+		() => ({
+			clear,
+			close,
+			isOpen: open,
+			isSending,
+			setSending,
+			setTitleText,
+			setValue: setDraft,
+			titleText,
+			value: draft,
+		}),
+		[clear, close, draft, isSending, open, setDraft, titleText]
+	);
+
+	// The draft lives here, above `Dialog.Content`, which unmounts once the exit
+	// animation ends — so an uncontrolled draft survives a close and a reopen.
+	return (
+		<Dialog isDismissible={isDismissible} isOpen={open} onOpenChange={setOpen}>
+			<FeedbackProvider value={context}>{children}</FeedbackProvider>
+		</Dialog>
+	);
+}
+
+/**
+ * A dialog for writing — "What should we fix first?", a bug report, a
+ * one-question survey.
+ *
+ * It is a `Dialog` whose text field sits in a recessed well, with the actions
+ * on the band around it. Open state, portal, scrim, back, escape, focus and the
+ * keyboard lift are all Dialog's; this adds the draft, a submit that waits for
+ * the send, and a well that eases between heights when a multi-step flow swaps
+ * its content. Not for confirmations or warnings — use a `Dialog`.
+ *
+ * The draft is kept across close and reopen while uncontrolled;
+ * `useFeedback().clear()` empties it. `Feedback.Submit` never closes the
+ * dialog: close from `onSubmit` once the send has gone through.
+ *
+ * Draws through `Overlay.Portal`, so the app needs `OverlayProvider` mounted
+ * once at its root.
+ *
+ * @example
+ * <Feedback>
+ *   <Feedback.Trigger asChild>
+ *     <Button variant="secondary">Give feedback</Button>
+ *   </Feedback.Trigger>
+ *   <Feedback.Content>
+ *     <Feedback.Panel>
+ *       <Feedback.Title>What should we fix first?</Feedback.Title>
+ *       <Feedback.Close />
+ *       <Feedback.Field placeholder="Tell us what got in your way" />
+ *     </Feedback.Panel>
+ *     <Feedback.Footer>
+ *       <Feedback.Cancel />
+ *       <Feedback.Submit onSubmit={send} />
+ *     </Feedback.Footer>
+ *   </Feedback.Content>
+ * </Feedback>
+ */
+export const Feedback = Object.assign(FeedbackRoot, {
+	/** The control that opens it. `asChild` donates the press to a `Button`. */
+	Trigger: FeedbackTrigger,
+	/** The shell — a `Dialog.Content` on the muted band. Renders nothing while closed. */
+	Content: FeedbackContent,
+	/** The recessed well holding the title, the close and the field. Eases between heights. */
+	Panel: FeedbackPanel,
+	/** The question — a `Dialog.Title`, and the field's default label. */
+	Title: FeedbackTitle,
+	/** The ✕ in the well's corner. Keeps the draft. */
+	Close: FeedbackClose,
+	/** The multiline text field, bound to the draft. */
+	Field: FeedbackField,
+	/** The actions, end-aligned on the band under the well. */
+	Footer: FeedbackFooter,
+	/** A custom footer action — a `secondary` `Button`. */
+	Action: FeedbackAction,
+	/** Closes and keeps the draft. */
+	Cancel: FeedbackCancel,
+	/** Sends the trimmed draft; waits on a promise; never closes. */
+	Submit: FeedbackSubmit,
+	displayName: "DelacourUI.Feedback",
+});

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

@@ -0,0 +1,185 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../../styles/theme-tokens.test";
+import {
+	canSubmitFeedback,
+	FEEDBACK_DEFAULT_MAX_ROWS,
+	FEEDBACK_DEFAULT_MIN_ROWS,
+	FEEDBACK_FIELD_LINE_HEIGHT,
+	FEEDBACK_PANEL_RESIZE_MS,
+	feedbackVariants,
+	resolveFeedbackFieldHeightStyle,
+	resolveFeedbackFieldMinHeight,
+} from "./feedback.variants";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** `border-t` and friends set a width, not a colour, and name no token. */
+const STRUCTURAL_BORDER_SUFFIXES = new Set(["t", "b", "l", "r", "x", "y", "s", "e"]);
+
+/** Every theme token a class string paints with, with any `/alpha` suffix dropped. */
+function colorTokens(cls: string): string[] {
+	const tokens: string[] = [];
+
+	for (const [, utility, token] of cls.matchAll(/\b(bg|border|text)-([a-z][\w-]*)(?:\/\d+)?\b/g)) {
+		if (utility === "border" && STRUCTURAL_BORDER_SUFFIXES.has(token)) continue;
+		// `text-input-md` is a size token, not a colour.
+		if (utility === "text" && token.startsWith("input-")) continue;
+		tokens.push(token);
+	}
+
+	return tokens;
+}
+
+/** Pinned rather than derived — `tv` adds a `base` slot of its own. */
+const SLOT_NAMES = ["content", "clip", "panel", "title", "close", "field", "footer"] as const;
+
+describe("feedbackVariants", () => {
+	test("the shell paints the muted band and is tighter than a dialog's p-5", () => {
+		const content = feedbackVariants().content();
+		expect(content).toContain("bg-muted");
+		expect(content).toMatch(/\bp-[1-3]\b/);
+		expect(content).not.toContain("p-5");
+	});
+
+	test("the panel is a recessed well on the page colour, inset with the md corner and a hairline", () => {
+		const panel = feedbackVariants().panel();
+		expect(panel).toContain("bg-background");
+		expect(panel).toContain("rounded-md");
+		expect(panel).toContain("border");
+		expect(panel).toContain("border-border");
+		expect(panel).toMatch(/\bp-\d/);
+	});
+
+	test("the clip hides the well's overflow mid-resize and shares its corner", () => {
+		const clip = feedbackVariants().clip();
+		expect(clip).toContain("overflow-hidden");
+		expect(clip).toContain("rounded-md");
+	});
+
+	test("the title reserves clearance for the close glyph and carries no type of its own", () => {
+		const title = feedbackVariants().title();
+		expect(title).toBe("pr-8");
+	});
+
+	test("the close glyph sits in the panel's top-right corner", () => {
+		const close = feedbackVariants().close();
+		expect(close).toContain("absolute");
+		expect(close).toMatch(/\btop-\d/);
+		expect(close).toMatch(/\bright-\d/);
+	});
+
+	test("the field has no box of its own and sets the input type on the house face", () => {
+		const field = feedbackVariants().field();
+		expect(field).toContain("font-sans");
+		expect(field).toContain("text-input-md");
+		expect(field).toContain("text-foreground");
+		expect(field).toContain("leading-6");
+		expect(field).not.toMatch(/\bborder\b/);
+		expect(field).not.toMatch(/\bbg-/);
+	});
+
+	test("the footer is an end-aligned row with a narrower inset than the well's", () => {
+		const footer = feedbackVariants().footer();
+		expect(footer).toContain("flex-row");
+		expect(footer).toContain("items-center");
+		expect(footer).toContain("justify-end");
+		expect(footer).toContain("gap-2");
+		expect(footer).not.toMatch(/\bp-[4-9]\b/);
+	});
+
+	test("a caller's className reaches each slot and wins a conflict", () => {
+		const panel = feedbackVariants().panel({ className: "rounded-xl" });
+		expect(panel).toContain("rounded-xl");
+		expect(panel).not.toContain("rounded-md");
+	});
+});
+
+describe("every token the slots name", () => {
+	test("is declared in both variants of theme.css", () => {
+		const slots = feedbackVariants();
+		for (const name of SLOT_NAMES) {
+			for (const token of colorTokens(slots[name]())) {
+				expect({ inLight: LIGHT.has(token), slot: name, token }).toEqual({ inLight: true, slot: name, token });
+				expect({ inDark: DARK.has(token), slot: name, token }).toEqual({ inDark: true, slot: name, token });
+			}
+		}
+	});
+
+	test("the reader found tokens at all", () => {
+		expect(colorTokens(feedbackVariants().content())).toContain("muted");
+		expect(colorTokens(feedbackVariants().panel())).toEqual(expect.arrayContaining(["background", "border"]));
+		expect(colorTokens(feedbackVariants().field())).toEqual(["foreground"]);
+	});
+});
+
+describe("canSubmitFeedback", () => {
+	test("an empty message cannot be sent", () => {
+		expect(canSubmitFeedback({ value: "" })).toBe(false);
+	});
+
+	test("whitespace is empty", () => {
+		expect(canSubmitFeedback({ value: "   \n\t " })).toBe(false);
+	});
+
+	test("any text can be sent", () => {
+		expect(canSubmitFeedback({ value: "The export button is hidden" })).toBe(true);
+		expect(canSubmitFeedback({ value: "  x  " })).toBe(true);
+	});
+
+	test("canSubmitEmpty lets an empty message through", () => {
+		expect(canSubmitFeedback({ canSubmitEmpty: true, value: "" })).toBe(true);
+		expect(canSubmitFeedback({ canSubmitEmpty: true, value: "  " })).toBe(true);
+	});
+
+	test("disabled outranks everything", () => {
+		expect(canSubmitFeedback({ isDisabled: true, value: "text" })).toBe(false);
+		expect(canSubmitFeedback({ canSubmitEmpty: true, isDisabled: true, value: "" })).toBe(false);
+	});
+});
+
+describe("resolveFeedbackFieldMinHeight", () => {
+	test("the line height is the field's leading-6", () => {
+		expect(FEEDBACK_FIELD_LINE_HEIGHT).toBe(24);
+	});
+
+	test("defaults to six rows", () => {
+		expect(FEEDBACK_DEFAULT_MIN_ROWS).toBe(6);
+		expect(resolveFeedbackFieldMinHeight(undefined, FEEDBACK_FIELD_LINE_HEIGHT)).toBe(144);
+	});
+
+	test("is rows times the line height", () => {
+		expect(resolveFeedbackFieldMinHeight(3, 24)).toBe(72);
+		expect(resolveFeedbackFieldMinHeight(1, 20)).toBe(20);
+	});
+
+	test("floors to whole rows and clamps to at least one", () => {
+		expect(resolveFeedbackFieldMinHeight(2.7, 24)).toBe(48);
+		expect(resolveFeedbackFieldMinHeight(0, 24)).toBe(24);
+		expect(resolveFeedbackFieldMinHeight(-3, 24)).toBe(24);
+	});
+
+	test("falls back to the default on a number that is not one", () => {
+		expect(resolveFeedbackFieldMinHeight(Number.NaN, 24)).toBe(144);
+		expect(resolveFeedbackFieldMinHeight(Number.POSITIVE_INFINITY, 24)).toBe(144);
+	});
+});
+
+describe("resolveFeedbackFieldHeightStyle", () => {
+	test("floors at minRows and caps at maxRows", () => {
+		expect(FEEDBACK_DEFAULT_MAX_ROWS).toBe(12);
+		expect(resolveFeedbackFieldHeightStyle({})).toEqual({ maxHeight: 288, minHeight: 144 });
+		expect(resolveFeedbackFieldHeightStyle({ maxRows: 4, minRows: 2 })).toEqual({ maxHeight: 96, minHeight: 48 });
+	});
+
+	test("lifts a ceiling below the floor up to it, so the field never shrinks as it grows", () => {
+		expect(resolveFeedbackFieldHeightStyle({ maxRows: 2, minRows: 6 })).toEqual({ maxHeight: 144, minHeight: 144 });
+	});
+});
+
+describe("FEEDBACK_PANEL_RESIZE_MS", () => {
+	test("is short and finite, so a step change settles before the next tap", () => {
+		expect(FEEDBACK_PANEL_RESIZE_MS).toBeGreaterThan(0);
+		expect(FEEDBACK_PANEL_RESIZE_MS).toBeLessThanOrEqual(250);
+	});
+});

package/src/components/feedback/feedback.variants.ts

@@ -0,0 +1,128 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+
+/** How many lines tall the field is before it grows, when `minRows` is not named. */
+export const FEEDBACK_DEFAULT_MIN_ROWS = 6;
+
+/** The tallest the field grows before it scrolls, when `maxRows` is not named. */
+export const FEEDBACK_DEFAULT_MAX_ROWS = 12;
+
+/**
+ * How long the well takes to follow a change in its content's height — a
+ * multi-step swap, or a line added while typing. Short, so a new line is never
+ * clipped for long, and finite, so an E2E runner's settle wait ends.
+ */
+export const FEEDBACK_PANEL_RESIZE_MS = 200;
+
+/**
+ * Points per line of the field — the `leading-6` its slot sets. The test reads
+ * the class back, so the two cannot drift apart.
+ */
+export const FEEDBACK_FIELD_LINE_HEIGHT = 24;
+
+/**
+ * Styling for every part of a feedback dialog.
+ *
+ * The shell is `Dialog.Content` with these classes merged over the dialog's
+ * own, so `content` only names what differs from a confirm dialog: the muted
+ * band and a tighter padding, which is what makes the well read as inset.
+ * Everything else — the corner, the hairline, the width cap — stays Dialog's.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const feedbackVariants = tv({
+	slots: {
+		/** The shell: the dialog's card, on the band colour, with a tight inset around the well. */
+		content: "gap-2 bg-muted p-2",
+		/**
+		 * The animated clip around the well. Its height follows the well's on a
+		 * timing; its corner matches the well's so nothing pokes out mid-resize.
+		 */
+		clip: "overflow-hidden rounded-md",
+		/**
+		 * The recessed well: the page colour, one step down the corner ramp from
+		 * the card it sits in so the two read as nested, and a hairline. Relative
+		 * so the corner ✕ positions against it rather than the shell.
+		 */
+		panel: "relative gap-2 overflow-hidden rounded-md border border-border bg-background p-4",
+		/** Clearance for `Feedback.Close`, and nothing else — the type is `Text.Header`'s. */
+		title: "pr-8",
+		close: "absolute top-3 right-3 z-10",
+		/**
+		 * A raw `TextInput` with no box: the well is the box. It restates
+		 * `font-sans` for the reason `Input`'s field does — a `TextInput`
+		 * inherits nothing — and sets paragraph leading, which its min height
+		 * is counted in.
+		 */
+		field: "p-0 font-sans text-foreground text-input-md leading-6",
+		/** Narrower than the well's inset, so the actions sit on the band rather than in it. */
+		footer: "flex-row items-center justify-end gap-2 px-1 pb-1",
+	},
+});
+
+export type FeedbackVariantProps = VariantProps<typeof feedbackVariants>;
+
+export type CanSubmitFeedbackInput = {
+	/** The draft as typed. */
+	value: string;
+	/** Allow an empty message — when chips or a rating carry the answer. Default false. */
+	canSubmitEmpty?: boolean;
+	/** The submit is off — disabled by the caller, or a send already in flight. Default false. */
+	isDisabled?: boolean;
+};
+
+/**
+ * Whether `Feedback.Submit` can be pressed.
+ *
+ * Whitespace is empty: a message of three spaces sends nothing, and `onSubmit`
+ * receives the trimmed text anyway. Disabled outranks `canSubmitEmpty`.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function canSubmitFeedback({
+	value,
+	canSubmitEmpty = false,
+	isDisabled = false,
+}: CanSubmitFeedbackInput): boolean {
+	if (isDisabled) return false;
+	if (canSubmitEmpty) return true;
+	return value.trim().length > 0;
+}
+
+/**
+ * The field's minimum height, in points — `minRows` lines of `lineHeight`.
+ *
+ * A style, never a class: a runtime `` `min-h-[${n}px]` `` is never compiled by
+ * Tailwind's static scanner. A bad row count degrades the way `Textarea`'s
+ * does — floored to whole lines, clamped to one, the default on `NaN`.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveFeedbackFieldMinHeight(minRows: number | undefined, lineHeight: number): number {
+	const rows =
+		minRows === undefined || !Number.isFinite(minRows) ? FEEDBACK_DEFAULT_MIN_ROWS : Math.max(1, Math.floor(minRows));
+	return rows * lineHeight;
+}
+
+/**
+ * The field's height bounds, as a style: floored at `minRows`, capped at
+ * `maxRows`, and between the two React Native's multiline `TextInput` sizes
+ * itself to its text. Past the cap it scrolls — a dialog that grew without
+ * one would push its footer under the keyboard.
+ *
+ * A ceiling below the floor is lifted up to it, so the field never shrinks as
+ * it grows. Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveFeedbackFieldHeightStyle({
+	minRows,
+	maxRows,
+	lineHeight = FEEDBACK_FIELD_LINE_HEIGHT,
+}: {
+	minRows?: number;
+	maxRows?: number;
+	lineHeight?: number;
+}): { minHeight: number; maxHeight: number } {
+	const minHeight = resolveFeedbackFieldMinHeight(minRows, lineHeight);
+	const ceiling = resolveFeedbackFieldMinHeight(maxRows ?? FEEDBACK_DEFAULT_MAX_ROWS, lineHeight);
+	return { maxHeight: Math.max(minHeight, ceiling), minHeight };
+}

package/src/components/feedback/index.ts

@@ -0,0 +1,24 @@
+export { Feedback, type FeedbackProps } from "./feedback";
+export { type FeedbackContextValue, useFeedback, useFeedbackContext } from "./feedback.context";
+export {
+	type CanSubmitFeedbackInput,
+	canSubmitFeedback,
+	FEEDBACK_DEFAULT_MAX_ROWS,
+	FEEDBACK_DEFAULT_MIN_ROWS,
+	FEEDBACK_FIELD_LINE_HEIGHT,
+	FEEDBACK_PANEL_RESIZE_MS,
+	type FeedbackVariantProps,
+	feedbackVariants,
+	resolveFeedbackFieldHeightStyle,
+	resolveFeedbackFieldMinHeight,
+} from "./feedback.variants";
+export type { FeedbackActionProps } from "./feedback-action";
+export type { FeedbackCancelProps } from "./feedback-cancel";
+export type { FeedbackCloseProps } from "./feedback-close";
+export type { FeedbackContentProps } from "./feedback-content";
+export type { FeedbackFieldProps } from "./feedback-field";
+export type { FeedbackFooterProps } from "./feedback-footer";
+export type { FeedbackPanelProps } from "./feedback-panel";
+export type { FeedbackSubmitProps } from "./feedback-submit";
+export type { FeedbackTitleProps } from "./feedback-title";
+export type { FeedbackTriggerProps } from "./feedback-trigger";