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

package/src/components/textarea/AGENTS.md

@@ -0,0 +1,86 @@
+# Textarea
+
+A multiline text field, sized in rows. One component, no parts: it renders an
+[`Input`](../input/AGENTS.md) and adds a height and an optional character count.
+
+`import { Textarea } from "@delacour/react-native-ui/textarea";`
+
+## Files
+
+| File | What it holds |
+| --- | --- |
+| `index.ts` | → `@delacour/react-native-ui/textarea` |
+| `textarea.tsx` | `Textarea` |
+| `textarea.variants.ts` | Pure `tv()` slots, the line metrics and the height and count resolvers, no RN imports |
+| `textarea.variants.test.ts` | |
+
+## Design
+
+- **The box is `Input`'s, and nothing here restates it.** Variants (`primary`,
+  `secondary`), sizes (`sm`, `md`, `lg`), the focus ring, the invalid border
+  that outranks it, the disabled fade, the `accent-*` caret and placeholder, and
+  the `Field` cascade all come from rendering an `Input` with `multiline`. A
+  second `tv()` for the same border would be a second thing that can drift, and
+  a textarea under a row of single-line fields has to read as the same control
+  at a different height — not as a close match.
+- **`rows` is a line count, and it becomes points in JavaScript.** A row count
+  only turns into a height once the height of a line is a number, so
+  `TEXTAREA_LINE_HEIGHTS` holds it per size and `resolveTextareaRowsHeight` adds
+  the padding and the border either side. The result is a **style**, never a
+  class: a runtime `` `h-[${n}px]` `` is never compiled by Tailwind's static
+  scanner and would draw nothing — the rule in
+  [Sizing](../../../AGENTS.md#sizing). `size` moves the type and the leading, so
+  a small three-row field and a large one are both three rows.
+- **Every number the height counts is pinned to the class that draws it.** The
+  line height is set by a `leading-*` class in `textareaVariants`' `field` slot,
+  and the padding is `Input`'s multiline `py-*`. `textarea.variants.test.ts`
+  resolves both classes and fails if either disagrees with its number — a
+  retune of `Input`'s padding would otherwise mis-size every textarea by a few
+  points, silently, with the last line clipped at the bottom edge.
+- **A paragraph gets paragraph leading.** `Input` sets `leading-tight` because
+  it centres one line in a fixed box; four lines at 1.25× read as a wall. The
+  textarea's `leading-5`/`-6`/`-7` replace it through `Input`'s own className
+  merge rather than sitting beside it, and a test holds each between 1.2× and
+  1.6× the `--text-input-*` size so the type scale can be retuned without this
+  going stale.
+- **`autoGrow` measures nothing.** It sets `minHeight` at `rows` and
+  `maxHeight` at `maxRows`, and between the two React Native's multiline
+  `TextInput` sizes itself to its content; past the cap it scrolls. An
+  `onContentSizeChange` loop would draw one frame at the old height after every
+  new line, which is exactly the jump a growing field exists to avoid. The field
+  never shrinks below `rows`, so a message typed and cleared goes back to where
+  it started rather than collapsing to one line.
+- **`maxRows` only type-checks with `autoGrow`, and `showCount` only with
+  `maxLength`.** Both are unions in `TextareaProps`. A ceiling on a field that
+  does not grow is a number nothing reads, and a count with no limit to count
+  towards says nothing — a runtime warning would only find either out on a
+  device.
+- **A bad row count degrades rather than throws.** `resolveTextareaRows` floors
+  to whole lines, clamps to at least one, falls back on `NaN` or `Infinity`, and
+  lifts a `maxRows` below `rows` up to it — otherwise a growing field would
+  shrink as it grew.
+- **The count turns destructive at the limit, not past it.** Native `maxLength`
+  stops typing at the limit, so "over" is a state someone typing never sees;
+  the count has to change at the moment the keyboard stops working. It renders
+  `Text.Caption` and passes its colour through the preset's `color` prop, so the
+  `count` slot carries no colour class to fight it. It uses `tabular-nums` so it
+  does not jitter as it counts, and announces as "12 of 280 characters" rather
+  than as a fraction.
+- **The count works controlled and uncontrolled.** A `value` is read directly;
+  without one, the last text the field reported is, seeded from `defaultValue`
+  so the first frame is already right.
+- **There is always a wrapping `View`.** `className` reaches the field, as it
+  does on `Input`, and `containerClassName` reaches the wrapper that holds the
+  field and its count. The wrapper is there whether or not the count is, so
+  flipping `showCount` never remounts the field and drops focus.
+- **`multiline` and `numberOfLines` are withheld.** It is always multiline, and
+  `rows` is its height; `numberOfLines` would be a second answer to the same
+  question, and on Android the one that wins.
+- **There is no `label`, `description` or `errorMessage` prop.** A textarea goes
+  in a [`Field`](../field/AGENTS.md) the way an `Input` does — the reason
+  `Input` ships no label part holds here too. `apps/playground`'s
+  `/textarea` gallery ends with a composed form showing the trade at a call site.
+- **Not for `Input.Group` or `Button.Group`.** An inner `Input` would read
+  either context and take its box or its corner, but a decorated or joined
+  paragraph is not a control this library draws, and the height math assumes
+  the box is the field's own.

package/src/components/textarea/index.ts

@@ -0,0 +1,16 @@
+export { Textarea, type TextareaProps } from "./textarea";
+export {
+	resolveTextareaCount,
+	resolveTextareaFieldClass,
+	resolveTextareaHeightStyle,
+	resolveTextareaRows,
+	resolveTextareaRowsHeight,
+	TEXTAREA_BORDER_WIDTH,
+	TEXTAREA_DEFAULT_MAX_ROWS,
+	TEXTAREA_DEFAULT_ROWS,
+	TEXTAREA_LINE_HEIGHTS,
+	TEXTAREA_PADDING_Y,
+	type TextareaCount,
+	type TextareaVariantProps,
+	textareaVariants,
+} from "./textarea.variants";

package/src/components/textarea/textarea.tsx

@@ -0,0 +1,157 @@
+import { type ReactElement, useCallback, useState } from "react";
+import { View } from "react-native";
+import { Input, type InputProps } from "../input";
+import { Text } from "../text";
+import {
+	resolveTextareaCount,
+	resolveTextareaFieldClass,
+	resolveTextareaHeightStyle,
+	textareaVariants,
+} from "./textarea.variants";
+
+/**
+ * Whether the field grows with its text.
+ *
+ * A union so `maxRows` is only accepted where it means something: on a field
+ * that does not grow, a ceiling is a number nothing reads.
+ */
+type TextareaGrowProps =
+	| {
+			/** Stay `rows` tall and scroll past it. The default. */
+			autoGrow?: false;
+			maxRows?: never;
+	  }
+	| {
+			/** Grow with the text, from `rows` up to `maxRows`, then scroll. */
+			autoGrow: true;
+			/** The tallest the field grows, in lines. Default 10. */
+			maxRows?: number;
+	  };
+
+/**
+ * Whether a character count sits under the field.
+ *
+ * A union so the count cannot be asked for without a limit: a count with
+ * nothing to count towards says nothing, and a runtime check would only find
+ * that out on a device.
+ */
+type TextareaCountProps =
+	| {
+			showCount?: false;
+			/** The most characters the field accepts. */
+			maxLength?: number;
+	  }
+	| {
+			/** Show how much of `maxLength` is used, under the field's trailing edge. */
+			showCount: true;
+			maxLength: number;
+	  };
+
+export type TextareaProps = Omit<InputProps, "multiline" | "numberOfLines" | "maxLength"> &
+	TextareaGrowProps &
+	TextareaCountProps & {
+		/** How many lines tall the field is — its height when fixed, its floor when growing. Default 4. */
+		rows?: number;
+		/** Class for the view holding the field and its count. `className` styles the field itself. */
+		containerClassName?: string;
+	};
+
+/**
+ * A multiline text field, sized in rows.
+ *
+ * The box is `Input`'s — its variants, sizes, focus ring, invalid border,
+ * disabled fade and the `Field` cascade all come from there unchanged, so a
+ * textarea and the single-line fields above it in a form are the same control
+ * at a different height rather than two that happen to match.
+ *
+ * What this adds is the height. `rows` is a line count, and it becomes points
+ * through the paragraph leading and the box's own padding and border — see
+ * `resolveTextareaHeightStyle`. It is applied as a style, never a class,
+ * because a runtime number cannot be a Tailwind class. `size` changes the type
+ * and leading, so a small three-row field and a large one are both three rows.
+ *
+ * `autoGrow` floors the field at `rows` and caps it at `maxRows`; between the
+ * two, React Native's multiline `TextInput` sizes itself to its content, and
+ * past the cap it scrolls. `showCount` with `maxLength` puts a count under the
+ * trailing edge that turns destructive at the limit.
+ *
+ * `multiline` and `numberOfLines` are withheld: it is always multiline, and its
+ * height comes from `rows`.
+ *
+ * Label, description and error come from `Field`, exactly as they do for
+ * `Input` — there is no `label` prop.
+ *
+ * @example
+ * <Field>
+ *   <Field.Label>Notes</Field.Label>
+ *   <Textarea placeholder="Anything we should know?" />
+ * </Field>
+ *
+ * @example
+ * <Textarea autoGrow maxRows={8} rows={2} placeholder="Message" />
+ *
+ * @example
+ * <Textarea maxLength={280} onChangeText={setStatus} showCount value={status} />
+ */
+export function Textarea({
+	rows,
+	autoGrow,
+	maxRows,
+	showCount,
+	maxLength,
+	size,
+	className,
+	containerClassName,
+	style,
+	value,
+	defaultValue,
+	onChangeText,
+	...props
+}: TextareaProps): ReactElement {
+	const resolvedSize = size ?? "md";
+	const slots = textareaVariants({ size: resolvedSize });
+
+	// The count reads the value's length whether or not the caller owns the
+	// value. Controlled, `value` is the truth; uncontrolled, the last text the
+	// field reported is — seeded from `defaultValue` so the count is right on
+	// the first frame rather than after the first keystroke.
+	const [ownLength, setOwnLength] = useState(() => defaultValue?.length ?? 0);
+	const length = value === undefined ? ownLength : value.length;
+
+	const handleChangeText = useCallback(
+		(text: string) => {
+			setOwnLength(text.length);
+			onChangeText?.(text);
+		},
+		[onChangeText]
+	);
+
+	const count = showCount && maxLength !== undefined ? resolveTextareaCount({ length, maxLength }) : null;
+
+	return (
+		<View className={slots.root({ className: containerClassName })}>
+			<Input
+				{...props}
+				className={resolveTextareaFieldClass({ className, size: resolvedSize })}
+				defaultValue={defaultValue}
+				maxLength={maxLength}
+				multiline
+				onChangeText={handleChangeText}
+				size={resolvedSize}
+				style={[resolveTextareaHeightStyle({ autoGrow, maxRows, rows, size: resolvedSize }), style]}
+				value={value}
+			/>
+			{count ? (
+				<Text.Caption
+					accessibilityLabel={count.accessibilityLabel}
+					accessibilityLiveRegion="polite"
+					className={slots.count()}
+					color={count.color}
+				>
+					{count.label}
+				</Text.Caption>
+			) : null}
+		</View>
+	);
+}
+Textarea.displayName = "DelacourUI.Textarea";

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

@@ -0,0 +1,219 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { INPUT_SIZES, inputVariants, resolveInputFieldClass } from "../input/input.variants";
+import {
+	resolveTextareaCount,
+	resolveTextareaFieldClass,
+	resolveTextareaHeightStyle,
+	resolveTextareaRows,
+	resolveTextareaRowsHeight,
+	TEXTAREA_BORDER_WIDTH,
+	TEXTAREA_DEFAULT_MAX_ROWS,
+	TEXTAREA_DEFAULT_ROWS,
+	TEXTAREA_LINE_HEIGHTS,
+	TEXTAREA_PADDING_Y,
+	textareaVariants,
+} from "./textarea.variants";
+
+const TOKENS_CSS = readFileSync(join(import.meta.dirname, "../../styles/tokens.css"), "utf-8");
+
+/** Points behind a `--text-input-*` token in `tokens.css`. */
+function inputTextPoints(size: string): number {
+	const match = TOKENS_CSS.match(new RegExp(`--text-input-${size}:\\s*([\\d.]+)px;`));
+	if (!match?.[1]) throw new Error(`tokens.css defines no --text-input-${size}`);
+	return Number(match[1]);
+}
+
+/** Points behind the first `<prefix>-N` spacing utility in a class string, at Tailwind's 4pt step. */
+function spacingPoints(cls: string, prefix: string): number | undefined {
+	const match = cls.match(new RegExp(`(?:^|\\s)${prefix}-(\\d+(?:\\.\\d+)?)(?:\\s|$)`));
+	return match?.[1] === undefined ? undefined : Number(match[1]) * 4;
+}
+
+describe("the metrics the height is derived from", () => {
+	// The height is a number, so the padding it counts has to be the padding
+	// the box actually wears. That padding is `Input`'s multiline `py-*`, and
+	// restating it here is only safe because this test reads it back.
+	test("count the vertical padding Input's multiline box wears", () => {
+		for (const size of INPUT_SIZES) {
+			const cls = resolveInputFieldClass({ isMultiline: true, size });
+			expect(spacingPoints(cls, "py")).toBe(TEXTAREA_PADDING_Y[size]);
+		}
+	});
+
+	test("count the one-pixel border every variant draws", () => {
+		expect(inputVariants().root()).toMatch(/(?:^|\s)border(?:\s|$)/);
+		expect(TEXTAREA_BORDER_WIDTH).toBe(1);
+	});
+
+	test("give each size the line height its field class sets", () => {
+		for (const size of INPUT_SIZES) {
+			const cls = resolveTextareaFieldClass({ size });
+			expect(spacingPoints(cls, "leading")).toBe(TEXTAREA_LINE_HEIGHTS[size]);
+		}
+	});
+
+	// A line shorter than its type clips descenders; one under 1.2× reads as
+	// a wall. The ratio is what is pinned, so the type scale can be retuned.
+	test("set every line between 1.2× and 1.6× the value's type size", () => {
+		for (const size of INPUT_SIZES) {
+			const ratio = TEXTAREA_LINE_HEIGHTS[size] / inputTextPoints(size);
+			expect(ratio).toBeGreaterThanOrEqual(1.2);
+			expect(ratio).toBeLessThanOrEqual(1.6);
+		}
+	});
+
+	test("step the line height with the size", () => {
+		const heights = INPUT_SIZES.map((size) => TEXTAREA_LINE_HEIGHTS[size]);
+		expect([...heights].sort((a, b) => a - b)).toEqual(heights);
+		expect(new Set(heights).size).toBe(heights.length);
+	});
+});
+
+describe("resolveTextareaFieldClass", () => {
+	test("replaces Input's single-line leading rather than adding a second", () => {
+		for (const size of INPUT_SIZES) {
+			const cls = resolveInputFieldClass({
+				className: resolveTextareaFieldClass({ size }),
+				isMultiline: true,
+				size,
+			});
+			expect(cls).not.toContain("leading-tight");
+			expect(cls.match(/\bleading-/g)).toHaveLength(1);
+		}
+	});
+
+	test("merges an incoming className last", () => {
+		expect(resolveTextareaFieldClass({ className: "leading-9", size: "md" })).toContain("leading-9");
+		expect(resolveTextareaFieldClass({ className: "leading-9", size: "md" })).not.toContain("leading-6");
+	});
+});
+
+describe("resolveTextareaRows", () => {
+	test("defaults to four rows and a ten-row ceiling", () => {
+		expect(TEXTAREA_DEFAULT_ROWS).toBe(4);
+		expect(TEXTAREA_DEFAULT_MAX_ROWS).toBe(10);
+		expect(resolveTextareaRows({})).toEqual({ maxRows: 10, rows: 4 });
+	});
+
+	test("never goes below one row", () => {
+		expect(resolveTextareaRows({ rows: 0 }).rows).toBe(1);
+		expect(resolveTextareaRows({ rows: -3 }).rows).toBe(1);
+	});
+
+	test("rounds a fractional row count down to whole lines", () => {
+		expect(resolveTextareaRows({ rows: 2.7 }).rows).toBe(2);
+		expect(resolveTextareaRows({ maxRows: 5.9, rows: 2 }).maxRows).toBe(5);
+	});
+
+	// A ceiling below the floor would make the field shrink as it grew.
+	test("lifts a ceiling below the floor up to it", () => {
+		expect(resolveTextareaRows({ maxRows: 2, rows: 6 })).toEqual({ maxRows: 6, rows: 6 });
+	});
+
+	test("falls back on a non-finite count", () => {
+		expect(resolveTextareaRows({ rows: Number.NaN })).toEqual({ maxRows: 10, rows: 4 });
+		expect(resolveTextareaRows({ maxRows: Number.POSITIVE_INFINITY, rows: 3 }).maxRows).toBe(10);
+	});
+});
+
+describe("resolveTextareaRowsHeight", () => {
+	test("is the lines plus the padding and border either side", () => {
+		for (const size of INPUT_SIZES) {
+			const expected = 3 * TEXTAREA_LINE_HEIGHTS[size] + 2 * TEXTAREA_PADDING_Y[size] + 2 * TEXTAREA_BORDER_WIDTH;
+			expect(resolveTextareaRowsHeight({ rows: 3, size })).toBe(expected);
+		}
+	});
+
+	test("grows by exactly one line per row", () => {
+		for (const size of INPUT_SIZES) {
+			const step = resolveTextareaRowsHeight({ rows: 5, size }) - resolveTextareaRowsHeight({ rows: 4, size });
+			expect(step).toBe(TEXTAREA_LINE_HEIGHTS[size]);
+		}
+	});
+
+	// A one-row textarea should not be shorter than the single-line field it
+	// sits beside in a form.
+	test("is never shorter than a single-line Input at one row", () => {
+		const INPUT_HEIGHTS = { lg: 52, md: 44, sm: 36 } as const;
+		for (const size of INPUT_SIZES) {
+			expect(resolveTextareaRowsHeight({ rows: 1, size })).toBeGreaterThanOrEqual(INPUT_HEIGHTS[size]);
+		}
+	});
+});
+
+describe("resolveTextareaHeightStyle", () => {
+	test("fixes the height at the row count when it does not grow", () => {
+		expect(resolveTextareaHeightStyle({ rows: 3, size: "md" })).toEqual({
+			height: resolveTextareaRowsHeight({ rows: 3, size: "md" }),
+		});
+	});
+
+	test("floors at rows and caps at maxRows when it grows", () => {
+		expect(resolveTextareaHeightStyle({ autoGrow: true, maxRows: 6, rows: 2, size: "sm" })).toEqual({
+			maxHeight: resolveTextareaRowsHeight({ rows: 6, size: "sm" }),
+			minHeight: resolveTextareaRowsHeight({ rows: 2, size: "sm" }),
+		});
+	});
+
+	test("caps a growing field at ten rows when maxRows is unset", () => {
+		expect(resolveTextareaHeightStyle({ autoGrow: true, size: "md" })).toEqual({
+			maxHeight: resolveTextareaRowsHeight({ rows: 10, size: "md" }),
+			minHeight: resolveTextareaRowsHeight({ rows: 4, size: "md" }),
+		});
+	});
+
+	test("ignores maxRows on a field that does not grow", () => {
+		expect(resolveTextareaHeightStyle({ maxRows: 8, rows: 2, size: "lg" })).toEqual({
+			height: resolveTextareaRowsHeight({ rows: 2, size: "lg" }),
+		});
+	});
+});
+
+describe("resolveTextareaCount", () => {
+	test("reads as used over limit", () => {
+		expect(resolveTextareaCount({ length: 12, maxLength: 280 }).label).toBe("12/280");
+	});
+
+	test("announces the count as a sentence", () => {
+		expect(resolveTextareaCount({ length: 1, maxLength: 280 }).accessibilityLabel).toBe("1 of 280 characters");
+	});
+
+	test("reports the limit once it is reached, and not before", () => {
+		expect(resolveTextareaCount({ length: 279, maxLength: 280 }).isAtLimit).toBe(false);
+		expect(resolveTextareaCount({ length: 280, maxLength: 280 }).isAtLimit).toBe(true);
+	});
+
+	test("is muted under the limit and destructive at it", () => {
+		expect(resolveTextareaCount({ length: 3, maxLength: 10 }).color).toBe("muted");
+		expect(resolveTextareaCount({ length: 10, maxLength: 10 }).color).toBe("destructive");
+	});
+
+	// A controlled value set past the limit in code is still over it; the
+	// native `maxLength` only stops typing.
+	test("still reports a value past the limit", () => {
+		expect(resolveTextareaCount({ length: 300, maxLength: 280 })).toEqual({
+			accessibilityLabel: "300 of 280 characters",
+			color: "destructive",
+			isAtLimit: true,
+			label: "300/280",
+		});
+	});
+});
+
+describe("the count slot", () => {
+	test("sits at the trailing edge", () => {
+		expect(textareaVariants().count()).toContain("self-end");
+	});
+
+	test("uses tabular figures, so the count does not jitter as it changes", () => {
+		expect(textareaVariants().count()).toContain("tabular-nums");
+	});
+
+	// Colour belongs to the `Text` preset's `color` prop, not to a class that
+	// would fight it in the merge.
+	test("carries no text colour of its own", () => {
+		expect(textareaVariants().count()).not.toMatch(/\btext-(?:muted|destructive|foreground)/);
+	});
+});

package/src/components/textarea/textarea.variants.ts

@@ -0,0 +1,171 @@
+import type { VariantProps } from "tailwind-variants";
+import { tv } from "../../lib/tv";
+import type { InputSize } from "../input/input.variants";
+
+/** How many lines tall a textarea is when `rows` is not named. */
+export const TEXTAREA_DEFAULT_ROWS = 4;
+
+/** The tallest a growing textarea goes when `maxRows` is not named. */
+export const TEXTAREA_DEFAULT_MAX_ROWS = 10;
+
+/**
+ * Points per line of text, by size.
+ *
+ * A paragraph needs more leading than the one line `Input` sets `leading-tight`
+ * for, and a row count only becomes a height once the height of a line is a
+ * number. So the number lives here, and the `leading-*` class that sets it lives
+ * in {@link textareaVariants} beside it; `textarea.variants.test.ts` reads the
+ * class back and fails if the two ever disagree.
+ */
+export const TEXTAREA_LINE_HEIGHTS: Record<InputSize, number> = { sm: 20, md: 24, lg: 28 };
+
+/**
+ * Vertical padding either side of the text, by size.
+ *
+ * A restatement of `Input`'s multiline `py-*` compounds — the box is `Input`'s,
+ * so the padding is too. The test resolves `Input`'s class and pins these
+ * against it, so a retune there fails here rather than silently mis-sizing
+ * every textarea by a few points.
+ */
+export const TEXTAREA_PADDING_Y: Record<InputSize, number> = { sm: 8, md: 10, lg: 12 };
+
+/** The hairline `Input`'s box draws on every variant, counted top and bottom. */
+export const TEXTAREA_BORDER_WIDTH = 1;
+
+/**
+ * Styling for the parts a textarea adds around `Input`.
+ *
+ * Everything the box itself wears — border, fill, corner, focus and invalid —
+ * is `Input`'s, and is not restated here. What this adds is the paragraph
+ * leading, and the character count that sits under the box.
+ *
+ * `count` carries no colour class: it renders `Text.Caption`, whose `color`
+ * prop is the one place that decision is made — {@link resolveTextareaCount}.
+ *
+ * Free of React Native imports so it stays unit-testable. See AGENTS.md.
+ */
+export const textareaVariants = tv({
+	slots: {
+		root: "gap-1.5",
+		field: "",
+		count: "self-end tabular-nums",
+	},
+	variants: {
+		size: {
+			sm: { field: "leading-5" },
+			md: { field: "leading-6" },
+			lg: { field: "leading-7" },
+		},
+	},
+	defaultVariants: {
+		size: "md",
+	},
+});
+
+export type TextareaVariantProps = VariantProps<typeof textareaVariants>;
+
+/**
+ * The class the textarea hands `Input` for its field.
+ *
+ * `Input` merges it after its own field slot, so the `leading-*` here replaces
+ * the `leading-tight` that slot sets rather than sitting beside it — and a
+ * caller's className, merged last here, still wins over both.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextareaFieldClass({ size, className }: { size: InputSize; className?: string }): string {
+	return textareaVariants({ size }).field({ className });
+}
+
+/** A whole, positive line count, or the fallback when the value is not one. */
+function wholeRows(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value)) return fallback;
+	return Math.max(1, Math.floor(value));
+}
+
+/**
+ * The floor and ceiling a textarea is sized between, in lines.
+ *
+ * A ceiling below the floor is lifted up to it — otherwise a growing field
+ * would shrink as it grew.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextareaRows({ rows, maxRows }: { rows?: number; maxRows?: number }): {
+	rows: number;
+	maxRows: number;
+} {
+	const floor = wholeRows(rows, TEXTAREA_DEFAULT_ROWS);
+	return { maxRows: Math.max(floor, wholeRows(maxRows, TEXTAREA_DEFAULT_MAX_ROWS)), rows: floor };
+}
+
+/**
+ * Points tall a box of `rows` lines is: the lines, plus the padding and the
+ * border either side.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextareaRowsHeight({ rows, size }: { rows: number; size: InputSize }): number {
+	return rows * TEXTAREA_LINE_HEIGHTS[size] + 2 * TEXTAREA_PADDING_Y[size] + 2 * TEXTAREA_BORDER_WIDTH;
+}
+
+/**
+ * The height a textarea is drawn at, as a style — never a class.
+ *
+ * A row count is a runtime number, and Tailwind's scanner is static: a
+ * `` `h-[${n}px]` `` is never compiled and would resolve to nothing. See
+ * AGENTS.md **Sizing**.
+ *
+ * A fixed field is exactly `rows` tall and scrolls past it. A growing one is
+ * floored at `rows` and capped at `maxRows`, and between the two React Native's
+ * own multiline `TextInput` sizes itself to its content — no measuring pass, so
+ * no frame drawn at the old height after a line is added.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextareaHeightStyle({
+	size,
+	rows,
+	maxRows,
+	autoGrow = false,
+}: {
+	size: InputSize;
+	rows?: number;
+	maxRows?: number;
+	autoGrow?: boolean;
+}): { height: number } | { minHeight: number; maxHeight: number } {
+	const lines = resolveTextareaRows({ maxRows, rows });
+	if (!autoGrow) return { height: resolveTextareaRowsHeight({ rows: lines.rows, size }) };
+	return {
+		maxHeight: resolveTextareaRowsHeight({ rows: lines.maxRows, size }),
+		minHeight: resolveTextareaRowsHeight({ rows: lines.rows, size }),
+	};
+}
+
+/** What the character count shows, announces and is coloured. */
+export type TextareaCount = {
+	label: string;
+	accessibilityLabel: string;
+	isAtLimit: boolean;
+	color: "muted" | "destructive";
+};
+
+/**
+ * The character count under a textarea.
+ *
+ * Turns destructive once the limit is reached, not after it: the native
+ * `maxLength` stops typing at the limit, so "over" is a state a person typing
+ * can never see, and the count has to say something at the moment typing stops
+ * working. A controlled value set past the limit in code still reads as at it.
+ *
+ * Pure, so it is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextareaCount({ length, maxLength }: { length: number; maxLength: number }): TextareaCount {
+	const isAtLimit = length >= maxLength;
+	return {
+		accessibilityLabel: `${length} of ${maxLength} characters`,
+		color: isAtLimit ? "destructive" : "muted",
+		isAtLimit,
+		label: `${length}/${maxLength}`,
+	};
+}