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

package/src/styles/tokens.css

@@ -0,0 +1,132 @@
+@theme {
+	/*
+	 * The one number every generic corner is derived from, in the `@theme
+	 * inline` block at the bottom of this file. shadcn's own scale, so a
+	 * `--radius` copied out of a web app retunes every rounded edge here at
+	 * once — and unlike the older `calc(var(--radius) - 4px)` form some theme
+	 * generators still emit, a multiplier scales rather than shifts, so a
+	 * square-cornered theme stays square at every step.
+	 *
+	 * It lives in `tokens.css` rather than beside the palette because
+	 * `apps/web` imports only this file; a `--radius` in `theme.css` would
+	 * leave every derived radius undefined on the docs site.
+	 */
+	--radius: 0.625rem;
+
+	--text-xs: 12px;
+	--text-sm: 14px;
+	--text-base: 16px;
+	--text-lg: 18px;
+	--text-xl: 20px;
+	--text-2xl: 24px;
+	--text-3xl: 30px;
+
+	/*
+	 * The button's three scales, stepped together: the height — which is also
+	 * the square footprint at an `icon-*` size — the label's type, and the
+	 * corner.
+	 *
+	 * The corner is half the height at every step, so a button is a capsule and
+	 * a square one a circle. A token rather than `rounded-full` because the
+	 * shape is a default, not a law: a kit that wants squarer buttons changes
+	 * three numbers here and touches no component. `tokens.test.ts` keeps each
+	 * under half its height — past that the renderer clamps and the number
+	 * stops meaning what it says.
+	 */
+	--spacing-button-sm: 36px;
+	--spacing-button-md: 44px;
+	--spacing-button-lg: 52px;
+
+	--text-button-sm: 14px;
+	--text-button-md: 16px;
+	--text-button-lg: 18px;
+
+	--radius-button-sm: 18px;
+	--radius-button-md: 22px;
+	--radius-button-lg: 26px;
+
+	/*
+	 * Field heights, and the type scale paired step-for-step with them.
+	 *
+	 * A scale of its own rather than `--spacing-button-*`, even though the
+	 * numbers agree today: a control that borrowed the button's would retune
+	 * silently whenever the button's did.
+	 */
+	--spacing-input-sm: 36px;
+	--spacing-input-md: 44px;
+	--spacing-input-lg: 52px;
+
+	--text-input-sm: 14px;
+	--text-input-md: 16px;
+	--text-input-lg: 18px;
+
+	/*
+	 * The icon scale, shared by `Icon` and `Spinner` so a named size means the
+	 * same edge length in both and one can replace the other without the
+	 * layout moving. `size-icon-md`.
+	 *
+	 * A component's own size axis indexes into this scale rather than restating
+	 * a number: a button's sm/md/lg icon is icon-sm/md/lg.
+	 *
+	 * It sizes more than glyphs. A `Checkbox`'s square reads it too, two steps
+	 * above the tick it holds, rather than minting a scale that would have to be
+	 * retuned in step with this one forever.
+	 */
+	--spacing-icon-xs: 14px;
+	--spacing-icon-sm: 16px;
+	--spacing-icon-md: 18px;
+	--spacing-icon-lg: 20px;
+	--spacing-icon-xl: 24px;
+	--spacing-icon-2xl: 32px;
+
+	/*
+	 * Screen chrome. `h-navbar-row` is the navbar's control row on its own —
+	 * the safe-area band above it is padding, not part of this number, so one
+	 * value holds across every device.
+	 *
+	 * `px-screen-gutter` is the horizontal gutter `Screen.Header`,
+	 * `Screen.Navbar` and a screen's own content all line up against. It is one
+	 * token rather than three `px-5`s so a change moves every edge together.
+	 *
+	 * The footer's padding is deliberately NOT here — see `screen.variants.ts`.
+	 */
+	--spacing-navbar-row: 56px;
+	--spacing-screen-gutter: 20px;
+
+	/*
+	 * A chart's height. It has no intrinsic one — a canvas fills whatever box
+	 * it is given — so without a token every chart on a dashboard would be a
+	 * different height and the rows would not line up.
+	 *
+	 * A height rather than an aspect ratio on purpose: two charts side by side
+	 * at different widths must still agree, and `aspect-video` would give them
+	 * different heights. Registering the names with tailwind-merge is what lets
+	 * a caller's `aspect-video h-auto` cleanly win when they want that instead.
+	 */
+	--spacing-chart-sm: 160px;
+	--spacing-chart-md: 220px;
+	--spacing-chart-lg: 280px;
+}
+
+/*
+ * The generic corner scale, derived from `--radius`.
+ *
+ * `inline` for the same reason the palette uses it: a utility has to read
+ * `var(--radius)` itself, so a theme that redeclares `--radius` reaches
+ * `rounded-lg` rather than a copy taken when the scale was compiled.
+ *
+ * `--radius-button-*` above is deliberately NOT part of this. A button's corner
+ * is half its own height — a shape, not a step on a scale — and it must not
+ * move when a consumer retunes `--radius`.
+ */
+@theme inline {
+	--radius-xs: calc(var(--radius) * 0.4);
+	--radius-sm: calc(var(--radius) * 0.6);
+	--radius-md: calc(var(--radius) * 0.8);
+	--radius-lg: var(--radius);
+	--radius-xl: calc(var(--radius) * 1.4);
+	--radius-2xl: calc(var(--radius) * 1.8);
+	--radius-3xl: calc(var(--radius) * 2.2);
+	--radius-4xl: calc(var(--radius) * 2.6);
+	--radius-full: 9999px;
+}

package/src/styles/tokens.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+	BUTTON_RADIUS_TOKENS,
+	BUTTON_SIZE_TOKENS,
+	BUTTON_TEXT_TOKENS,
+	CHART_SIZE_TOKENS,
+	ICON_SIZE_TOKENS,
+	INPUT_SIZE_TOKENS,
+	INPUT_TEXT_TOKENS,
+	SCREEN_SIZE_TOKENS,
+} from "./tokens";
+
+const CSS = readFileSync(join(import.meta.dirname, "tokens.css"), "utf-8");
+
+/** Every `--name: 12px` declaration in `tokens.css`, as a name → points map. */
+function declarations(): Map<string, number> {
+	const found = new Map<string, number>();
+	for (const [, name, value] of CSS.matchAll(/--([\w-]+):\s*([\d.]+)px;/g)) {
+		found.set(name, Number(value));
+	}
+	return found;
+}
+
+const TOKENS = declarations();
+
+/** Points behind a token, failing loudly rather than yielding NaN. */
+function px(name: string): number {
+	const value = TOKENS.get(name);
+	if (value === undefined) throw new Error(`tokens.css defines no --${name}`);
+	return value;
+}
+
+describe("tokens.ts and tokens.css", () => {
+	// The registry drives `cn`'s tailwind-merge extension. A token in the CSS
+	// that is missing here is an override that silently stops working; a name
+	// here with no CSS behind it is a class that compiles to nothing.
+	test("declare exactly the same spacing tokens", () => {
+		const declared = [...TOKENS.keys()]
+			.filter((name) => name.startsWith("spacing-"))
+			.map((name) => name.replace("spacing-", ""))
+			.sort();
+		const registered = [
+			...BUTTON_SIZE_TOKENS,
+			...CHART_SIZE_TOKENS,
+			...ICON_SIZE_TOKENS,
+			...INPUT_SIZE_TOKENS,
+			...SCREEN_SIZE_TOKENS,
+		].sort();
+		expect(declared).toEqual(registered);
+	});
+
+	test("declare exactly the same button text tokens", () => {
+		const declared = [...TOKENS.keys()]
+			.filter((name) => name.startsWith("text-button-"))
+			.map((name) => name.replace("text-", ""))
+			.sort();
+		expect(declared).toEqual([...BUTTON_TEXT_TOKENS].sort());
+	});
+
+	test("declare exactly the same button radius tokens", () => {
+		const declared = [...TOKENS.keys()]
+			.filter((name) => name.startsWith("radius-button-"))
+			.map((name) => name.replace("radius-", ""))
+			.sort();
+		expect(declared).toEqual([...BUTTON_RADIUS_TOKENS].sort());
+	});
+
+	test("declare exactly the same input text tokens", () => {
+		const declared = [...TOKENS.keys()]
+			.filter((name) => name.startsWith("text-input-"))
+			.map((name) => name.replace("text-", ""))
+			.sort();
+		expect(declared).toEqual([...INPUT_TEXT_TOKENS].sort());
+	});
+});
+
+describe("the chart scale", () => {
+	test("ascends in the order the registry lists it", () => {
+		const values = CHART_SIZE_TOKENS.map((token) => px(`spacing-${token}`));
+		expect(values).toEqual([...values].sort((a, b) => a - b));
+		expect(new Set(values).size).toBe(CHART_SIZE_TOKENS.length);
+	});
+
+	test("stays taller than a control, since a chart is a region and not a row", () => {
+		// A chart shorter than an input would have no room for an axis under its
+		// own plot, and the labels would collide with the marks.
+		expect(px("spacing-chart-sm")).toBeGreaterThan(px("spacing-input-lg"));
+	});
+});
+
+describe("the icon scale", () => {
+	// Component tests compare tokens by their index in ICON_SIZE_TOKENS rather
+	// than by looking up points, which only means anything while the array is
+	// ordered. This is the test that keeps that true.
+	test("ascends in the order the registry lists it", () => {
+		const values = ICON_SIZE_TOKENS.map((token) => px(`spacing-${token}`));
+		expect(values).toEqual([...values].sort((a, b) => a - b));
+		expect(new Set(values).size).toBe(ICON_SIZE_TOKENS.length);
+	});
+});
+
+describe("the button scale", () => {
+	test("ascends in the order the registry lists it", () => {
+		const values = BUTTON_SIZE_TOKENS.map((token) => px(`spacing-${token}`));
+		expect(values).toEqual([...values].sort((a, b) => a - b));
+		expect(new Set(values).size).toBe(BUTTON_SIZE_TOKENS.length);
+	});
+
+	test("pairs each height with a label size and an icon that fit inside it", () => {
+		for (const [index, token] of BUTTON_SIZE_TOKENS.entries()) {
+			const height = px(`spacing-${token}`);
+			expect(px(`text-${BUTTON_TEXT_TOKENS[index]}`)).toBeLessThan(height);
+			// A button's icon indexes the shared scale at the same step name.
+			expect(px(`spacing-icon-${token.replace("button-", "")}`)).toBeLessThan(height);
+		}
+	});
+
+	test("scales the label with the height", () => {
+		const text = BUTTON_TEXT_TOKENS.map((token) => px(`text-${token}`));
+		expect(text).toEqual([...text].sort((a, b) => a - b));
+	});
+
+	// A radius past half the height is silently clamped to half by the
+	// renderer, so a number above it would stop meaning what it says — and the
+	// step it sits at would stop being retunable. Equal to half, which is what
+	// every step is today, draws the capsule the button ships as.
+	test("gives each height a corner it can actually draw", () => {
+		for (const [index, token] of BUTTON_SIZE_TOKENS.entries()) {
+			const height = px(`spacing-${token}`);
+			expect(px(`radius-${BUTTON_RADIUS_TOKENS[index]}`)).toBeLessThanOrEqual(height / 2);
+		}
+	});
+
+	test("scales the corner with the height", () => {
+		const radii = BUTTON_RADIUS_TOKENS.map((token) => px(`radius-${token}`));
+		expect(radii).toEqual([...radii].sort((a, b) => a - b));
+		expect(new Set(radii).size).toBe(BUTTON_RADIUS_TOKENS.length);
+	});
+
+	// The three scales are indexed by the same step name — `button-md` names a
+	// height, a label size and a corner — so a step added to one and not the
+	// others would compile to a class with nothing behind it.
+	test("names its steps the same way across all three scales", () => {
+		expect([...BUTTON_RADIUS_TOKENS]).toEqual([...BUTTON_SIZE_TOKENS]);
+		expect([...BUTTON_TEXT_TOKENS]).toEqual([...BUTTON_SIZE_TOKENS]);
+	});
+});
+
+describe("the input scale", () => {
+	test("ascends in the order the registry lists it", () => {
+		const values = INPUT_SIZE_TOKENS.map((token) => px(`spacing-${token}`));
+		expect(values).toEqual([...values].sort((a, b) => a - b));
+		expect(new Set(values).size).toBe(INPUT_SIZE_TOKENS.length);
+	});
+
+	test("pairs each height with a text size and an icon that fit inside it", () => {
+		for (const [index, token] of INPUT_SIZE_TOKENS.entries()) {
+			const height = px(`spacing-${token}`);
+			expect(px(`text-${INPUT_TEXT_TOKENS[index]}`)).toBeLessThan(height);
+			// A decorator's icon indexes the shared scale at the same step name.
+			expect(px(`spacing-icon-${token.replace("input-", "")}`)).toBeLessThan(height);
+		}
+	});
+
+	test("scales the text with the height", () => {
+		const text = INPUT_TEXT_TOKENS.map((token) => px(`text-${token}`));
+		expect(text).toEqual([...text].sort((a, b) => a - b));
+	});
+
+	// `Input` and `Button` are the two controls a form puts side by side, so a
+	// field that stood a step taller than the button beside it would read as a
+	// mistake. They are separate scales precisely so this is asserted rather
+	// than assumed — see the note in tokens.css.
+	test("stands exactly as tall as the button beside it", () => {
+		for (const [index, token] of INPUT_SIZE_TOKENS.entries()) {
+			expect(px(`spacing-${token}`)).toBe(px(`spacing-${BUTTON_SIZE_TOKENS[index]}`));
+		}
+	});
+});

package/src/styles/tokens.ts

@@ -0,0 +1,86 @@
+/**
+ * Names of the semantic size tokens defined in `tokens.css`.
+ *
+ * These exist so `cn()` can teach tailwind-merge about them. Without that,
+ * `h-button-md` is an unrecognised utility and twMerge will not drop it when a
+ * caller passes `h-12` — both survive and the override silently stops working.
+ * {@link ../lib/cn} registers every name here, and a test asserts this list
+ * still matches `tokens.css`.
+ *
+ * Values live in the CSS, not here. A component references a token by writing
+ * the class out in full (`size-icon-md`) — Tailwind scans source text, so a
+ * name assembled at runtime would never be compiled.
+ */
+
+/** Suffixes in the `--spacing-*` namespace: `h-button-md`, `w-button-md`. */
+export const BUTTON_SIZE_TOKENS = ["button-sm", "button-md", "button-lg"] as const;
+
+/** Suffixes in the `--spacing-*` namespace: `size-icon-md`. */
+export const ICON_SIZE_TOKENS = ["icon-xs", "icon-sm", "icon-md", "icon-lg", "icon-xl", "icon-2xl"] as const;
+
+/**
+ * Suffixes in the `--spacing-*` namespace: `h-navbar-row`, `px-screen-gutter`.
+ *
+ * Not a scale — two independent measurements of a screen's chrome — so unlike
+ * the icon and button tokens their order carries no meaning.
+ */
+export const SCREEN_SIZE_TOKENS = ["navbar-row", "screen-gutter"] as const;
+
+/**
+ * Suffixes in the `--spacing-*` namespace: `h-input-md`, `min-h-input-md`.
+ *
+ * Read on two axes, unlike the button's: a single-line field takes the height
+ * as a fixed one and a multiline field takes it as a floor, so both `h-` and
+ * `min-h-` have to be recognised.
+ */
+export const INPUT_SIZE_TOKENS = ["input-sm", "input-md", "input-lg"] as const;
+
+/**
+ * Suffixes in the `--radius-*` namespace: `rounded-button-md`.
+ *
+ * Stepped with the button's heights rather than borrowing the generic
+ * `--radius-*` scale, so the corner is retuned with the control it belongs to
+ * and a caller's `rounded-lg` still overrides it.
+ */
+export const BUTTON_RADIUS_TOKENS = ["button-sm", "button-md", "button-lg"] as const;
+
+/** Suffixes in the `--text-*` namespace: `text-button-md`. */
+export const BUTTON_TEXT_TOKENS = ["button-sm", "button-md", "button-lg"] as const;
+
+/** Suffixes in the `--text-*` namespace: `text-input-md`. */
+export const INPUT_TEXT_TOKENS = ["input-sm", "input-md", "input-lg"] as const;
+
+/**
+ * Suffixes in the `--spacing-*` namespace: `h-chart-md`.
+ *
+ * A chart canvas has no intrinsic height, so one is named here rather than
+ * written as a `h-56` at each call site — a dashboard's rows only line up if
+ * every chart agrees, and they only stay agreed if there is one number.
+ */
+export const CHART_SIZE_TOKENS = ["chart-sm", "chart-md", "chart-lg"] as const;
+
+/**
+ * The tailwind-merge extension both mergers in this package are built from.
+ *
+ * There are two, and they are easy to forget: `cn()` merges a caller's
+ * className, and `tv()` merges slots and variants using a tailwind-merge
+ * instance of its own. Extending only one leaves the other treating
+ * `text-button-md` as an unrecognised utility — which is how a size token ends
+ * up colliding with a colour and silently dropping it. One config, read by
+ * `lib/cn.ts` and `lib/tv.ts`, so they cannot drift apart.
+ */
+export const TW_MERGE_CONFIG = {
+	extend: {
+		theme: {
+			radius: [...BUTTON_RADIUS_TOKENS],
+			spacing: [
+				...BUTTON_SIZE_TOKENS,
+				...CHART_SIZE_TOKENS,
+				...ICON_SIZE_TOKENS,
+				...INPUT_SIZE_TOKENS,
+				...SCREEN_SIZE_TOKENS,
+			],
+			text: [...BUTTON_TEXT_TOKENS, ...INPUT_TEXT_TOKENS],
+		},
+	},
+} as const;

package/src/uniwind-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="uniwind/types" />