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

package/src/lib/compose-refs.ts

@@ -0,0 +1,37 @@
+import type { Ref } from "react";
+
+type RefCleanup = () => void;
+
+/**
+ * Fans a single node out to several refs.
+ *
+ * React 19 lets a callback ref return a cleanup function. When any of the given
+ * refs does, the composed ref returns a cleanup of its own that runs each child
+ * cleanup and nulls out every object ref.
+ */
+export function composeRefs<T>(...refs: (Ref<T> | undefined)[]): (node: T | null) => RefCleanup | undefined {
+	return (node) => {
+		const cleanups: RefCleanup[] = [];
+
+		for (const ref of refs) {
+			if (!ref) continue;
+
+			if (typeof ref === "function") {
+				const result = ref(node);
+				if (typeof result === "function") cleanups.push(result);
+				continue;
+			}
+
+			ref.current = node;
+		}
+
+		if (cleanups.length === 0) return undefined;
+
+		return () => {
+			for (const cleanup of cleanups) cleanup();
+			for (const ref of refs) {
+				if (ref && typeof ref !== "function") ref.current = null;
+			}
+		};
+	};
+}

package/src/lib/keyboard-animation.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "bun:test";
+import { shouldResetKeyboardAnimation } from "./keyboard-animation";
+
+describe("shouldResetKeyboardAnimation", () => {
+	test("leaves a genuinely focused keyboard alone", () => {
+		// The guard must never fight a real keyboard. Every open-looking state is
+		// legitimate while an input holds focus, including a mid-animation one.
+		for (const [progress, height] of [
+			[0, 0],
+			[0.5, -160],
+			[1, -336],
+		] as const) {
+			expect(shouldResetKeyboardAnimation({ hasFocusedInput: true, height, progress })).toBe(false);
+		}
+	});
+
+	test("repairs an open state with nothing focused", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -336, progress: 1 })).toBe(true);
+	});
+
+	test("repairs a half-open state, which is what an interrupted dismiss leaves behind", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -160, progress: 0.5 })).toBe(true);
+	});
+
+	test("repairs either value on its own — the two are written separately", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: 0, progress: 1 })).toBe(true);
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: -336, progress: 0 })).toBe(true);
+	});
+
+	test("is a no-op on an already-closed state, so mounting never schedules a pointless write", () => {
+		expect(shouldResetKeyboardAnimation({ hasFocusedInput: false, height: 0, progress: 0 })).toBe(false);
+	});
+});

package/src/lib/keyboard-animation.ts

@@ -0,0 +1,28 @@
+/**
+ * Whether `KeyboardProvider`'s shared animation values are provably stale.
+ *
+ * Lives here, free of React Native imports, so the decision is reachable from
+ * `bun test` — `hooks/use-keyboard-state-sync` cannot be, since Bun's
+ * transpiler cannot parse React Native's Flow-typed source. See AGENTS.md.
+ *
+ * `hasFocusedInput` MUST come from React Native's own focus registry
+ * (`TextInput.State.currentlyFocusedInput()`), never from
+ * `KeyboardController.isVisible()`. The latter is fed by the very
+ * `keyboardWillShow` / `keyboardDidHide` notifications that go missing in the
+ * failure this guard exists for, so in the broken case it reads a stale `true`
+ * and would veto the repair. RN's registry is driven by the input's own native
+ * focus and blur — a genuinely independent signal.
+ */
+export function shouldResetKeyboardAnimation(state: {
+	/** `KeyboardProvider`'s shared progress, 0 closed through 1 open. */
+	progress: number;
+	/** `KeyboardProvider`'s shared height, negative while open. */
+	height: number;
+	/** Whether React Native's focus registry holds a focused `TextInput`. */
+	hasFocusedInput: boolean;
+}): boolean {
+	"worklet";
+	// Never fight a real, focused keyboard.
+	if (state.hasFocusedInput) return false;
+	return state.progress !== 0 || state.height !== 0;
+}

package/src/lib/merge-props.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, test } from "bun:test";
+import { mergeProps } from "./merge-props";
+
+describe("mergeProps", () => {
+	test("child props override slot props", () => {
+		expect(mergeProps({ testID: "slot" }, { testID: "child" })).toMatchObject({ testID: "child" });
+	});
+
+	test("slot props survive when the child omits them", () => {
+		expect(mergeProps({ accessibilityRole: "button" }, {})).toMatchObject({ accessibilityRole: "button" });
+	});
+
+	test("chains event handlers slot-first", () => {
+		const order: string[] = [];
+		const merged = mergeProps<{ onPress?: (v: string) => void }>(
+			{
+				onPress: (v: string) => {
+					order.push(`slot:${v}`);
+				},
+			},
+			{
+				onPress: (v: string) => {
+					order.push(`child:${v}`);
+				},
+			}
+		);
+		merged.onPress?.("x");
+		expect(order).toEqual(["slot:x", "child:x"]);
+	});
+
+	test("keeps a lone handler from either side", () => {
+		let hit = false;
+		const fromSlot = mergeProps<{ onPress?: () => void }>(
+			{
+				onPress: () => {
+					hit = true;
+				},
+			},
+			{}
+		);
+		fromSlot.onPress?.();
+		expect(hit).toBe(true);
+
+		hit = false;
+		const fromChild = mergeProps<{ onPress?: () => void }>(
+			{},
+			{
+				onPress: () => {
+					hit = true;
+				},
+			}
+		);
+		fromChild.onPress?.();
+		expect(hit).toBe(true);
+	});
+
+	test("merges className through cn so the child wins conflicts", () => {
+		const merged = mergeProps({ className: "p-2 bg-primary" }, { className: "bg-secondary" });
+		expect(merged.className).toBe("p-2 bg-secondary");
+	});
+
+	test("flattens style into an array with the child last", () => {
+		const merged = mergeProps({ style: { opacity: 1 } }, { style: { opacity: 0.5 } });
+		expect(merged.style).toEqual([{ opacity: 1 }, { opacity: 0.5 }]);
+	});
+
+	test("keeps a single style untouched", () => {
+		expect(mergeProps({ style: { flex: 1 } }, {}).style).toEqual({ flex: 1 });
+	});
+
+	test("does not treat a non-function on* value as a handler", () => {
+		expect(mergeProps({ onPress: undefined }, { onPress: undefined }).onPress).toBeUndefined();
+	});
+
+	test("never mutates its inputs", () => {
+		const slot = { className: "p-2", onPress: () => {} };
+		const child = { className: "p-4" };
+		mergeProps(slot, child);
+		expect(slot.className).toBe("p-2");
+		expect(child.className).toBe("p-4");
+	});
+});

package/src/lib/merge-props.ts

@@ -0,0 +1,47 @@
+import { cn } from "./cn";
+
+type UnknownProps = Record<string, unknown>;
+
+function isEventHandlerKey(key: string): boolean {
+	return key.startsWith("on") && key.length > 2 && key[2] === key[2]?.toUpperCase();
+}
+
+/**
+ * Merges a slot's own props with those of the element it renders into.
+ *
+ * Child props win, with three exceptions: event handlers are chained
+ * slot-first-then-child so neither side is silently dropped, `className` is
+ * merged through {@link cn} so the child's utilities beat conflicting slot
+ * ones, and `style` is flattened into an array with the child last (React
+ * Native resolves style arrays left to right).
+ */
+export function mergeProps<T extends UnknownProps>(slotProps: UnknownProps, childProps: UnknownProps): T {
+	const merged: UnknownProps = { ...slotProps };
+
+	for (const key of Object.keys(childProps)) {
+		const slotValue = slotProps[key];
+		const childValue = childProps[key];
+
+		if (isEventHandlerKey(key) && typeof slotValue === "function" && typeof childValue === "function") {
+			merged[key] = (...args: unknown[]) => {
+				(slotValue as (...a: unknown[]) => unknown)(...args);
+				return (childValue as (...a: unknown[]) => unknown)(...args);
+			};
+			continue;
+		}
+
+		if (key === "className") {
+			merged[key] = cn(slotValue as string, childValue as string);
+			continue;
+		}
+
+		if (key === "style" && slotValue != null && childValue != null) {
+			merged[key] = [slotValue, childValue].flat();
+			continue;
+		}
+
+		merged[key] = childValue;
+	}
+
+	return merged as T;
+}

package/src/lib/navigation-theme.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test";
+import { declaredTokens } from "../styles/theme-tokens.test";
+import { NAVIGATION_THEME_TOKENS } from "./navigation-theme";
+
+const LIGHT = declaredTokens("light");
+const DARK = declaredTokens("dark");
+
+/** The slots React Navigation's theme actually has. Missing one falls back to its light default. */
+const REACT_NAVIGATION_SLOTS = ["background", "card", "text", "border", "primary", "notification"] as const;
+
+describe("the theme.css reader", () => {
+	// The assertions below are only worth anything if the parse found something.
+	test("finds both variants", () => {
+		expect(LIGHT.size).toBeGreaterThan(0);
+		expect(DARK.size).toBeGreaterThan(0);
+	});
+});
+
+describe("NAVIGATION_THEME_TOKENS", () => {
+	test("covers every slot React Navigation's theme has", () => {
+		expect(Object.keys(NAVIGATION_THEME_TOKENS).sort()).toEqual([...REACT_NAVIGATION_SLOTS].sort());
+	});
+
+	// A slot pointing at a token no theme emits resolves to undefined, gets
+	// dropped, and silently leaves React Navigation's light default in place —
+	// which is the exact failure this whole hook exists to fix.
+	test("names only tokens the light theme declares", () => {
+		for (const token of Object.values(NAVIGATION_THEME_TOKENS)) {
+			expect(LIGHT.has(token)).toBe(true);
+		}
+	});
+
+	test("names only tokens the dark theme declares", () => {
+		for (const token of Object.values(NAVIGATION_THEME_TOKENS)) {
+			expect(DARK.has(token)).toBe(true);
+		}
+	});
+
+	test("maps the background slot to the token a screen paints itself with", () => {
+		// Screen's root is `bg-background`. If these two ever disagree, the
+		// container behind a transition stops matching the cards in front of it.
+		expect(NAVIGATION_THEME_TOKENS.background).toBe("background");
+	});
+
+	test("gives every slot its own token, so no two slots collapse together", () => {
+		const tokens = Object.values(NAVIGATION_THEME_TOKENS);
+		expect(new Set(tokens).size).toBe(tokens.length);
+	});
+});

package/src/lib/navigation-theme.ts

@@ -0,0 +1,53 @@
+/**
+ * React Navigation's colour slots, mapped to this library's semantic tokens.
+ *
+ * Lives here, free of React Native imports, so the mapping is reachable from
+ * `bun test` — `hooks/use-navigation-theme` cannot be, since Bun's transpiler
+ * cannot parse React Native's Flow-typed source. See AGENTS.md.
+ *
+ * A slot pointing at a token no theme emits would resolve to `undefined`, be
+ * dropped, and silently leave React Navigation's own light default in place —
+ * which is the exact failure the hook exists to fix. The test asserts every
+ * token here is declared in both variants of `styles/theme.css`.
+ */
+export const NAVIGATION_THEME_TOKENS = {
+	background: "background",
+	card: "card",
+	text: "foreground",
+	border: "border",
+	primary: "primary",
+	notification: "destructive",
+} as const;
+
+export type NavigationThemeSlot = keyof typeof NAVIGATION_THEME_TOKENS;
+
+/** The resolved colours, and whether the active theme is a dark one. */
+export type NavigationTheme = {
+	dark: boolean;
+	/**
+	 * Resolved colours by slot. A slot the active theme does not emit is
+	 * ABSENT rather than `undefined`, so spreading this over a base theme
+	 * leaves that slot's default in place instead of punching a hole in it.
+	 */
+	colors: Partial<Record<NavigationThemeSlot, string>>;
+};
+
+/**
+ * Drops the slots that resolved to nothing.
+ *
+ * The result is spread over a base theme, and `{ ...base, background: undefined }`
+ * overwrites the default with `undefined` rather than leaving it — a navigator
+ * with no background at all, which reads as a transparent hole rather than as
+ * a missing token.
+ */
+export function omitUnresolvedColors(
+	colors: Record<NavigationThemeSlot, string | undefined>
+): Partial<Record<NavigationThemeSlot, string>> {
+	const resolved: Partial<Record<NavigationThemeSlot, string>> = {};
+
+	for (const [slot, value] of Object.entries(colors) as [NavigationThemeSlot, string | undefined][]) {
+		if (value !== undefined) resolved[slot] = value;
+	}
+
+	return resolved;
+}

package/src/lib/slot.tsx

@@ -0,0 +1,45 @@
+import { Children, cloneElement, isValidElement, type ReactElement, type ReactNode, type Ref } from "react";
+import { composeRefs } from "./compose-refs";
+import { mergeProps } from "./merge-props";
+
+type SlotProps = {
+	children?: ReactNode;
+	[key: string]: unknown;
+};
+
+type ChildProps = Record<string, unknown> & { ref?: Ref<unknown> };
+
+/**
+ * Renders its props into its single child instead of emitting an element.
+ *
+ * This is what backs the `asChild` prop: `<Pressable asChild><Button /></Pressable>`
+ * gives the Button the Pressable's behaviour with no extra View in the tree.
+ * Props are combined by {@link mergeProps} and refs by {@link composeRefs}.
+ *
+ * React 19 exposes `ref` as an ordinary prop, so no `forwardRef` is involved.
+ *
+ * Do not pass a Reanimated style through this. React Native deep freezes style
+ * props on a non-animated component in development, and Reanimated's effect
+ * then throws trying to write to the frozen object. `Pressable` handles that
+ * case by rendering the child through an animated counterpart of its own type.
+ */
+export function Slot({ children, ...slotProps }: SlotProps): ReactElement {
+	const count = Children.count(children);
+
+	if (count !== 1) {
+		throw new Error(`Slot expects exactly one child element, received ${count}. Did you mean to omit \`asChild\`?`);
+	}
+
+	const child = Children.only(children);
+
+	if (!isValidElement(child)) {
+		throw new Error("Slot expects a single React element child; text and fragments cannot receive props.");
+	}
+
+	const childProps = child.props as ChildProps;
+	const merged = mergeProps<ChildProps>(slotProps, childProps);
+	merged.ref = composeRefs(slotProps.ref as Ref<unknown> | undefined, childProps.ref);
+
+	return cloneElement(child, merged);
+}
+Slot.displayName = "DelacourUI.Slot";

package/src/lib/tv.ts

@@ -0,0 +1,20 @@
+import { createTV } from "tailwind-variants";
+import { TW_MERGE_CONFIG } from "../styles/tokens";
+
+/**
+ * `tailwind-variants`, taught the semantic size tokens from `tokens.css`.
+ *
+ * Import `tv` from here in every `*.variants.ts` — never from
+ * `tailwind-variants` directly. `tv()` merges its own slots and variants
+ * through a tailwind-merge instance it builds itself, entirely separate from
+ * the one behind `cn()`, and a bare `tv` does not know what `button-md` is.
+ *
+ * That is not a cosmetic gap. An unrecognised `text-button-md` lands in
+ * tailwind-merge's text *colour* group alongside `text-primary-foreground`, the
+ * two are judged to conflict, and the label loses its colour — no error, just a
+ * button whose text quietly renders in the wrong shade.
+ *
+ * Free of React Native imports so variants files stay unit-testable. See
+ * AGENTS.md.
+ */
+export const tv = createTV({ twMergeConfig: TW_MERGE_CONFIG });

package/src/styles/base.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "uniwind";

package/src/styles/geometry.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const TOKENS_CSS = readFileSync(join(import.meta.dirname, "tokens.css"), "utf-8");
+const THEME_CSS = readFileSync(join(import.meta.dirname, "theme.css"), "utf-8");
+
+/**
+ * Every `--name: value` declaration inside one `@variant` block of `theme.css`.
+ *
+ * Source text, not an import: these are CSS custom properties and no renderer
+ * is involved, so reading the file is the only way to assert against them.
+ * `styles/tokens.test.ts` and `styles/theme-tokens.test.ts` do the same.
+ */
+function variantDeclarations(variant: string): Map<string, string> {
+	const block = THEME_CSS.split(`@variant ${variant} {`)[1]?.split("}")[0] ?? "";
+	const found = new Map<string, string>();
+
+	for (const [, name, value] of block.matchAll(/(--[\w-]+):\s*([^;]+);/g)) {
+		found.set(name as string, (value as string).trim());
+	}
+
+	return found;
+}
+
+/** The same, from `tokens.css`'s first `@theme` block — the copy `apps/web` reads. */
+function themeDeclarations(): Map<string, string> {
+	const block = TOKENS_CSS.split("@theme {")[1]?.split("\n}")[0] ?? "";
+	const found = new Map<string, string>();
+
+	for (const [, name, value] of block.matchAll(/(--[\w-]+):\s*([^;]+);/g)) {
+		found.set(name as string, (value as string).trim());
+	}
+
+	return found;
+}
+
+const NATIVE = variantDeclarations("native");
+const TOKENS = themeDeclarations();
+
+describe("the CSS readers", () => {
+	test("find both blocks", () => {
+		expect(NATIVE.size).toBeGreaterThan(0);
+		expect(TOKENS.size).toBeGreaterThan(0);
+	});
+});
+
+/**
+ * The geometry is declared twice, and the two copies must agree.
+ *
+ * `tokens.css` is the copy `apps/web` reads — the docs site imports only that
+ * file. `theme.css`'s `@variant native` block is the copy React Native reads,
+ * and it exists because Uniwind inlines a plain `@theme` declaration at build
+ * time: without it every one of these numbers would be frozen into the bundle
+ * and the playground's Style and Radius axes would silently do nothing.
+ *
+ * Two hand-maintained copies of one number always drift. This is what stops it.
+ */
+describe("the geometry block", () => {
+	test("restates every number tokens.css declares, with the same value", () => {
+		for (const [name, value] of NATIVE) {
+			expect(TOKENS.get(name), `tokens.css declares no ${name}`).toBeDefined();
+			expect(TOKENS.get(name), `${name} disagrees between tokens.css and theme.css`).toBe(value);
+		}
+	});
+
+	/**
+	 * A token left out of the native block is not a build error — it is a
+	 * control in the playground's customizer that moves nothing, which is the
+	 * kind of gap only a person notices, late.
+	 */
+	test("covers every scale a customizer can retune", () => {
+		const required = [
+			"--radius",
+			...(["sm", "md", "lg"] as const).flatMap((step) => [
+				`--spacing-button-${step}`,
+				`--text-button-${step}`,
+				`--radius-button-${step}`,
+				`--spacing-input-${step}`,
+				`--text-input-${step}`,
+			]),
+			...(["xs", "sm", "md", "lg", "xl", "2xl"] as const).map((step) => `--spacing-icon-${step}`),
+			"--spacing-navbar-row",
+			"--spacing-screen-gutter",
+			...(["sm", "md", "lg"] as const).map((step) => `--spacing-chart-${step}`),
+		];
+
+		for (const name of required) {
+			expect(NATIVE.has(name), `theme.css's @variant native declares no ${name}`).toBe(true);
+		}
+	});
+
+	// The generic corner scale is derived from `--radius` in `tokens.css`'s
+	// `@theme inline` block. Restating a derived step here would pin it and
+	// break the one thing the Radius axis relies on.
+	test("does not restate the derived corner scale", () => {
+		for (const step of ["xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "full"]) {
+			expect(NATIVE.has(`--radius-${step}`)).toBe(false);
+		}
+	});
+});
+
+/** The heading face is a token like the other three, or `Text.Display` cannot follow a theme. */
+describe("the font families", () => {
+	test("declare all four for both platforms", () => {
+		for (const platform of ["ios", "android"] as const) {
+			const declared = variantDeclarations(platform);
+
+			for (const token of ["--font-sans", "--font-serif", "--font-mono", "--font-heading"] as const) {
+				expect(declared.get(token), `@variant ${platform} declares no ${token}`).toBeDefined();
+				// React Native's `fontFamily` takes one name and no fallback
+				// list, so a comma-separated web stack resolves to nothing.
+				expect(declared.get(token)).not.toContain(",");
+			}
+		}
+	});
+});

package/src/styles/index.css

@@ -0,0 +1,3 @@
+@import "./base.css";
+@import "./tokens.css";
+@import "./theme.css";