@robomous/ui-core 0.1.0 → 0.2.0

package/src/theme/imports.test.ts

@@ -0,0 +1,160 @@
+// @vitest-environment node
+/**
+ * Everything `styles.css` imports really resolves — packages and siblings both.
+ *
+ * The stylesheet ships as **source**: `exports["./styles.css"]` hands a consumer
+ * the file itself, and the consumer's Tailwind build is what resolves the
+ * `@import`s in it. So a package named there is a genuine runtime dependency of
+ * this one, and a sibling named there is a file that has to be published. Get
+ * either wrong and every consumer breaks while `pnpm lint`, `pnpm build` and
+ * `pnpm test` all stay green — nothing in this repository compiles CSS, so
+ * nothing here would otherwise notice. A rule nothing checks is a preference;
+ * this is the check.
+ *
+ * Both halves matter, and they fail differently. A missing **package** is a
+ * dependency that was dropped from `package.json` because a grep for
+ * `from "..."` never sees a CSS `@import`. A missing **sibling** is a file that
+ * exists on the author's disk but was never committed, or was left out of
+ * `files` — so it resolves here and nowhere else.
+ *
+ * Package resolution goes through the package's own `exports` map with the
+ * `style` condition first, because that is the condition a CSS bundler asks for
+ * and some packages expose their stylesheet under no other — Node's own
+ * `import.meta.resolve` asks for `import`/`require` and would report a
+ * correctly installed package as missing.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { expect, test } from "vitest";
+
+const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+const MODULES = path.join(REPO, "node_modules");
+const STYLESHEET_DIR = path.join(REPO, "src/theme");
+const STYLESHEET = readFileSync(path.join(STYLESHEET_DIR, "styles.css"), "utf8");
+
+/** The conditions a CSS bundler offers, most specific first. */
+const CONDITIONS = ["style", "default", "import", "require"];
+
+/** Every `@import` specifier in the stylesheet, in source order. */
+function importsIn(css: string): string[] {
+  return [...css.matchAll(/^\s*@import\s+["']([^"']+)["']/gm)].map((match) => match[1]);
+}
+
+/** A URL needs no filesystem, so it is not this gate's business. */
+const isRemote = (spec: string) => /^https?:/.test(spec);
+
+/** `"./tailwind.css"`, `"../a/b.css"` — resolved against the stylesheet itself. */
+const isRelative = (spec: string) => /^\.{1,2}\//.test(spec);
+
+/** `"@scope/pkg/a/b"` → `["@scope/pkg", "./a/b"]`; `"pkg"` → `["pkg", "."]`. */
+function splitSpecifier(spec: string): [name: string, subpath: string] {
+  const segments = spec.split("/");
+  const name = spec.startsWith("@") ? segments.slice(0, 2).join("/") : segments[0];
+  const rest = spec.slice(name.length);
+  return [name, rest === "" ? "." : `.${rest}`];
+}
+
+/** The first branch of a conditional export any of `CONDITIONS` selects. */
+function pickCondition(node: unknown): string | null {
+  if (typeof node === "string") return node;
+  if (node === null || typeof node !== "object") return null;
+  const branches = node as Record<string, unknown>;
+  for (const condition of CONDITIONS) {
+    if (condition in branches) {
+      const picked = pickCondition(branches[condition]);
+      if (picked !== null) return picked;
+    }
+  }
+  return null;
+}
+
+/** Where a package's `exports` (or its legacy fields) send one subpath. */
+function targetOf(manifest: Record<string, unknown>, subpath: string): string | null {
+  const map = manifest.exports;
+  if (map === undefined) {
+    // No exports map: "." is the package's own stylesheet field, and any other
+    // subpath is a plain path inside the package.
+    if (subpath !== ".") return subpath;
+    return (manifest.style as string) ?? (manifest.main as string) ?? null;
+  }
+  if (typeof map === "string") return subpath === "." ? map : null;
+  const entries = map as Record<string, unknown>;
+  if (subpath in entries) return pickCondition(entries[subpath]);
+  // An exports map that is conditions all the way down is shorthand for ".".
+  if (subpath === "." && !Object.keys(entries).some((key) => key.startsWith("."))) {
+    return pickCondition(entries);
+  }
+  return null;
+}
+
+/** The file a specifier lands on, or why it lands nowhere. */
+function resolveStyleImport(spec: string): { file: string } | { reason: string } {
+  const [name, subpath] = splitSpecifier(spec);
+  const root = path.join(MODULES, ...name.split("/"));
+  const manifestPath = path.join(root, "package.json");
+  if (!existsSync(manifestPath)) {
+    return { reason: `${name} is not installed — it is missing from package.json dependencies` };
+  }
+  const target = targetOf(JSON.parse(readFileSync(manifestPath, "utf8")), subpath);
+  if (target === null) {
+    return { reason: `${name} declares no export for ${subpath}` };
+  }
+  const file = path.join(root, target);
+  if (!existsSync(file)) {
+    return { reason: `${name} exports ${subpath} as ${target}, which does not exist` };
+  }
+  return { file };
+}
+
+test("every package the stylesheet imports is installed and exports the file it names", () => {
+  const specs = importsIn(STYLESHEET).filter((spec) => !isRemote(spec) && !isRelative(spec));
+  expect(specs.length > 0, "the stylesheet named no packages, so this proves nothing").toBe(true);
+
+  const broken = specs
+    .map((spec) => ({ spec, result: resolveStyleImport(spec) }))
+    .filter((entry) => "reason" in entry.result)
+    .map((entry) => `@import "${entry.spec}": ${(entry.result as { reason: string }).reason}`);
+
+  expect(
+    broken,
+    "styles.css ships as source and the consumer's Tailwind build resolves these, so an " +
+      "unresolvable @import breaks every consumer and nothing in this repository compiles " +
+      `CSS to catch it:\n${broken.join("\n")}`,
+  ).toEqual([]);
+});
+
+test("every sibling the stylesheet imports exists and is committed", () => {
+  const specs = importsIn(STYLESHEET).filter(isRelative);
+  expect(specs.length > 0, "the stylesheet named no siblings, so this proves nothing").toBe(true);
+
+  const broken = specs.flatMap((spec) => {
+    const file = path.resolve(STYLESHEET_DIR, spec);
+    if (!existsSync(file)) {
+      return [`@import "${spec}": ${path.relative(REPO, file)} does not exist`];
+    }
+    // On disk is not enough. `files: ["src"]` publishes what the working tree
+    // holds, so an uncommitted sibling packs fine here and is absent from the
+    // clone CI builds and publishes from — the failure lands on consumers only.
+    const tracked = spawnSync("git", ["ls-files", "--error-unmatch", file], {
+      cwd: REPO,
+      encoding: "utf8",
+    });
+    if (tracked.status !== 0) {
+      return [
+        `@import "${spec}": ${path.relative(REPO, file)} exists but is not tracked by git — ` +
+          "commit it, or the published package will not carry it",
+      ];
+    }
+    return [];
+  });
+
+  expect(
+    broken,
+    "styles.css ships as source, so a sibling it imports has to reach the consumer with it:\n" +
+      broken.join("\n"),
+  ).toEqual([]);
+});

package/src/{statusTone.test.ts → theme/statusTone.test.ts}

@@ -13,7 +13,11 @@ describe("status tones", () => {
     expect(STATUS_INK.warning).toBe("text-amber-700 dark:text-amber-400");
     expect(STATUS_INK.success).toBe("text-emerald-700 dark:text-emerald-400");
     expect(STATUS_INK.info).toBe("text-sky-700 dark:text-sky-400");
-    for (const v of [...Object.values(TONE_FILL), ...Object.values(TONE_BORDER), ...Object.values(STATUS_INK)]) {
+    for (const v of [
+      ...Object.values(TONE_FILL),
+      ...Object.values(TONE_BORDER),
+      ...Object.values(STATUS_INK),
+    ]) {
       expect(v).not.toMatch(/\b(?:bg|border|text)-(?:success|warning)\b/);
     }
   });

package/src/{styles.css → theme/styles.css}

@@ -1,17 +1,22 @@
 /*
  * @robomous/ui-core — the design system's stylesheet.
  *
- * This is the shadcn preset `b2iH` (style `nova` on the Radix base, base colour
- * `neutral`, chart palette `neutral`, icons `lucide`, Geist throughout with the
- * heading face inheriting the body's, radius medium, menu inverted/subtle, and
- * the pointer cursor on pressable controls) — the CLI's exact generated output,
- * transcribed verbatim from a Docker scratch project built with `shadcn` 4.19.0. The preset is the source of truth for every
- * name below except one: `brand` is Robomous's own, justified in
- * `DESIGN.md` and following shadcn's own extension convention — a value
- * in `:root`, a dark counterpart in `.dark`, exposure through `@theme
- * inline`. Consumers add their extensions in their own stylesheet after
- * importing this one. `src/tokens.ts` is the TypeScript mirror of this file
- * and `tokens.test.ts` asserts the two agree, declaration for declaration.
+ * **This file is the design system's one home for a colour.** Tailwind v4 is
+ * CSS-first, so this is not a mirror of a config — it *is* the config, and
+ * every utility in this package and in every consuming app resolves through
+ * the names below. `brand` is Robomous's own identity colour, justified in
+ * `DESIGN.md`, and it is declared the way every other name here is: a value in
+ * `:root`, a dark counterpart in `.dark`, exposure through `@theme inline`.
+ * Consumers add their extensions in their own stylesheet after importing this
+ * one. `tokens.ts` is the TypeScript mirror of this file, for callers that
+ * cannot read CSS, and `tokens.test.ts` asserts the two agree declaration for
+ * declaration.
+ *
+ * `./tailwind.css` carries the variant and utility layer the components paint
+ * through: the `data-*` variants that key off the `data-state` attributes the
+ * behaviour libraries emit, plus the scroll-mask and shimmer utilities. It is
+ * imported ahead of the token blocks because a variant has to exist before a
+ * utility can qualify on it.
  *
  * A consuming app imports exactly this:
  *
@@ -24,7 +29,7 @@
 
 @import "tailwindcss";
 @import "tw-animate-css";
-@import "shadcn/tailwind.css";
+@import "./tailwind.css";
 @import "@fontsource-variable/geist";
 
 /*
@@ -38,15 +43,15 @@
 
 :root {
   --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
+  --foreground: oklch(0.2 0 0);
   --card: oklch(1 0 0);
   --card-foreground: oklch(0.145 0 0);
   --popover: oklch(1 0 0);
   --popover-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
+  --primary: oklch(0.2 0 0);
   --primary-foreground: oklch(0.985 0 0);
   --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
+  --secondary-foreground: oklch(0.269 0 0);
   --muted: oklch(0.97 0 0);
   --muted-foreground: oklch(0.556 0 0);
   --accent: oklch(0.97 0 0);
@@ -71,11 +76,15 @@
   --sidebar-ring: oklch(0.708 0 0);
 
   /*
-   * Robomous coral. Identity only — the wordmark and its styleguide swatch,
-   * named in `DESIGN.md` — never a functional-UI colour. A third site
+   * Robomous orange (#F5580B). Identity only — the wordmark and its styleguide
+   * swatch, named in `DESIGN.md` — never a functional-UI colour. A third site
    * is a design decision, not a styling one.
+   *
+   * At 3.34:1 on `background` it clears 3:1 for large text and non-text marks
+   * and misses 4.5:1 for body copy, which is one more reason the wordmark is
+   * where it belongs.
    */
-  --brand: oklch(0.653 0.178 32.3);
+  --brand: oklch(0.663 0.205 39.9);
 }
 
 .dark {
@@ -111,11 +120,11 @@
   --sidebar-border: oklch(1 0 0 / 10%);
   --sidebar-ring: oklch(0.556 0 0);
 
-  --brand: oklch(0.653 0.178 32.3);
+  --brand: oklch(0.663 0.205 39.9);
 }
 
 @theme inline {
-  --font-sans: 'Geist Variable', sans-serif;
+  --font-sans: "Geist Variable", sans-serif;
   --font-heading: var(--font-sans);
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-border: var(--sidebar-border);
@@ -156,15 +165,16 @@
   --radius-3xl: calc(var(--radius) * 2.2);
   --radius-4xl: calc(var(--radius) * 2.6);
 
-  /* Robomous's one identity token, exposed the same way as every preset colour. */
+  /* Robomous's one identity token, exposed the same way as every other colour. */
   --color-brand: var(--brand);
 }
 
 @layer base {
   /* The hairline and the outline *colour* — the two things every element
-     inherits. The focus treatment itself belongs to the primitives: each one
-     carries Nova's own `ring-3` ring in `ring/50` (DESIGN.md, Borders and
-     focus), so the base layer names the colour and stays out of the geometry.
+     inherits. The focus treatment itself belongs to the components: each
+     focusable one carries its own `ring-3` ring in `ring/50` (DESIGN.md,
+     Borders and focus), so the base layer names the colour and stays out of
+     the geometry.
      Nothing here may declare focus geometry again: one blanket declaration in
      this layer is how thirteen components' rings got overridden at once. */
   * {
@@ -186,19 +196,23 @@
   body {
     @apply bg-background text-foreground;
   }
-  /* The preset's pointer option. Scoped to what is actually pressable and away
-     from what is not: a disabled control keeps the arrow, because a hand over
-     something that will not respond is the cursor telling a lie. */
-  button:not(:disabled), [role="button"]:not(:disabled) {
+  /* Scoped to what is actually pressable and away from what is not: a disabled
+     control keeps the arrow, because a hand over something that will not
+     respond is the cursor telling a lie. */
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
     cursor: pointer;
   }
   html {
     @apply font-sans;
   }
-  /* One family now: the preset sets `--font-heading` to `--font-sans`, so this
-     rule keeps the semantic hook without changing the face. A later preset that
+  /* One family now: `--font-heading` resolves to `--font-sans`, so this rule
+     keeps the semantic hook without changing the face. A later decision that
      splits them again lands here without a diff at every heading. */
-  h1, h2, h3, h4 {
+  h1,
+  h2,
+  h3,
+  h4 {
     @apply font-heading;
   }
 }