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

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

package/src/components/field/AGENTS.md

@@ -52,6 +52,18 @@ A form field's layout, and the one place its state is written down. Root plus
   `accessible={false}`, so the control stays the element a screen reader sees,
   and the inner detector claims a tap on the box itself rather than firing both.
   A field holds one control, so a second registration replaces the first.
+- **The label names the control, through the same context.** `Field.Label`
+  registers its text with `registerLabel`, the mirror of `registerPress`: a
+  control hands its press up, a label hands its name down. A control with no
+  text of its own — a [Slider](../slider/AGENTS.md) thumb is a capsule — reads
+  `field.label` as its `accessibilityLabel`, so "Volume" is announced rather than
+  a bare "40". React Native has no `<label for>`; this is that association, done
+  by hand. `resolveFieldLabelText` decides what qualifies and it is strict on
+  purpose: a plain string or number, trimmed, and nothing else. A label built
+  from elements has no text this side of a render, and guessing at one — an
+  icon's key, say — would name the control after the wrong thing. State rather
+  than a ref for the same reason as the press: the control renders differently
+  for it, and the label registers in an effect, so it costs one render on mount.
 - **A data-attribute class would also leave `bun test`.** Even for a part styling
   itself, `data-invalid:text-destructive` moves the decision from `field.variants.ts`
   into uniwind's runtime matcher, where no unit test can see it. The parts style
@@ -91,6 +103,13 @@ A form field's layout, and the one place its state is written down. Root plus
 - **`Field.Group` inserts no dividers**, unlike [`ListGroup`](../list-group/AGENTS.md). A list of rows
   without lines is a wall of text; fields are already held apart by whitespace,
   and a rule between every one is noise.
+- **`Field.Label` is not built on [`Label`](../label/AGENTS.md)**, the standalone
+  primitive. `Label` narrows `children` from `Text`'s and reports
+  `accessibilityState.disabled`, so wrapping it would change this part's public
+  surface. The two colour and fade identically instead, and
+  `label.variants.test.ts` holds them to it against `fieldVariants`' label slot
+  and `resolveFieldTextColor`. A required field uses `Label` directly, since
+  `Field.Label` has no `isRequired`.
 - **There is no `Field.Title`.** On the web it exists because a `<div>` is not a
   `<label>` — label-styled text with nothing to point `htmlFor` at. React Native
   has neither element nor association, so it and `Field.Label` would render the

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

@@ -1,8 +1,8 @@
-import type { ReactElement } from "react";
+import { type ReactElement, useEffect } from "react";
 import { Text } from "../text";
 import { useFieldContext } from "./field.context";
 import type { FieldTextProps } from "./field.types";
-import { fieldVariants, resolveFieldTextColor } from "./field.variants";
+import { fieldVariants, resolveFieldLabelText, resolveFieldTextColor } from "./field.variants";
 
 /**
  * The name of the control this field holds.
@@ -15,19 +15,33 @@ import { fieldVariants, resolveFieldTextColor } from "./field.variants";
  * There is no `htmlFor`. React Native has no `<label>` element and no
  * label-for-control association, which is also why there is no `Field.Title`:
  * on the web that part exists only because a `<div>` is not a `<label>`, and
- * here both would be the same `Text`.
+ * here both would be the same `Text`. **The association is made by hand
+ * instead**: a string label hands its text to the field's context, and a control
+ * inside with no text of its own — a `Slider.Thumb` — reads it as its accessible
+ * name. `resolveFieldLabelText` decides what qualifies.
  */
-export function FieldLabel({ className, color, ...props }: FieldTextProps): ReactElement {
+export function FieldLabel({ className, color, children, ...props }: FieldTextProps): ReactElement {
 	const field = useFieldContext();
 	const isInvalid = field?.isInvalid ?? false;
 	const isDisabled = field?.isDisabled ?? false;
 
+	const registerLabel = field?.registerLabel;
+	const labelText = resolveFieldLabelText(children);
+
+	useEffect(() => {
+		if (!registerLabel) return;
+		registerLabel(labelText);
+		return () => registerLabel(null);
+	}, [labelText, registerLabel]);
+
 	return (
 		<Text.Label
 			className={fieldVariants({ isDisabled, isInvalid }).label({ className })}
 			color={color ?? resolveFieldTextColor("label", isInvalid)}
 			{...props}
-		/>
+		>
+			{children}
+		</Text.Label>
 	);
 }
 FieldLabel.displayName = "DelacourUI.Field.Label";

package/src/components/field/field.context.tsx

@@ -17,6 +17,23 @@ export type FieldContextValue = {
 	 * second registration replaces the first.
 	 */
 	registerPress: (press: (() => void) | null) => void;
+	/**
+	 * The text of the `Field.Label` inside, or `null` while there is none.
+	 *
+	 * What a control reads for its accessible name when it holds no text of its
+	 * own — a `Slider.Thumb` is a capsule, and a `Switch` is a pill. React Native
+	 * has no `<label for>`; this is that association, carried by the same context
+	 * the state cascades down.
+	 */
+	label: string | null;
+	/**
+	 * A `Field.Label` offers its text here. Pass `null` on unmount.
+	 *
+	 * The counterpart of {@link FieldContextValue.registerPress} going the same
+	 * way: a control hands its press up, a label hands its name down. A field
+	 * holds one label, so a second registration replaces the first.
+	 */
+	registerLabel: (label: string | null) => void;
 };
 
 const FieldContext = createContext<FieldContextValue | null>(null);

package/src/components/field/field.tsx

@@ -37,9 +37,15 @@ function FieldRoot({
 	// The updater form would call `press` instead of storing it.
 	const registerPress = useCallback((press: (() => void) | null) => setControlPress(() => press), []);
 
+	// The label's text, for a control inside to read as its accessible name.
+	// State for the same reason as the press: a control renders differently for
+	// it, and the label registers in an effect, so it costs one render on mount.
+	const [label, setLabel] = useState<string | null>(null);
+	const registerLabel = useCallback((next: string | null) => setLabel(next), []);
+
 	const context = useMemo<FieldContextValue>(
-		() => ({ isDisabled, isInvalid, orientation, registerPress }),
-		[isDisabled, isInvalid, orientation, registerPress]
+		() => ({ isDisabled, isInvalid, label, orientation, registerLabel, registerPress }),
+		[isDisabled, isInvalid, label, orientation, registerLabel, registerPress]
 	);
 
 	const rootClassName = fieldVariants({ isDisabled, isInvalid, orientation }).root({ className });
@@ -86,6 +92,13 @@ function FieldRoot({
  * A control's own prop still wins, so one field inside an invalid group can opt
  * out with `<Input isInvalid={false} />`.
  *
+ * **The label names the control, too.** `Field.Label` hands its text down the
+ * same context, so a control with no text of its own — a `Slider.Thumb`, a
+ * `Switch` — reads "Volume" to a screen reader rather than a bare number. React
+ * Native has no `<label for>`; this is that association. Only a plain string or
+ * number label is lent, since a label built from elements has no text to read
+ * before it renders.
+ *
  * **The whole row drives the control**, once one offers a press through the same
  * context — so tapping "Accept the terms", or the description under it, ticks
  * the `Checkbox` beside it. A checkbox in a form is a small square next to a

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

@@ -7,6 +7,7 @@ import {
 	type FieldTextPart,
 	fieldVariants,
 	resolveFieldInteractive,
+	resolveFieldLabelText,
 	resolveFieldTextColor,
 } from "./field.variants";
 
@@ -214,3 +215,26 @@ describe("resolveFieldInteractive", () => {
 		expect(resolveFieldInteractive(() => undefined)).toBe(true);
 	});
 });
+
+describe("resolveFieldLabelText", () => {
+	test("hands a string label through, trimmed", () => {
+		expect(resolveFieldLabelText("Volume")).toBe("Volume");
+		expect(resolveFieldLabelText("  Volume\n")).toBe("Volume");
+	});
+
+	test("reads a number the way a screen reader would", () => {
+		expect(resolveFieldLabelText(42)).toBe("42");
+	});
+
+	// A label made of elements has no text this side of a render, and an empty
+	// string is not a name — both leave the control to name itself.
+	test("offers nothing for an element, an empty string, or no children at all", () => {
+		expect(resolveFieldLabelText("")).toBeNull();
+		expect(resolveFieldLabelText("   ")).toBeNull();
+		expect(resolveFieldLabelText(undefined)).toBeNull();
+		expect(resolveFieldLabelText(null)).toBeNull();
+		expect(resolveFieldLabelText(false)).toBeNull();
+		expect(resolveFieldLabelText({ type: "Text", props: {} })).toBeNull();
+		expect(resolveFieldLabelText(["a", "b"])).toBeNull();
+	});
+});

package/src/components/field/field.variants.ts

@@ -133,4 +133,24 @@ export function resolveFieldInteractive(press: (() => void) | null): press is ()
 	return press !== null;
 }
 
+/**
+ * The text a `Field.Label` can lend to the control beside it as its accessible
+ * name, or `null` when it has none to lend.
+ *
+ * Only a bare string or number qualifies. A label built from elements has no
+ * text this side of a render, and guessing at one would name a control after
+ * the wrong thing — an icon's key, say. Whitespace is trimmed and an empty
+ * string is an absence, because a screen reader handed `""` reads nothing at
+ * all, which is worse than reading the value alone.
+ *
+ * React Native has no `<label for>`; this is the association, done by hand
+ * through the field's context. Pure, so `bun test` reaches it. See AGENTS.md.
+ */
+export function resolveFieldLabelText(children: unknown): string | null {
+	if (typeof children === "number") return String(children);
+	if (typeof children !== "string") return null;
+	const text = children.trim();
+	return text === "" ? null : text;
+}
+
 export type FieldVariantProps = VariantProps<typeof fieldVariants>;

package/src/components/field/index.ts

@@ -11,6 +11,7 @@ export {
 	type FieldVariantProps,
 	fieldVariants,
 	resolveFieldInteractive,
+	resolveFieldLabelText,
 	resolveFieldTextColor,
 } from "./field.variants";
 export type { FieldContentProps } from "./field-content";

package/src/components/item/AGENTS.md

@@ -0,0 +1,92 @@
+# Item
+
+A row of media, text and actions, for lists and settings. Compound root plus
+`Item.Media`, `Item.Content`, `Item.Title`, `Item.Description`, `Item.Actions`,
+`Item.Header` and `Item.Footer`, and two layout parts, `Item.Group` and
+`Item.Separator`.
+
+`import { Item } from "@delacour/react-native-ui/item";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/item` |
+| `item.tsx` | Root + the `Object.assign` compound surface, and the bare-text wrap it owns |
+| `item-media.tsx` | `Item.Media` |
+| `item-content.tsx` | `Item.Content` |
+| `item-title.tsx` | `Item.Title` |
+| `item-description.tsx` | `Item.Description` |
+| `item-actions.tsx` | `Item.Actions` |
+| `item-header.tsx` | `Item.Header` |
+| `item-footer.tsx` | `Item.Footer` |
+| `item-group.tsx` | `Item.Group` |
+| `item-separator.tsx` | `Item.Separator` |
+| `item.context.tsx` | `ItemProvider`, `useItem()`, `useItemContext()`, `useItemPart()` |
+| `item.types.ts` | Prop types shared by two or more parts |
+| `item.variants.ts` | Pure `tv()` slots and the four resolvers, no RN imports |
+| `item.variants.test.ts` | |
+
+## Design
+
+- **Axes**: `variant` — `default`, `outline`, `muted`; `size` — `sm`, `md`,
+  `lg`; `orientation` — `horizontal`, `vertical`. States: `isDisabled`,
+  `isSelected`, and `busy` inherited from `Pressable`. `Item.Media` has its own
+  `variant` — `default`, `icon`, `image`.
+- **It drops into a `ListGroup` as a row, and that is the point of it.** An item
+  reads the group's context through the `list-group.context` leaf (rule 3 —
+  never `../list-group`) and changes three things when it finds one:
+  - **The surface becomes `grouped`.** `resolveItemSurface` ignores the variant:
+    the group draws the border, fill and corner, and a row repeating any of them
+    would draw a card inside a card. `surface` rather than `variant` is the
+    `tv()` axis for that reason.
+  - **Size defaults to the group's.** `resolveItemSize` — own, else group, else
+    `md`. The two components share the `sm`/`md`/`lg` scale on purpose.
+  - **Press feedback defaults to `fade`**, not `scale` — a full-bleed row that
+    scales reads as the whole card flexing. `resolveItemFeedback`.
+- **Row metrics are `ListGroup`'s, number for number.** The group insets each
+  divider by its own row padding, so an item padded differently would sit with
+  its text and its divider out of line. The tests assert the item's `min-h`,
+  `gap`, `px` and `py` against `listGroupVariants().item()` at every size, and
+  the bare media icon against the group's `prefixIcon` — change one without the
+  other and `bun test` fails by name.
+- **Pressable only with a handler.** `resolveItemRender` returns one of two:
+  `pressable` (a handler — a `Pressable`, role `button`, children merged into
+  one accessible element; disabled, it keeps the role, reports `disabled` and
+  dims through `opacity-50`, which `Pressable` composes with its press
+  animation) or `static` (no handler — a plain `Animated.View` with no role, so
+  a static row never announces itself as a button). The plain branch is
+  `Animated.View` rather than `View` so the `ref` type is one type.
+- **A pressable item must not hold another control.** iOS merges an accessible
+  element's children into it, so a `Button` in the actions of a pressable item
+  is unreachable by VoiceOver. Either leave the item static and let the actions
+  be the controls, or make the row the control: a switch row takes
+  `accessibilityRole="switch"` and `accessibilityState={{ checked }}` on the
+  item, toggles from its `onPress`, and renders the `Switch` inside for show.
+- **`isSelected` lays `bg-accent` over any surface**, the muted fill included —
+  declared after `surface` in the `tv()` so tailwind-merge drops the losing
+  `bg-*`. It also sets `accessibilityState.selected`. What marks the choice (a
+  check, a radio) is composed into `Item.Actions` by the caller.
+- **Icons are composed, never passed as props.** `Item.Media` and
+  `Item.Actions` each wrap their subtree in an `IconDefaultsProvider`. Media
+  gets the foreground token at the size its variant calls for — a bare icon
+  matches a `ListGroup` prefix, an `icon` tile's glyph sits two steps smaller
+  inside it. Actions gets `muted-foreground` a step lower still, so a chevron
+  reads as a hint. A `Button` in the actions publishes its own defaults and is
+  unaffected.
+- **`Header` and `Footer` work on both orientations.** The horizontal root is
+  `flex-wrap` and the strips are `w-full`, so a strip takes a line of its own
+  above or below media, text and actions without the item having to become a
+  column.
+- **`Content` only flexes along a row.** Vertical, it is `self-stretch`: a
+  `flex-1` column in an auto-height parent collapses to zero in Yoga.
+- **`Item.Group` is spaced, not divided.** It is for standalone items — outlined
+  cards, a carousel — announced with `accessibilityRole="list"`. Rows sharing
+  one card with dividers belong in a `ListGroup`, which already does both.
+  `Item.Separator` is a `Separator` under the item's name, for the occasional
+  hand-placed rule in a group.
+- **String children** are wrapped in a `Content` around a `Title`, consecutive
+  strings collapsing into one — the same rule, and the same reason, as
+  [`ListGroup`](../list-group/AGENTS.md).
+- **Text colour goes on the text.** No slot but `title` and `description` holds
+  a `text-*` colour; the tests assert the root never does.

package/src/components/item/index.ts

@@ -0,0 +1,25 @@
+export { Item, type ItemProps } from "./item";
+export { type ItemContextValue, ItemProvider, useItem, useItemContext } from "./item.context";
+export type { ItemSlotProps, ItemTextProps } from "./item.types";
+export {
+	ITEM_ACTIONS_ICON_TOKEN,
+	ITEM_MEDIA_ICON_TOKEN,
+	ITEM_MEDIA_VARIANTS,
+	ITEM_ORIENTATIONS,
+	ITEM_SIZES,
+	ITEM_VARIANTS,
+	type ItemMediaVariant,
+	type ItemOrientation,
+	type ItemRender,
+	type ItemSize,
+	type ItemSurface,
+	type ItemVariant,
+	type ItemVariantProps,
+	itemVariants,
+	resolveItemFeedback,
+	resolveItemRender,
+	resolveItemSize,
+	resolveItemSurface,
+} from "./item.variants";
+export type { ItemGroupProps } from "./item-group";
+export type { ItemMediaProps } from "./item-media";