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

package/src/hooks/use-keyboard-state-sync.tsx

@@ -0,0 +1,147 @@
+import { useCallback, useEffect } from "react";
+import { AppState, type AppStateStatus, TextInput } from "react-native";
+import { KeyboardEvents, useKeyboardContext } from "react-native-keyboard-controller";
+import type { SharedValue } from "react-native-reanimated";
+import { scheduleOnUI } from "react-native-worklets";
+import { shouldResetKeyboardAnimation } from "../lib/keyboard-animation";
+
+// Re-exported so the pure decision is reachable beside the hook that acts on
+// it; it lives in `lib` only because `bun test` cannot follow this module's
+// React Native imports.
+export { shouldResetKeyboardAnimation } from "../lib/keyboard-animation";
+
+/** The one pair of animation values `KeyboardProvider` shares with the whole app. */
+type KeyboardAnimationValues = {
+	progress: SharedValue<number>;
+	height: SharedValue<number>;
+};
+
+/**
+ * Snaps the shared progress and height back to closed when they are stale.
+ *
+ * The focus check stays on the JS thread — that is where the registry lives —
+ * and the read-and-write happens inside one worklet, so the UI thread's own
+ * values are what the decision is made against.
+ */
+export function reconcileKeyboardAnimation({ progress, height }: KeyboardAnimationValues): void {
+	if (TextInput.State.currentlyFocusedInput() != null) return;
+
+	scheduleOnUI(() => {
+		"worklet";
+		if (!shouldResetKeyboardAnimation({ hasFocusedInput: false, height: height.value, progress: progress.value })) {
+			return;
+		}
+		// Snap, never animate: the keyboard is already gone, so there is nothing
+		// to animate towards and a timing curve would just be a visible glitch.
+		progress.value = 0;
+		height.value = 0;
+	});
+}
+
+/**
+ * Repairs the keyboard animation values `KeyboardProvider` shares with the
+ * whole app when the keyboard disappears without telling them.
+ *
+ * `KeyboardProvider` owns exactly ONE pair of Reanimated shared values
+ * (`progress` / `height`), and on iOS they are written only by
+ * `onKeyboardMoveStart` — emitted from `keyboardWillAppear` /
+ * `keyboardWillDisappear` — and by the interactive-move KVO.
+ * `onKeyboardMoveEnd`, the event `keyboardDidDisappear` emits, updates them on
+ * ANDROID ONLY, and the library has no app-lifecycle re-sync at all.
+ *
+ * So any teardown that produces no `keyboardWillHide` — an interactive dismiss
+ * interrupted by navigation, a native-stack pop, a call interruption, an app
+ * suspend — leaves both values pinned at their open state, app-wide, forever.
+ * Every consumer then renders "keyboard open" over a screen with no keyboard on
+ * it: `Screen.Footer` translates its content up by a keyboard height, and
+ * `useScreenScrollInsets` reserves a keyboard-sized spacer under content that
+ * needs none.
+ *
+ * Deliberately NOT used here, and why:
+ * - `KeyboardController.dismiss()` resolves on `keyboardDidHide` and natively
+ *   just resigns the first responder. With the keyboard already gone there is
+ *   no responder, nothing fires, and the values stay stuck — and it would blur
+ *   an input the user legitimately has focused.
+ * - `setEnabled(false/true)` unmounts and remounts the native observers,
+ *   dropping some of them, and never touches the shared values.
+ * - Gating each reader behind a screen-local flag adds a second driver to every
+ *   consumer and still leaves the globals wrong for the next screen.
+ *
+ * Mount ONCE, directly inside `<KeyboardProvider>` — or let
+ * `DelacourProvider` do it.
+ */
+export function useKeyboardStateSync(): void {
+	const { reanimated } = useKeyboardContext();
+
+	useEffect(() => {
+		const appState = AppState.addEventListener("change", (status: AppStateStatus) => {
+			if (status === "active") reconcileKeyboardAnimation(reanimated);
+		});
+
+		// The `did` events carry the authoritative terminal state, and on iOS the
+		// provider throws them away. Mirroring them here is what makes a lost
+		// `will` event self-heal on the very next keyboard transition.
+		const didHide = KeyboardEvents.addListener("keyboardDidHide", () => {
+			scheduleOnUI(() => {
+				"worklet";
+				reanimated.progress.value = 0;
+				reanimated.height.value = 0;
+			});
+		});
+		const didShow = KeyboardEvents.addListener("keyboardDidShow", (event) => {
+			// The same height `onKeyboardMoveStart` delivers — both come from the
+			// observer's `keyboardHeight`.
+			const keyboardHeight = event.height;
+			scheduleOnUI(() => {
+				"worklet";
+				reanimated.progress.value = 1;
+				reanimated.height.value = -keyboardHeight;
+			});
+		});
+
+		// The values may already be stale by the time this mounts.
+		reconcileKeyboardAnimation(reanimated);
+
+		return () => {
+			appState.remove();
+			didHide.remove();
+			didShow.remove();
+		};
+	}, [reanimated]);
+}
+
+/**
+ * Render-free host for {@link useKeyboardStateSync}, to drop into a layout tree.
+ *
+ * `DelacourProvider` already mounts this — write it out only when composing the
+ * root providers by hand.
+ *
+ * @example
+ * <KeyboardProvider>
+ *   <KeyboardStateSync />
+ *   <Stack />
+ * </KeyboardProvider>
+ */
+export function KeyboardStateSync(): null {
+	useKeyboardStateSync();
+	return null;
+}
+KeyboardStateSync.displayName = "DelacourUI.KeyboardStateSync";
+
+/**
+ * Screen-level repair, for a surface that mounts into an already-poisoned
+ * global state.
+ *
+ * Idempotent and cheap — a no-op whenever an input is genuinely focused, which
+ * is what keeps "navigate to a new screen with the keyboard still open"
+ * working. `Screen.Footer` runs this on mount so a screen repairs itself even
+ * in an app that never mounted {@link KeyboardStateSync}.
+ */
+export function useKeyboardAnimationGuard(): void {
+	const { reanimated } = useKeyboardContext();
+	const reconcile = useCallback(() => reconcileKeyboardAnimation(reanimated), [reanimated]);
+
+	useEffect(() => {
+		reconcile();
+	}, [reconcile]);
+}

package/src/hooks/use-navigation-theme.ts

@@ -0,0 +1,78 @@
+import { useMemo } from "react";
+import { useUniwind } from "uniwind";
+import { NAVIGATION_THEME_TOKENS, type NavigationTheme, omitUnresolvedColors } from "../lib/navigation-theme";
+import { useThemeColor } from "./use-theme-color";
+
+// Re-exported so the mapping is reachable beside the hook that reads it; it
+// lives in `lib` only because `bun test` cannot follow this module's React
+// Native imports.
+export {
+	NAVIGATION_THEME_TOKENS,
+	type NavigationTheme,
+	type NavigationThemeSlot,
+} from "../lib/navigation-theme";
+
+/**
+ * The active theme's colours, shaped for a React Navigation theme.
+ *
+ * Exists because a navigator paints its own chrome from its own theme, and
+ * nothing connects that to this library's tokens. `expo-router` mounts its
+ * `NavigationContainer` with no `theme`, so the light default stands however
+ * dark the app is: on iOS the native stack hands `colors.background` to the
+ * `UINavigationController`'s view, which is the slab visible between cards
+ * during a push. That layer is hardcoded to the theme, so a `contentStyle` in
+ * `screenOptions` cannot reach it — only a theme can.
+ *
+ * Returns plain values rather than a `Theme`, and imports nothing from a
+ * navigation library. That is deliberate: this package takes no navigation
+ * dependency — the same reason `Screen.Navbar.BackButton` takes an `onPress`
+ * instead of calling a router — so the app owns the wiring and this owns the
+ * colours. It also sidesteps restating React Navigation's `fonts`, whose shape
+ * is platform-specific and would be a second definition able to drift.
+ *
+ * `dark` comes from Uniwind's active theme, never React Native's
+ * `useColorScheme`: an app that lets the user force light or dark against the
+ * system setting would otherwise theme its navigator the wrong way round.
+ *
+ * Reactive. Every colour is read through {@link useThemeColor}, which
+ * subscribes to Uniwind's theme changes, so switching theme re-renders the
+ * caller with new values rather than needing a reload.
+ *
+ * @example
+ * // expo-router. `ThemeProvider` comes from `expo-router`, which vendors
+ * // React Navigation — `@react-navigation/native` does not resolve.
+ * import { DarkTheme, DefaultTheme, Stack, ThemeProvider } from "expo-router";
+ *
+ * function NavigationTheme({ children }: { children: ReactNode }) {
+ *   const { dark, colors } = useNavigationTheme();
+ *   const base = dark ? DarkTheme : DefaultTheme;
+ *   const value = useMemo(
+ *     () => ({ ...base, dark, colors: { ...base.colors, ...colors } }),
+ *     [base, dark, colors]
+ *   );
+ *
+ *   return <ThemeProvider value={value}>{children}</ThemeProvider>;
+ * }
+ */
+export function useNavigationTheme(): NavigationTheme {
+	const { theme } = useUniwind();
+
+	// Written out one call per slot rather than looped: a hook cannot be called
+	// from inside a map, however stable the list looks.
+	const background = useThemeColor(NAVIGATION_THEME_TOKENS.background);
+	const card = useThemeColor(NAVIGATION_THEME_TOKENS.card);
+	const text = useThemeColor(NAVIGATION_THEME_TOKENS.text);
+	const border = useThemeColor(NAVIGATION_THEME_TOKENS.border);
+	const primary = useThemeColor(NAVIGATION_THEME_TOKENS.primary);
+	const notification = useThemeColor(NAVIGATION_THEME_TOKENS.notification);
+
+	const dark = theme === "dark";
+
+	return useMemo(
+		() => ({
+			colors: omitUnresolvedColors({ background, border, card, notification, primary, text }),
+			dark,
+		}),
+		[dark, background, border, card, notification, primary, text]
+	);
+}

package/src/hooks/use-theme-color.ts

@@ -0,0 +1,44 @@
+import { useCSSVariable } from "uniwind";
+import { isLiteralColor, themeVariableName } from "../lib/color";
+
+/** Defined by every theme, so looking it up never misses and never warns. */
+const PROBE_VARIABLE = "--foreground";
+
+/**
+ * Reads a theme colour as a plain string for props that take a colour value
+ * rather than a style — icon `color`, gradient stops, chart series, and any
+ * third-party component that will not accept a className.
+ *
+ * Resolves against the nearest `ScopedTheme`, so it follows light/dark and any
+ * custom theme automatically. Prefer a `bg-*`/`text-*` className wherever the
+ * target actually accepts one.
+ *
+ * A literal colour — `#EC4899`, `rgb(...)` — passes straight through without
+ * being looked up, so a caller can hand one to any prop typed as a token
+ * without special-casing it.
+ *
+ * A token resolves only if the active theme actually emits its CSS variable.
+ * That is the semantic palette in `styles/theme.css` — Tailwind's own palette
+ * names (`emerald-500`) are not emitted unless some utility class references
+ * them. An unresolved token yields `undefined` rather than a bogus value.
+ *
+ * The variable looked up is the RAW name — `--destructive`, not
+ * `--color-destructive`. `theme.css` maps the raw names onto the `--color-*`
+ * namespace through `@theme inline`, and `inline` means Tailwind substitutes
+ * the value into each utility and emits no `--color-*` variable at all. Those
+ * names do not exist at runtime; the raw ones are the only thing there. They
+ * are also the names a shadcn theme is written in, so `useThemeColor("chart-1")`
+ * works on a pasted palette with no support from this package.
+ */
+export function useThemeColor(token: string): string | undefined {
+	const isLiteral = isLiteralColor(token);
+	const name = themeVariableName(token);
+
+	// A literal still has to go through the hook — hook order cannot be
+	// conditional — but it must not be the thing looked up. Uniwind logs a
+	// warning on every miss, and `--#EC4899` misses on every single render.
+	// Probe a variable that is always defined instead, and discard it.
+	const resolved = useCSSVariable(isLiteral ? PROBE_VARIABLE : name) as string | undefined;
+
+	return isLiteral ? token : resolved;
+}

package/src/icons/central.ts

@@ -0,0 +1 @@
+export * from "@central-icons-react-native/round-outlined-radius-1-stroke-1.5";

package/src/lib/cn.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "bun:test";
+import {
+	BUTTON_RADIUS_TOKENS,
+	BUTTON_SIZE_TOKENS,
+	BUTTON_TEXT_TOKENS,
+	ICON_SIZE_TOKENS,
+	INPUT_SIZE_TOKENS,
+	INPUT_TEXT_TOKENS,
+	SCREEN_SIZE_TOKENS,
+} from "../styles/tokens";
+import { cn } from "./cn";
+
+describe("cn", () => {
+	test("joins plain class strings", () => {
+		expect(cn("px-2", "py-1")).toBe("px-2 py-1");
+	});
+
+	test("drops falsy values", () => {
+		expect(cn("px-2", false, null, undefined, "", "py-1")).toBe("px-2 py-1");
+	});
+
+	test("resolves conditional objects and arrays", () => {
+		expect(cn(["px-2", { "py-1": true, "py-4": false }])).toBe("px-2 py-1");
+	});
+
+	test("last conflicting utility wins", () => {
+		expect(cn("p-2", "p-6")).toBe("p-6");
+		expect(cn("bg-primary", "bg-destructive")).toBe("bg-destructive");
+	});
+
+	test("keeps non-conflicting utilities from the same group", () => {
+		expect(cn("px-2", "py-4")).toBe("px-2 py-4");
+	});
+
+	test("an incoming className overrides the base", () => {
+		expect(cn("rounded-lg bg-primary", "bg-secondary")).toBe("rounded-lg bg-secondary");
+	});
+
+	test("returns an empty string for no input", () => {
+		expect(cn()).toBe("");
+	});
+});
+
+// Without these, tailwind-merge treats `h-button-md` as an unrecognised
+// utility and keeps it alongside a caller's `h-12`. Both would apply and the
+// winner would be whichever uniwind resolved last — the exact failure `cn`
+// exists to prevent, and an invisible one, since nothing errors.
+// A side corner survives an all-corner class emitted BEFORE it, and is
+// annihilated by one emitted after. `Button.Group` rests on that asymmetry: it
+// is why a joined member replaces its corner with a per-side pair rather than
+// layering a squaring class over the `rounded-button-*` the size axis would
+// otherwise leave behind. That class would delete the pair silently, with
+// nothing to see in a diff.
+describe("cn with a side corner", () => {
+	test("keeps a side class set after an all-corner one", () => {
+		for (const token of BUTTON_RADIUS_TOKENS) {
+			expect(cn(`rounded-${token}`, "rounded-e-none")).toBe(`rounded-${token} rounded-e-none`);
+		}
+	});
+
+	test("drops a side class set before an all-corner one", () => {
+		for (const token of BUTTON_RADIUS_TOKENS) {
+			expect(cn("rounded-e-none", `rounded-${token}`)).toBe(`rounded-${token}`);
+		}
+	});
+
+	test("lets a caller's all-corner class beat a whole per-side pair", () => {
+		for (const token of BUTTON_RADIUS_TOKENS) {
+			expect(cn(`rounded-s-${token} rounded-e-none`, "rounded-lg")).toBe("rounded-lg");
+		}
+	});
+});
+
+describe("cn with the semantic size tokens", () => {
+	test("a caller's plain utility replaces a token one", () => {
+		for (const token of BUTTON_SIZE_TOKENS) {
+			expect(cn(`h-${token}`, "h-12")).toBe("h-12");
+			expect(cn(`w-${token}`, "w-12")).toBe("w-12");
+		}
+		for (const token of ICON_SIZE_TOKENS) {
+			expect(cn(`size-${token}`, "size-6")).toBe("size-6");
+		}
+		for (const token of BUTTON_TEXT_TOKENS) {
+			expect(cn(`text-${token}`, "text-lg")).toBe("text-lg");
+		}
+		// The button's corner is a token like its height, so a caller who wants
+		// a squarer button writes `rounded-lg` and gets it.
+		for (const token of BUTTON_RADIUS_TOKENS) {
+			expect(cn(`rounded-${token}`, "rounded-lg")).toBe("rounded-lg");
+			expect(cn(`rounded-${token}`, "rounded-full")).toBe("rounded-full");
+		}
+		// A field's height is read on two axes — fixed for a single line,
+		// a floor for a multiline one — so `min-h` has to be recognised too.
+		for (const token of INPUT_SIZE_TOKENS) {
+			expect(cn(`h-${token}`, "h-12")).toBe("h-12");
+			expect(cn(`min-h-${token}`, "min-h-12")).toBe("min-h-12");
+		}
+		for (const token of INPUT_TEXT_TOKENS) {
+			expect(cn(`text-${token}`, "text-lg")).toBe("text-lg");
+		}
+		// The screen tokens are read on two different axes — `h-navbar-row` sizes
+		// the navbar's row, `px-screen-gutter` its horizontal padding — so both
+		// have to be recognised, not just the one each token was named for.
+		for (const token of SCREEN_SIZE_TOKENS) {
+			expect(cn(`h-${token}`, "h-12")).toBe("h-12");
+			expect(cn(`px-${token}`, "px-8")).toBe("px-8");
+		}
+	});
+
+	test("a token utility replaces a plain one", () => {
+		expect(cn("h-12", "h-button-sm")).toBe("h-button-sm");
+		expect(cn("size-6", "size-icon-xs")).toBe("size-icon-xs");
+		expect(cn("text-lg", "text-button-sm")).toBe("text-button-sm");
+		expect(cn("px-8", "px-screen-gutter")).toBe("px-screen-gutter");
+		expect(cn("min-h-12", "min-h-input-lg")).toBe("min-h-input-lg");
+		expect(cn("rounded-lg", "rounded-button-md")).toBe("rounded-button-md");
+	});
+
+	test("one token replaces another on the same axis", () => {
+		expect(cn("size-icon-sm", "size-icon-2xl")).toBe("size-icon-2xl");
+		expect(cn("h-button-sm", "h-button-lg")).toBe("h-button-lg");
+		expect(cn("h-input-sm", "h-input-lg")).toBe("h-input-lg");
+		expect(cn("text-input-sm", "text-input-lg")).toBe("text-input-lg");
+		expect(cn("rounded-button-sm", "rounded-button-lg")).toBe("rounded-button-lg");
+	});
+
+	test("tokens on different axes both survive", () => {
+		expect(cn("h-button-md", "w-button-md")).toBe("h-button-md w-button-md");
+		expect(cn("h-button-md", "rounded-button-md")).toBe("h-button-md rounded-button-md");
+		expect(cn("size-icon-md", "text-button-md")).toBe("size-icon-md text-button-md");
+		// `--input` and `--text-input-md` are different namespaces that
+		// happen to share a word. A field sets both at once, so a merger that
+		// judged them to conflict would silently strip one.
+		expect(cn("border-input", "text-input-md")).toBe("border-input text-input-md");
+	});
+});

package/src/lib/cn.ts

@@ -0,0 +1,29 @@
+import { type ClassValue, clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+import { TW_MERGE_CONFIG } from "../styles/tokens";
+
+/**
+ * tailwind-merge, taught the semantic size tokens from `tokens.css`.
+ *
+ * Registering them is load-bearing rather than tidiness. tailwind-merge only
+ * treats two classes as conflicting when it recognises both as members of the
+ * same group, and `button-md` is not a value it knows. Left unregistered,
+ * `cn("h-button-md", "h-12")` returns *both* classes: they each resolve to a
+ * height, uniwind applies whichever it saw last, and a caller's override works
+ * or does not depending on class order. Nothing throws, so the failure is
+ * silent — which is why `cn.test.ts` asserts every token here.
+ *
+ * `tv()` needs the same treatment for its own merger — see `lib/tv.ts`.
+ */
+const twMerge = extendTailwindMerge(TW_MERGE_CONFIG);
+
+/**
+ * Merges class names and resolves Tailwind conflicts so the last utility wins.
+ *
+ * Uniwind does not deduplicate conflicting classes on its own — both would be
+ * applied and the winner would be undefined. Always route a caller-supplied
+ * `className` through this before handing it to a component.
+ */
+export function cn(...inputs: ClassValue[]): string {
+	return twMerge(clsx(inputs));
+}

package/src/lib/color.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import { isLiteralColor, themeVariableName, transparentOf } from "./color";
+
+describe("isLiteralColor", () => {
+	test("treats hex as a literal", () => {
+		expect(isLiteralColor("#EC4899")).toBe(true);
+		expect(isLiteralColor("#fff")).toBe(true);
+		expect(isLiteralColor("#00000080")).toBe(true);
+	});
+
+	test("treats functional notation as a literal", () => {
+		expect(isLiteralColor("rgb(236, 72, 153)")).toBe(true);
+		expect(isLiteralColor("rgba(0, 0, 0, 0.5)")).toBe(true);
+		expect(isLiteralColor("hsl(330 81% 60%)")).toBe(true);
+		expect(isLiteralColor("oklch(0.7 0.2 20)")).toBe(true);
+		expect(isLiteralColor("color-mix(in oklch, red, blue)")).toBe(true);
+	});
+
+	test("treats a theme token name as a token", () => {
+		expect(isLiteralColor("foreground")).toBe(false);
+		expect(isLiteralColor("primary-foreground")).toBe(false);
+		expect(isLiteralColor("destructive-soft-foreground")).toBe(false);
+		expect(isLiteralColor("emerald-500")).toBe(false);
+	});
+
+	test("treats a raw CSS variable name as a token", () => {
+		expect(isLiteralColor("--color-foreground")).toBe(false);
+	});
+
+	test("does not mistake an empty string for a literal", () => {
+		expect(isLiteralColor("")).toBe(false);
+	});
+});
+
+describe("themeVariableName", () => {
+	test("prefixes a bare token name", () => {
+		expect(themeVariableName("foreground")).toBe("--foreground");
+		expect(themeVariableName("destructive-soft-foreground")).toBe("--destructive-soft-foreground");
+		expect(themeVariableName("chart-1")).toBe("--chart-1");
+	});
+
+	test("passes a raw variable name through", () => {
+		expect(themeVariableName("--foreground")).toBe("--foreground");
+	});
+
+	// `theme.css` maps the raw names onto `--color-*` through `@theme inline`,
+	// and `inline` emits no `--color-*` variable at all — so the prefixed form
+	// a caller may have written before would miss on every render.
+	test("rewrites the pre-shadcn --color- form onto the raw name", () => {
+		expect(themeVariableName("--color-foreground")).toBe("--foreground");
+		expect(themeVariableName("--color-destructive-soft")).toBe("--destructive-soft");
+	});
+});
+
+describe("transparentOf", () => {
+	test("keeps the hue and drops the alpha, so a fade never runs through black", () => {
+		expect(transparentOf("#0a0a0a")).toBe("#0a0a0a00");
+		expect(transparentOf("#FFFFFF")).toBe("#FFFFFF00");
+	});
+
+	test("expands a short hex, which cannot simply take a suffix", () => {
+		expect(transparentOf("#abc")).toBe("#aabbcc00");
+	});
+
+	test("replaces an alpha the colour already carries rather than appending a second", () => {
+		expect(transparentOf("#0a0a0aff")).toBe("#0a0a0a00");
+		expect(transparentOf("#abcd")).toBe("#aabbcc00");
+	});
+
+	test("rewrites functional notation in place", () => {
+		expect(transparentOf("rgb(10, 20, 30)")).toBe("rgba(10, 20, 30, 0)");
+		expect(transparentOf("rgba(10, 20, 30, 0.5)")).toBe("rgba(10, 20, 30, 0)");
+	});
+
+	test("gives up rather than guessing, so a caller can decline to draw", () => {
+		expect(transparentOf(undefined)).toBeUndefined();
+		expect(transparentOf("rebeccapurple")).toBeUndefined();
+		expect(transparentOf("oklch(0.5 0.1 200)")).toBeUndefined();
+	});
+});

package/src/lib/color.ts

@@ -0,0 +1,79 @@
+const FUNCTIONAL_COLOR = /^[a-z][a-z-]*\(/i;
+
+/**
+ * True when a string is a literal CSS colour rather than a theme token name.
+ *
+ * Theme tokens (`foreground`, `destructive-soft-foreground`, `emerald-500`) are
+ * resolved through a CSS variable; literals are handed to the platform as-is.
+ * The two are told apart by shape: a literal is either hex or a functional
+ * notation, and no token name can look like either.
+ */
+export function isLiteralColor(value: string): boolean {
+	return value.startsWith("#") || FUNCTIONAL_COLOR.test(value);
+}
+
+/** The `--color-` prefix this package used before it adopted shadcn's names. */
+const LEGACY_PREFIX = "--color-";
+
+/**
+ * The CSS variable a token name resolves to.
+ *
+ * The raw name, not the `--color-*` one: `theme.css` maps raw onto `--color-*`
+ * through `@theme inline`, and `inline` means Tailwind substitutes the value
+ * into each utility and emits no `--color-*` variable at all. Only the raw
+ * names exist at runtime.
+ *
+ * A `--color-*` argument is rewritten rather than rejected — it is what a
+ * caller wrote before this package took shadcn's names, and left alone it would
+ * miss silently on every render.
+ *
+ * Pure, and separate from `useThemeColor` so it is reachable from `bun test` —
+ * the hook imports `uniwind`, which Bun's transpiler cannot parse. See AGENTS.md.
+ */
+export function themeVariableName(token: string): string {
+	if (token.startsWith(LEGACY_PREFIX)) return `--${token.slice(LEGACY_PREFIX.length)}`;
+	if (token.startsWith("--")) return token;
+
+	return `--${token}`;
+}
+
+const HEX = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB = /^rgba?\(\s*([^,]+),\s*([^,]+),\s*([^,)]+)/i;
+
+/**
+ * The same colour at zero alpha, for the far end of a fade.
+ *
+ * A gradient must never fade to the keyword `transparent`: that is transparent
+ * BLACK, and interpolating toward it drags every stop between through grey — a
+ * dark bloom over a light ground, a milky one over a dark. The far stop has to
+ * be the near colour with its alpha taken off, which is what this returns.
+ *
+ * `undefined` for anything it cannot take apart, which a caller should read as
+ * "do not draw" rather than reaching for the keyword after all. A colour that
+ * arrives here in a notation this does not know is a colour whose channels are
+ * not knowable without a parser, and a fade is not worth one.
+ */
+export function transparentOf(color: string | undefined): string | undefined {
+	if (!color) return undefined;
+
+	if (HEX.test(color)) {
+		const digits = color.slice(1);
+		// A short hex cannot take a suffix: `#abc` + `00` is a four-digit hex,
+		// which is `#aabbccdd` shorthand and not the colour at all.
+		const rgb =
+			digits.length <= 4
+				? digits
+						.slice(0, 3)
+						.split("")
+						.map((digit) => digit + digit)
+						.join("")
+				: digits.slice(0, 6);
+
+		return `#${rgb}00`;
+	}
+
+	const channels = RGB.exec(color);
+	if (channels) return `rgba(${channels[1]?.trim()}, ${channels[2]?.trim()}, ${channels[3]?.trim()}, 0)`;
+
+	return undefined;
+}

package/src/lib/compose-refs.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { composeRefs } from "./compose-refs";
+
+describe("composeRefs", () => {
+	test("assigns to every object ref", () => {
+		const a: { current: string | null } = { current: null };
+		const b: { current: string | null } = { current: null };
+		composeRefs(a, b)("node");
+		expect(a.current).toBe("node");
+		expect(b.current).toBe("node");
+	});
+
+	test("calls every callback ref", () => {
+		const seen: string[] = [];
+		composeRefs<string>(
+			(n) => {
+				seen.push(`a:${n}`);
+			},
+			(n) => {
+				seen.push(`b:${n}`);
+			}
+		)("node");
+		expect(seen).toEqual(["a:node", "b:node"]);
+	});
+
+	test("mixes callback and object refs", () => {
+		const obj: { current: string | null } = { current: null };
+		const called: string[] = [];
+		composeRefs<string>(obj, (n) => {
+			if (n) called.push(n);
+		})("node");
+		expect(obj.current).toBe("node");
+		expect(called).toEqual(["node"]);
+	});
+
+	test("skips null and undefined refs", () => {
+		const obj: { current: string | null } = { current: null };
+		expect(() => composeRefs<string>(null, undefined, obj)("node")).not.toThrow();
+		expect(obj.current).toBe("node");
+	});
+
+	test("runs cleanups returned by callback refs on unmount", () => {
+		const order: string[] = [];
+		const cleanup = composeRefs<string>(
+			() => () => {
+				order.push("cleanup-a");
+			},
+			() => () => {
+				order.push("cleanup-b");
+			}
+		)("node");
+		expect(typeof cleanup).toBe("function");
+		cleanup?.();
+		expect(order).toEqual(["cleanup-a", "cleanup-b"]);
+	});
+
+	test("clears object refs on unmount when a cleanup runs", () => {
+		const obj: { current: string | null } = { current: null };
+		const cleanup = composeRefs<string>(obj, () => () => {})("node");
+		expect(obj.current).toBe("node");
+		cleanup?.();
+		expect(obj.current).toBeNull();
+	});
+});