@hoardodile/ui 0.0.0

package/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @hoardodile/ui — the design-system component library for hoardodile
+ * (the host app and plugin iframes alike). Components are importable
+ * per-path (`@hoardodile/ui/components/button`,
+ * `@hoardodile/ui/components/app-dialog`, `@hoardodile/ui/icons/registry`,
+ * ...) so bundles stay small; hooks live under
+ * `@hoardodile/ui/hooks/*` and shared CSS variables in
+ * `@hoardodile/ui/theme.css`. The root entry re-exports only app-owned
+ * pieces that don't fit the subpath layout.
+ *
+ * Theme classes: `@hoardodile/ui/theme.css` defines the `.light` /
+ * `.dark` variables and per-palette `.theme-<id>` blocks the host app
+ * and plugin iframes both consume.
+ */
+
+export type { AppDialogProps } from "./components/app-dialog.tsx"
+export { AppDialog } from "./components/app-dialog.tsx"
+export {
+	setNavigationResolver,
+	useMobileBackToClose,
+} from "./hooks/useMobileBackToClose.ts"
+export { cn } from "./lib/utils.ts"

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

@@ -0,0 +1,109 @@
+// @vitest-environment node
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { mergeTheme } from "./merge-config"
+import { cn } from "./utils"
+
+// merge-config.ts registers the app's custom @theme tokens (theme.css) with
+// tailwind-merge, so custom utilities get correct conflict semantics — e.g.
+// `text-ui` must behave as a font size, not as a text color. Two pins:
+// 1. Token contract: every @theme token in a covered namespace is
+//    registered. Add a token, go red until registered — no silent drift.
+// 2. Behavior: the merges that previously misbehaved, pinned.
+// Vitest runs with the package root as cwd (see scan-contract.test.ts).
+const THEME_CSS = join(process.cwd(), "src", "styles", "theme.css")
+
+// Namespaces whose tokens the merge config owns; keys mirror the v4
+// `--<namespace>-*` prefixes one-to-one.
+const NAMESPACES = [
+	"text",
+	"spacing",
+	"tracking",
+	"shadow",
+	"container",
+	"font",
+	"ease",
+	"animate",
+] as const
+
+// Names already covered by tailwind-merge's default config under the same
+// token name — registered there, not here.
+const BUILTIN: Partial<Record<(typeof NAMESPACES)[number], readonly string[]>> =
+	{
+		font: ["sans"],
+		ease: ["in", "out"],
+	}
+
+function themeTokens(namespace: string): string[] {
+	const css = readFileSync(THEME_CSS, "utf8")
+	const open = css.indexOf("{", css.indexOf("@theme"))
+	let depth = 0
+	let end = css.length
+	for (let i = open; i < css.length; i++) {
+		if (css[i] === "{") depth++
+		else if (css[i] === "}") {
+			depth--
+			if (depth === 0) {
+				end = i
+				break
+			}
+		}
+	}
+	const tokens = new Set<string>()
+	for (const match of css.slice(open, end).matchAll(/--([\w-]+)\s*:/g)) {
+		// `--text-ui--line-height` is the line-height companion of `text-ui`,
+		// not a separate utility — resolve it to its base token.
+		const name = match[1]!.replace(/--line-height$/, "")
+		if (name.startsWith(`${namespace}-`)) {
+			tokens.add(name.slice(namespace.length + 1))
+		}
+	}
+	return [...tokens]
+}
+
+describe("tailwind-merge theme config", () => {
+	it("registers every custom @theme token", () => {
+		for (const namespace of NAMESPACES) {
+			const covered = mergeTheme[namespace] as readonly string[]
+			const builtin = BUILTIN[namespace] ?? []
+			const unregistered = themeTokens(namespace).filter(
+				(token) => !covered.includes(token) && !builtin.includes(token),
+			)
+			expect(
+				unregistered,
+				`--${namespace}-* tokens missing from mergeTheme.${namespace}`,
+			).toEqual([])
+		}
+	})
+
+	it("merges custom font sizes as sizes, not colors", () => {
+		expect(cn("text-ui text-foreground")).toBe("text-ui text-foreground")
+		expect(cn("text-tiny text-muted-foreground")).toBe(
+			"text-tiny text-muted-foreground",
+		)
+		expect(cn("text-doc-title text-primary")).toBe(
+			"text-doc-title text-primary",
+		)
+	})
+
+	it("keeps custom font sizes mutually exclusive with the builtin scale", () => {
+		expect(cn("text-ui text-sm")).toBe("text-sm")
+		expect(cn("text-sm text-ui")).toBe("text-ui")
+	})
+
+	it("merges the other custom token families with correct conflicts", () => {
+		expect(cn("h-control h-10")).toBe("h-10")
+		expect(cn("max-w-content max-w-md")).toBe("max-w-md")
+		expect(cn("tracking-label tracking-wide")).toBe("tracking-wide")
+		expect(cn("shadow-card shadow-sm")).toBe("shadow-sm")
+		expect(cn("font-doc font-sans")).toBe("font-sans")
+		expect(cn("ease-standard ease-out")).toBe("ease-out")
+		expect(cn("animate-skel animate-pop")).toBe("animate-pop")
+	})
+
+	it("keeps custom tokens from different groups side by side", () => {
+		expect(cn("text-ui leading-[1.75]")).toBe("text-ui leading-[1.75]")
+		expect(cn("h-nav min-h-nav")).toBe("h-nav min-h-nav")
+		expect(cn("font-doc text-doc-title")).toBe("font-doc text-doc-title")
+	})
+})

package/src/lib/merge-config.ts

@@ -0,0 +1,22 @@
+import { extendTailwindMerge } from "tailwind-merge"
+
+// The app's `@theme inline` tokens (theme.css) generate utility names
+// tailwind-merge doesn't know, so it misclassifies them — e.g. `text-ui` is
+// parsed as a text color and dropped next to any `text-*` color. The default
+// class groups are theme-backed, so extending the theme (keys mirror the v4
+// token namespaces one-to-one) registers every custom utility with correct
+// conflict semantics. merge-config.test.ts pins this list against theme.css.
+export const mergeTheme = {
+	text: ["tiny", "ui", "doc", "doc-title", "doc-heading", "quote"],
+	spacing: ["chip", "control", "nav", "sidebar", "panel"],
+	tracking: ["label"],
+	shadow: ["card", "dialog"],
+	container: ["reading", "medium", "content"],
+	font: ["doc", "heading"],
+	ease: ["standard"],
+	animate: ["skel", "pop"],
+} as const
+
+export const twMerge = extendTailwindMerge({
+	extend: { theme: mergeTheme },
+})

package/src/lib/pagination.test.ts

@@ -0,0 +1,55 @@
+/**
+ * @vitest-environment node
+ */
+
+import { describe, expect, it } from "vitest"
+import { pageCountOf, paginationWindow } from "./pagination"
+
+describe("pageCountOf", () => {
+	it("returns 1 when there are no rows so the UI never shows '1 / 0'", () => {
+		expect(pageCountOf(0, 20)).toBe(1)
+	})
+
+	it("returns 1 when total fits exactly in one page", () => {
+		expect(pageCountOf(20, 20)).toBe(1)
+	})
+
+	it("rounds up to cover the partial trailing page", () => {
+		expect(pageCountOf(21, 20)).toBe(2)
+		expect(pageCountOf(99, 10)).toBe(10)
+	})
+
+	it("returns 1 for negative or NaN input rather than 0 or NaN", () => {
+		expect(pageCountOf(-5, 20)).toBe(1)
+	})
+})
+
+describe("paginationWindow", () => {
+	it("shows first, last, the asymmetric window and ellipses for a middle page", () => {
+		expect(paginationWindow(6, 68)).toEqual([1, "…", 5, 6, 7, 8, "…", 68])
+	})
+
+	it("renders every page when the range fits without gaps", () => {
+		expect(paginationWindow(3, 5)).toEqual([1, 2, 3, 4, 5])
+		expect(paginationWindow(3, 6)).toEqual([1, 2, 3, 4, 5, 6])
+		expect(paginationWindow(4, 7)).toEqual([1, "…", 3, 4, 5, 6, 7])
+		expect(paginationWindow(4, 8)).toEqual([1, "…", 3, 4, 5, 6, "…", 8])
+	})
+
+	it("drops the leading ellipse when the window touches the first page", () => {
+		expect(paginationWindow(1, 68)).toEqual([1, 2, 3, "…", 68])
+		expect(paginationWindow(3, 68)).toEqual([1, 2, 3, 4, 5, "…", 68])
+	})
+
+	it("drops the trailing ellipse when the window touches the last page", () => {
+		expect(paginationWindow(68, 68)).toEqual([1, "…", 67, 68])
+		expect(paginationWindow(67, 68)).toEqual([1, "…", 66, 67, 68])
+		expect(paginationWindow(66, 68)).toEqual([1, "…", 65, 66, 67, 68])
+	})
+
+	it("stays within bounds for tiny ranges", () => {
+		expect(paginationWindow(1, 1)).toEqual([1])
+		expect(paginationWindow(1, 2)).toEqual([1, 2])
+		expect(paginationWindow(2, 3)).toEqual([1, 2, 3])
+	})
+})

package/src/lib/pagination.ts

@@ -0,0 +1,42 @@
+/**
+ * Compute the number of pages for a paginated list given a total row count
+ * and the page size. Always at least 1 so the UI never renders "1 / 0".
+ */
+export function pageCountOf(total: number, pageSize: number): number {
+	return Math.max(1, Math.ceil(total / pageSize))
+}
+
+/**
+ * The page numbers a windowed pager renders: the first and last pages are
+ * always shown, with an asymmetric window around the active one (more
+ * pages trailing than leading) and an ellipsis wherever the gap between
+ * two segments is wider than a single page (adjacent numbers render
+ * directly, no ellipsis).
+ *
+ * @example
+ *   paginationWindow(6, 68) // [1, "…", 5, 6, 7, 8, "…", 68]
+ *   paginationWindow(1, 5)  // [1, 2, 3, 4, 5]
+ */
+export function paginationWindow(
+	page: number,
+	pageCount: number,
+	before = 1,
+	after = 2,
+): readonly (number | "…")[] {
+	const windowStart = Math.max(2, page - before)
+	const windowEnd = Math.min(pageCount - 1, page + after)
+	const items: (number | "…")[] = [1]
+	if (windowStart > 2) {
+		items.push("…")
+	}
+	for (let p = windowStart; p <= windowEnd; p++) {
+		items.push(p)
+	}
+	if (windowEnd < pageCount - 1) {
+		items.push("…")
+	}
+	if (pageCount > 1) {
+		items.push(pageCount)
+	}
+	return items
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "./merge-config"
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}

package/src/styles/scan-contract.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+import { compile } from "@tailwindcss/node"
+import { Scanner } from "@tailwindcss/oxide"
+
+// Consumers import `@hoardodile/ui/theme.css`, which resolves to the dist
+// copy. Its `@source` glob is relative to that file, so it only sees what
+// tsup ships — this test compiles the built stylesheet exactly like a
+// consumer's Tailwind would, pinning the published artifact against the
+// components it must style. It goes red if the glob stops matching the
+// tsup outputs (wrong extension, moved dist layout, minified output, ...).
+// Vitest runs with the package root as cwd; `import.meta.url` is not a
+// file URL under its module runner, so resolve from cwd instead.
+const DIST_STYLES = join(process.cwd(), "dist", "styles")
+
+const REPRESENTATIVE_CANDIDATES = [
+	// dialog surface + exit animation
+	"bg-popover",
+	"text-popover-foreground",
+	"sm:data-starting-style:scale-95",
+	// button variants, icon slots, dark input
+	"hover:bg-primary/80",
+	"has-data-[icon=inline-end]:pr-2",
+	"dark:bg-input/30",
+	// button-group slot override
+	"in-data-[slot=button-group]:rounded-md",
+	// popover anchor animation
+	"data-[side=bottom]:slide-in-from-top-2",
+] as const
+
+describe("theme.css scan contract", () => {
+	it("scans the tsup outputs and generates the component utilities", async () => {
+		const themeCss = readFileSync(join(DIST_STYLES, "theme.css"), "utf8")
+		// `tw-animate-css` / `shadcn/tailwind.css` are package-name imports
+		// resolved by the consumer's Tailwind toolchain; compile() resolves
+		// only relative imports, so strip them. They don't affect the scan
+		// contract under test.
+		const entry = themeCss.replace(
+			/@import "tw-animate-css";\n@import "shadcn\/tailwind.css";\n/g,
+			"",
+		)
+
+		const compiled = await compile(entry, {
+			base: DIST_STYLES,
+			onDependency: () => {},
+		})
+		expect(compiled.sources.length).toBeGreaterThan(0)
+
+		const candidates = new Set(
+			new Scanner({ sources: compiled.sources }).scan(),
+		)
+		for (const candidate of REPRESENTATIVE_CANDIDATES) {
+			expect([...candidates]).toContain(candidate)
+		}
+
+		const css = compiled.build([...candidates])
+		// theme.css itself went through (palettes survive the entry surgery)
+		expect(css).toContain(".theme-parchment")
+		// build() pretty-prints (`{` on its own line), so assert on the
+		// selector text and one rule body rather than brace positions
+		for (const fragment of [
+			".bg-popover",
+			"background-color: var(--popover);",
+			".text-popover-foreground",
+			"data-starting-style\\:scale-95",
+			"has-data-\\[icon",
+			"in-data-\\[slot\\=button-group\\]",
+			"hover\\:bg-primary\\/80",
+			".dark\\:bg-input\\/30",
+		]) {
+			expect(css).toContain(fragment)
+		}
+	})
+})