@delacour/react-native-ui 0.1.0-alpha.20260925053522

package/src/components/text/text.variants.ts

@@ -0,0 +1,282 @@
+import type { VariantProps } from "tailwind-variants";
+import { cn } from "../../lib/cn";
+import { tv } from "../../lib/tv";
+
+/**
+ * The named text roles, block presets first and largest first.
+ *
+ * Order carries meaning for the block half — the tests read it to assert the
+ * type scale descends — so a new block role goes in at its step rather than on
+ * the end.
+ */
+export const TEXT_VARIANTS = [
+	"display",
+	"title",
+	"header",
+	"subheader",
+	"paragraph",
+	"label",
+	"caption",
+	"overline",
+	"strong",
+	"emphasis",
+	"link",
+	"code",
+] as const;
+
+/**
+ * Presets that emit only a delta — a weight, a slant, a decoration, a family —
+ * and inherit size, colour and weight from the `Text` they sit inside.
+ *
+ * This is what makes `<Text.Paragraph>Hi <Text.Strong>there</Text.Strong></Text.Paragraph>`
+ * come out at the paragraph's size and colour instead of snapping back to a
+ * base of its own.
+ */
+export const TEXT_INLINE_VARIANTS = ["strong", "emphasis", "link", "code"] as const;
+
+export const TEXT_SIZES = ["xs", "sm", "md", "lg", "xl", "2xl", "3xl"] as const;
+export const TEXT_WEIGHTS = ["normal", "medium", "semibold", "bold"] as const;
+export const TEXT_COLORS = ["default", "muted", "destructive", "success", "warning", "info"] as const;
+export const TEXT_ALIGNS = ["left", "center", "right"] as const;
+export const TEXT_TRANSFORMS = ["none", "uppercase", "lowercase", "capitalize"] as const;
+
+export type TextVariant = (typeof TEXT_VARIANTS)[number];
+export type TextInlineVariant = (typeof TEXT_INLINE_VARIANTS)[number];
+export type TextSize = (typeof TEXT_SIZES)[number];
+export type TextWeight = (typeof TEXT_WEIGHTS)[number];
+export type TextColor = (typeof TEXT_COLORS)[number];
+export type TextAlign = (typeof TEXT_ALIGNS)[number];
+export type TextTransform = (typeof TEXT_TRANSFORMS)[number];
+
+/**
+ * The treatment a `Text` falls back to on every axis nothing else names.
+ *
+ * First in {@link resolveTextClass}'s chain and therefore the weakest source, so
+ * it never fights an inherited class or a named axis. It is applied
+ * unconditionally — including inside a nested `Text` — and that is deliberate.
+ *
+ * For a nested `Text` it is a no-op: the parent's resolved class came out of
+ * this same function and already names all three axes, so tailwind-merge drops
+ * every class here. It only does work under a *partial* provider — a `Button`
+ * publishing nothing but `text-primary-foreground`, say. Guarding it behind "am
+ * I nested" would leave that `Text` with a colour and no size at all, silently
+ * collapsing to React Native's own 14pt default.
+ *
+ * It names the three axes React Native inherits natively and cannot default
+ * sensibly on its own — weight, size, colour — plus the family.
+ *
+ * `font-sans` is what makes the typeface themeable at all: it resolves
+ * `--font-sans`, which `theme.css` declares per platform and an app may retune
+ * at runtime. Without it a `Text` carries no `fontFamily` and the platform
+ * default stands however the variable is set. It is FIRST in the chain, so
+ * `Text.Code`'s `font-mono` and the headings' `font-heading` — emitted later by
+ * `textVariants`, in the same tailwind-merge group — both still win.
+ */
+export const TEXT_BASE_CLASS = "font-sans font-normal text-base text-foreground";
+
+/**
+ * Cap on OS font scaling.
+ *
+ * Accessibility text sizes are respected — `allowFontScaling` is left at React
+ * Native's default — but the library's fixed-height chrome cannot grow with
+ * them: `h-button-sm|md|lg` are hard 36/44/52pt and `h-navbar-row` is 56pt, so
+ * an uncapped multiplier clips a label rather than enlarging it.
+ */
+export const TEXT_MAX_FONT_SIZE_MULTIPLIER = 1.4;
+
+/**
+ * Styling for one piece of text, on six independent axes.
+ *
+ * ## Order is the design
+ *
+ * `tv` emits variants in the order their keys are declared here, then the
+ * compound variants, then the caller's `className`. `variant` is FIRST because
+ * a preset is the weakest named source: `<Text.Header size="sm">` has to come
+ * out at 14pt. The axes after it touch different tailwind-merge groups, so
+ * their order relative to each other means nothing.
+ *
+ * ## No `defaultVariants`, on purpose
+ *
+ * A `defaultVariants: { size: "md" }` would emit `text-base` from THIS call,
+ * after `variant` and therefore ahead of it in the merge — every preset's size
+ * would be overwritten by the default. More importantly an axis the caller did
+ * not name has to emit *nothing*, so it falls through to the class the
+ * enclosing `Text` published. That is what reproduces React Native's own
+ * cascade. `iconVariants` avoids the same trap for the same reason; the
+ * fallback lives in {@link TEXT_BASE_CLASS} instead.
+ *
+ * ## A variant names type, never a line height
+ *
+ * tailwind-merge lists `leading` among `font-size`'s conflicting groups, so a
+ * `text-lg` from the `size` axis silently strips a `leading-6` written beside a
+ * `text-base` here — no error, just a paragraph that loses its leading the
+ * moment someone resizes it. Tailwind v4's `--text-*--line-height` companions
+ * survive `tokens.css`'s size-only overrides, so every step already carries a
+ * paired leading. If prose ever needs its own, add a `--text-paragraph` /
+ * `--text-paragraph--line-height` *pair* in `tokens.css` and register the
+ * bespoke name in `tokens.ts` — one utility carrying both.
+ *
+ * Free of React Native imports so it stays unit-testable — `bun test` cannot
+ * parse React Native's Flow-typed source. See AGENTS.md.
+ */
+export const textVariants = tv({
+	variants: {
+		variant: {
+			// The three block headings, and the only presets that read
+			// `--font-heading`. It defaults to the same family as `--font-sans`,
+			// so pairing a display face with body text is opt-in for an app
+			// rather than something this package decides.
+			display: "font-heading font-bold text-3xl text-foreground",
+			title: "font-heading font-bold text-2xl text-foreground",
+			header: "font-heading font-semibold text-xl text-foreground",
+			// A step down from the title it sits under, not a fourth heading
+			// level — which is why it is muted and carries no weight of its own.
+			subheader: "text-lg text-muted-foreground",
+			paragraph: "text-base text-foreground",
+			label: "font-medium text-sm text-foreground",
+			caption: "text-sm text-muted-foreground",
+			overline: "font-semibold text-muted-foreground text-xs uppercase tracking-wide",
+			// The four below emit a delta and nothing else. See TEXT_INLINE_VARIANTS.
+			strong: "font-semibold",
+			emphasis: "italic",
+			// `text-info`, never `text-primary`. `--primary` is the primary
+			// SURFACE — #262626 light, #f5f5f5 dark — so a link painted with it
+			// would be indistinguishable from the foreground it sits in.
+			link: "text-info underline",
+			code: "bg-muted font-mono",
+		},
+		// The empty branches are load-bearing typing, not placeholders: a map with
+		// only `true` types the prop as `true` rather than `boolean`. The compound
+		// below matches without them — `tv` compares against `defaultVariants` plus
+		// props and never reads this map. See the note in button.variants.ts.
+		isNested: { true: "", false: "" },
+		size: {
+			xs: "text-xs",
+			sm: "text-sm",
+			// `md` rather than Tailwind's own `base`, so one step name means "the
+			// default step" across Icon, Spinner, Button, ListGroup and Text. The
+			// token underneath is still `--text-base`.
+			md: "text-base",
+			lg: "text-lg",
+			xl: "text-xl",
+			"2xl": "text-2xl",
+			"3xl": "text-3xl",
+		},
+		weight: {
+			normal: "font-normal",
+			medium: "font-medium",
+			semibold: "font-semibold",
+			bold: "font-bold",
+		},
+		// Page-level text colours only. Text drawn ON a coloured surface is that
+		// surface component's job — BUTTON_FOREGROUND_TOKEN already maps a variant
+		// to its foreground, and a second copy of that map here could drift from
+		// it. A caller on a coloured surface writes the utility directly.
+		color: {
+			default: "text-foreground",
+			muted: "text-muted-foreground",
+			destructive: "text-destructive",
+			success: "text-success",
+			warning: "text-warning",
+			info: "text-info",
+		},
+		// `left`/`right`, never `start`/`end`: React Native's `textAlign` accepts
+		// auto | left | right | center | justify and nothing else, so Tailwind v4's
+		// logical-property utilities would resolve to a value RN rejects.
+		align: { left: "text-left", center: "text-center", right: "text-right" },
+		transform: {
+			// `normal-case` rather than an empty string, so `transform="none"` can
+			// actually clear an inherited or preset `uppercase`.
+			none: "normal-case",
+			uppercase: "uppercase",
+			lowercase: "lowercase",
+			capitalize: "capitalize",
+		},
+	},
+	compoundVariants: [
+		// A standalone `Text.Code` is an ordinary Yoga box and takes padding. A
+		// NESTED one is a run inside the platform text engine — iOS lays it out as
+		// an NSAttributedString, Android as a Span — and both ignore padding,
+		// margin and border radius on an inner `<Text>` outright. Only the
+		// background survives, drawn tight to the glyphs with square corners.
+		{ variant: "code", isNested: false, class: "rounded-md px-1.5 py-0.5" },
+	],
+});
+
+/** Whether a preset emits only a delta and inherits the rest from the `Text` above it. */
+export function isInlineTextVariant(variant: TextVariant): boolean {
+	return (TEXT_INLINE_VARIANTS as readonly string[]).includes(variant);
+}
+
+/**
+ * Whether a `Text` with these children can hold a nested `Text` at all.
+ *
+ * A string or number child has no descendant component, so nothing below could
+ * read the context — publishing it would render a provider element per label
+ * for the most-instantiated component in the library. `false` here is provable
+ * rather than a guess, which is what makes skipping the provider safe.
+ *
+ * Deliberately typed on `unknown` rather than `ReactNode`: keeping this module
+ * free of even a type import is what lets `bun test` reach it.
+ */
+export function canNestText(children: unknown): boolean {
+	return typeof children !== "string" && typeof children !== "number";
+}
+
+/**
+ * The class chain that styles one piece of text, weakest source first.
+ *
+ * | Source | How it wins |
+ * | --- | --- |
+ * | {@link TEXT_BASE_CLASS} | first in the chain |
+ * | the class inherited from the enclosing `Text` or `TextClassProvider` | second |
+ * | this `Text`'s own named axes | third |
+ * | the caller's `className` | last |
+ *
+ * This is what replaces React Native's native text inheritance. Natively a
+ * nested `<Text>` inherits the parent's *style object* and overrides only the
+ * keys it sets; here every `Text` compiles its own className, so the parent's
+ * resolved class has to be threaded through and beaten per-axis rather than
+ * wholesale. The chain does that: an axis the child names wins, an axis it
+ * leaves alone falls through.
+ *
+ * The property that makes nesting correct is a fixpoint — for every `x` this
+ * function can produce, `resolveTextClass({ inherited: x })` is exactly `x`, at
+ * any depth. The tests assert it across the matrix.
+ *
+ * Precedence is the ladder `Icon` and `Spinner` already follow, so a `Text`
+ * composed into a `Button` matches it without being told to. See
+ * `resolveIconSizeClass`.
+ *
+ * Pure, so the whole ladder is reachable from `bun test`. See AGENTS.md.
+ */
+export function resolveTextClass({
+	align,
+	className,
+	color,
+	inherited,
+	isNested = false,
+	size,
+	transform,
+	variant,
+	weight,
+}: {
+	align?: TextAlign;
+	className?: string;
+	color?: TextColor;
+	inherited?: string;
+	isNested?: boolean;
+	size?: TextSize;
+	transform?: TextTransform;
+	variant?: TextVariant;
+	weight?: TextWeight;
+}): string {
+	return cn(
+		TEXT_BASE_CLASS,
+		inherited,
+		textVariants({ align, color, isNested, size, transform, variant, weight }),
+		className
+	);
+}
+
+export type TextVariantProps = VariantProps<typeof textVariants>;

package/src/display-name.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SRC = import.meta.dirname;
+
+/**
+ * Every component in the package must carry a `DelacourUI.`-prefixed displayName.
+ *
+ * React DevTools reads `displayName || name`, so without one a tree row, an error
+ * stack and a profiler entry all read the private symbol — `ScreenNavbarTitle`
+ * rather than `DelacourUI.Screen.Navbar.Title`. `bun test` cannot render React
+ * Native, so the convention is checked against the source text instead: this file
+ * reads the `.tsx` tree off disk and imports nothing from it.
+ *
+ * The corpus spans every file at once rather than checking each in isolation,
+ * because `ScreenRoot` is declared in `screen-root.tsx` and named by the
+ * `Object.assign` in `screen.tsx` — see components/screen/AGENTS.md for why the
+ * two cannot share a file.
+ */
+
+/** Every `.tsx` under `src/`, as a path → source map. */
+function sources(): Map<string, string> {
+	const found = new Map<string, string>();
+	const walk = (dir: string): void => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const path = join(dir, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (entry.name.endsWith(".tsx")) found.set(path, readFileSync(path, "utf-8"));
+		}
+	};
+	walk(SRC);
+	return found;
+}
+
+const SOURCES = sources();
+
+/**
+ * A PascalCase `function` declaration, or a `memo(…)` / `forwardRef(…)` const.
+ *
+ * Those are the only three shapes a component takes here: the package has no
+ * arrow-function components, and every PascalCase function declaration in it
+ * returns `ReactElement`, `ReactElement | null` or `null`. A PascalCase helper
+ * would be a false positive — write helpers in camelCase, as the package already
+ * does (`wrapTextChildren`, `withDividers`, `resolveListComponent`).
+ *
+ * A `forwardRef` component's own render function is a function EXPRESSION on the
+ * same line as the call, so it never starts a line and is not counted twice —
+ * which is why the screen scrollables name themselves once, on the const.
+ */
+const DECLARATIONS = [
+	/^(?:export )?function ([A-Z][A-Za-z0-9]*)\s*[<(]/gm,
+	/^(?:export )?const ([A-Z][A-Za-z0-9]*) = memo\(/gm,
+	/^(?:export )?const ([A-Z][A-Za-z0-9]*) = forwardRef[<(]/gm,
+];
+
+/** The trailing form on a part, and the `Object.assign` form on a root. */
+const BINDINGS = [
+	/^([A-Z][A-Za-z0-9]*)\.displayName = "([^"]*)";/gm,
+	/Object\.assign\(\s*([A-Z][A-Za-z0-9]*)\s*,\s*\{[\s\S]*?displayName: "([^"]*)"/gm,
+];
+
+/** Component name → the file it is declared in. */
+function declared(): Map<string, string> {
+	const found = new Map<string, string>();
+	for (const [path, source] of SOURCES) {
+		for (const pattern of DECLARATIONS) {
+			for (const [, name] of source.matchAll(pattern)) found.set(name, path);
+		}
+	}
+	return found;
+}
+
+/** Component name → every displayName bound to it, across the whole tree. */
+function bound(): Map<string, string[]> {
+	const found = new Map<string, string[]>();
+	for (const source of SOURCES.values()) {
+		for (const pattern of BINDINGS) {
+			for (const [, name, value] of source.matchAll(pattern)) {
+				found.set(name, [...(found.get(name) ?? []), value]);
+			}
+		}
+	}
+	return found;
+}
+
+const DECLARED = declared();
+const BOUND = bound();
+
+/** `DelacourUI` plus one segment per step down the public API. */
+const SHAPE = /^DelacourUI(\.[A-Z][A-Za-z0-9]*)+$/;
+
+describe("displayName", () => {
+	// A walker that matched nothing would let every assertion below pass on an
+	// empty set, so the suite would stay green while the convention rotted.
+	test("finds the component tree", () => {
+		expect(SOURCES.size).toBeGreaterThan(50);
+		expect(DECLARED.size).toBeGreaterThan(80);
+	});
+
+	test("every component has one", () => {
+		const missing = [...DECLARED]
+			.filter(([name]) => !BOUND.has(name))
+			.map(([name, path]) => `${name} (${path.slice(SRC.length + 1)})`);
+		expect(missing).toEqual([]);
+	});
+
+	// Two bindings on one component is a rename that only landed in one place.
+	test("no component has two", () => {
+		const doubled = [...BOUND].filter(([, values]) => values.length > 1).map(([name]) => name);
+		expect(doubled).toEqual([]);
+	});
+
+	test("every name is a DelacourUI path", () => {
+		const wrong = [...BOUND]
+			.filter(([, values]) => values.some((value) => !SHAPE.test(value)))
+			.map(([name, values]) => `${name} = ${values[0]}`);
+		expect(wrong).toEqual([]);
+	});
+
+	// Two components answering to one name is a copy-pasted part file.
+	test("no two components share a name", () => {
+		const seen = new Map<string, string>();
+		const clashes: string[] = [];
+		for (const [name, values] of BOUND) {
+			for (const value of values) {
+				const owner = seen.get(value);
+				if (owner) clashes.push(`${value}: ${owner} and ${name}`);
+				else seen.set(value, name);
+			}
+		}
+		expect(clashes).toEqual([]);
+	});
+
+	// A part's name is its path in the public API, so its root's name is a prefix
+	// of it. This is what keeps `Badge.Label` from drifting to `Badge.Text`.
+	test("every name descends from a component that exists", () => {
+		const names = new Set([...BOUND.values()].flat());
+		const orphans = [...names].filter((name) => {
+			const parent = name.slice(0, name.lastIndexOf("."));
+			return parent !== "DelacourUI" && !names.has(parent);
+		});
+		expect(orphans).toEqual([]);
+	});
+});

package/src/docs.test.ts

@@ -0,0 +1,98 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SRC = import.meta.dirname;
+const COMPONENTS = join(SRC, "components");
+const PACKAGE_DOC = join(SRC, "..", "AGENTS.md");
+const PACKAGE_JSON = join(SRC, "..", "package.json");
+
+/**
+ * Every component folder must carry an `AGENTS.md`, and the package doc must
+ * index it.
+ *
+ * `Radio` shipped exported, tested and rendered in the playground, and stayed
+ * undocumented for fifteen commits — while nine bullets in other sections
+ * already pointed at rules nobody had written down. Nothing caught it, because
+ * nothing was looking. This looks.
+ *
+ * The index table is the second assertion for a reason: a folder can hold an
+ * `AGENTS.md` nobody can find. A component absent from the table is a component
+ * an agent reaches only by already knowing it exists, which is the same failure
+ * one step later.
+ *
+ * Like `display-name.test.ts` and `styles/tokens.test.ts`, this reads the tree as
+ * **text** and imports nothing from it. That is the move available whenever a
+ * convention is real but no renderer can check it — and `bun test` cannot render
+ * React Native at all.
+ */
+
+/** Every directory under `src/components/`, by folder name. */
+function componentFolders(): string[] {
+	return readdirSync(COMPONENTS, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.sort();
+}
+
+/**
+ * The folder names the package doc's index table lists.
+ *
+ * Matched on the export subpath rather than the heading, because the two are not
+ * the same word: `provider` is `DelacourProvider` and `list-group` is
+ * `ListGroup`. The subpath is the unambiguous key, and it is the string a
+ * consumer actually types.
+ *
+ * The package name is read from `package.json` rather than written out here, so
+ * a rename cannot leave this matching a name nobody publishes any more. It did
+ * once: the literal was a regex, escaped slashes and all, so the rename that
+ * swept every other mention of the old name walked straight past it and every
+ * component read as undocumented.
+ */
+function indexedFolders(): string[] {
+	const doc = readFileSync(PACKAGE_DOC, "utf-8");
+	const { name } = JSON.parse(readFileSync(PACKAGE_JSON, "utf-8")) as { name: string };
+	const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const rows = doc.matchAll(new RegExp(`\\[\`?${escaped}/([a-z-]+)\`?\\]|\`${escaped}/([a-z-]+)\``, "g"));
+	return [...new Set([...rows].map(([, a, b]) => a ?? b))].sort();
+}
+
+const FOLDERS = componentFolders();
+const INDEXED = indexedFolders();
+
+describe("component docs", () => {
+	// A walker that found nothing would let every assertion below pass on an
+	// empty set, so the suite would stay green while the convention rotted.
+	test("finds the component tree", () => {
+		expect(FOLDERS.length).toBeGreaterThan(15);
+	});
+
+	test("every component folder has an AGENTS.md", () => {
+		const missing = FOLDERS.filter((name) => !existsSync(join(COMPONENTS, name, "AGENTS.md")));
+		expect(missing).toEqual([]);
+	});
+
+	// An empty file passes the check above and helps nobody.
+	test("no component doc is a stub", () => {
+		const stubs = FOLDERS.filter((name) => {
+			const path = join(COMPONENTS, name, "AGENTS.md");
+			if (!existsSync(path)) return false;
+			const doc = readFileSync(path, "utf-8");
+			return !doc.startsWith("# ") || doc.split("\n").length < 10;
+		});
+		expect(stubs).toEqual([]);
+	});
+
+	// This is the assertion that would have caught Radio.
+	test("every component is named in the package doc", () => {
+		const unlisted = FOLDERS.filter((name) => !INDEXED.includes(name));
+		expect(unlisted).toEqual([]);
+	});
+
+	// A row naming a folder that no longer exists is a rename that landed in one
+	// place, and it sends a reader to a path that will not resolve.
+	test("the package doc names no component that does not exist", () => {
+		const orphans = INDEXED.filter((name) => !FOLDERS.includes(name));
+		expect(orphans).toEqual([]);
+	});
+});

package/src/expo/navigation-theme.tsx

@@ -0,0 +1,58 @@
+import { DarkTheme, DefaultTheme, ThemeProvider } from "expo-router";
+import { type ReactElement, type ReactNode, useMemo } from "react";
+import { useNavigationTheme } from "../hooks/use-navigation-theme";
+
+export type NavigationThemeProps = {
+	children: ReactNode;
+};
+
+/**
+ * Hands the navigator this library's theme colours.
+ *
+ * Mount it around a `Stack`, `Tabs` or `Drawer`, inside `DelacourProvider`.
+ *
+ * Not decoration. `expo-router` mounts its `NavigationContainer` with no
+ * `theme`, so React Navigation's light default stands however dark the app is —
+ * and on iOS the native stack hands `colors.background` to the
+ * `UINavigationController`'s view, which is the slab visible between the cards
+ * during a push and at their rounded corners. That layer is set from the theme
+ * with no escape hatch, so a `contentStyle` in `screenOptions` cannot reach it.
+ *
+ * `ThemeProvider` comes from `expo-router`, which vendors React Navigation:
+ * `@react-navigation/native` is not a package this monorepo can resolve.
+ *
+ * The framework's own base theme is spread underneath rather than replaced,
+ * because `ReactNavigation.Theme` also carries `fonts`, whose shape is
+ * platform-specific — restating it here would be a second definition able to
+ * drift from the one React Navigation actually ships. Only the colours this
+ * library owns are overridden, and `DarkTheme`'s `rgb(1, 1, 1)` background is
+ * exactly the kind of near-miss that makes overriding worth doing.
+ *
+ * Re-renders on a theme change and nothing else, so keep it below the
+ * providers — they have no reason to remount when the palette swaps.
+ *
+ * @example
+ * // app/_layout.tsx
+ * import { DelacourProvider } from "@delacour/react-native-ui/provider";
+ * import { NavigationTheme } from "@delacour/react-native-ui/expo/navigation-theme";
+ * import { Stack } from "expo-router";
+ *
+ * export default function RootLayout() {
+ *   return (
+ *     <DelacourProvider>
+ *       <NavigationTheme>
+ *         <Stack screenOptions={{ headerShown: false }} />
+ *       </NavigationTheme>
+ *     </DelacourProvider>
+ *   );
+ * }
+ */
+export function NavigationTheme({ children }: NavigationThemeProps): ReactElement {
+	const { dark, colors } = useNavigationTheme();
+	const base = dark ? DarkTheme : DefaultTheme;
+
+	const value = useMemo(() => ({ ...base, colors: { ...base.colors, ...colors }, dark }), [base, colors, dark]);
+
+	return <ThemeProvider value={value}>{children}</ThemeProvider>;
+}
+NavigationTheme.displayName = "DelacourUI.NavigationTheme";

package/src/hooks/use-controllable-state.ts

@@ -0,0 +1,45 @@
+import { useCallback, useRef, useState } from "react";
+
+type UseControllableStateOptions<T> = {
+	/** Controlled value. When not `undefined` the hook defers to the caller. */
+	value?: T;
+	/** Initial value used while uncontrolled. */
+	defaultValue: T;
+	onChange?: (value: T) => void;
+};
+
+/**
+ * Supports both controlled and uncontrolled usage from one hook.
+ *
+ * While `value` is undefined the state is held internally; once a value is
+ * passed the caller owns it and the setter only reports upward. Which mode is
+ * in play is locked in on first render — switching later is a caller bug and
+ * warns in development rather than silently changing behaviour.
+ */
+export function useControllableState<T>({
+	value,
+	defaultValue,
+	onChange,
+}: UseControllableStateOptions<T>): [T, (next: T) => void] {
+	const isControlled = value !== undefined;
+	const wasControlled = useRef(isControlled);
+	const [uncontrolled, setUncontrolled] = useState<T>(defaultValue);
+
+	if (process.env.NODE_ENV !== "production" && wasControlled.current !== isControlled) {
+		console.warn(
+			`useControllableState: switched from ${wasControlled.current ? "controlled" : "uncontrolled"} to ` +
+				`${isControlled ? "controlled" : "uncontrolled"}. Pick one for the lifetime of the component.`
+		);
+		wasControlled.current = isControlled;
+	}
+
+	const setValue = useCallback(
+		(next: T) => {
+			if (!isControlled) setUncontrolled(next);
+			onChange?.(next);
+		},
+		[isControlled, onChange]
+	);
+
+	return [isControlled ? value : uncontrolled, setValue];
+}