@nebutra/theme 0.1.1 → 0.2.1

package/src/__tests__/apply-language.test.ts

@@ -0,0 +1,70 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { applyLanguage, clearLanguage, getActiveLanguageId } from "../apply-language";
+import { getBuiltInBrandPackage, listBuiltInBrandIds } from "../built-in-packages";
+
+afterEach(() => {
+  clearLanguage();
+  document.getElementById("nebutra-brand-skin")?.remove();
+  delete document.documentElement.dataset.brand;
+});
+
+describe("getBuiltInBrandPackage", () => {
+  it("loads all stress-test fixtures", () => {
+    const ids = listBuiltInBrandIds();
+    expect(ids).toEqual(
+      expect.arrayContaining(["linear", "gsap", "raycast", "vercel", "vanta", "stripe", "notion"]),
+    );
+    for (const id of ids) {
+      const pkg = getBuiltInBrandPackage(id);
+      expect(pkg?.id).toBe(id);
+      expect(pkg?.semantic.primary).toBeTruthy();
+      expect(pkg?.recipe.buttonDefault).toBeTruthy();
+    }
+  });
+});
+
+describe("applyLanguage", () => {
+  it("applies built-in language without options.package", () => {
+    const entry = applyLanguage("vanta");
+    expect(entry?.id).toBe("vanta");
+    expect(getActiveLanguageId()).toBe("vanta");
+    expect(document.documentElement.dataset.brand).toBe("vanta");
+    const style = document.getElementById("nebutra-brand-skin");
+    expect(style?.textContent).toMatch(/data-brand="vanta"/);
+    // light pack: global inject must not force .dark selector
+    expect(style?.textContent).not.toMatch(/:root,\n\.dark,/);
+  });
+
+  it.each([
+    "linear",
+    "vercel",
+  ] as const)("applies dual-mode language %s with separate light/dark CSS blocks", (id) => {
+    applyLanguage(id);
+    const style = document.getElementById("nebutra-brand-skin");
+    const css = style?.textContent ?? "";
+    expect(css).toMatch(/dualMode=true/);
+    // dual-mode: light under :root / html[data-brand]; dark under .dark / html.dark[data-brand]
+    expect(css).toMatch(new RegExp(`:root,\\nhtml\\[data-brand="${id}"\\]`));
+    expect(css).toMatch(new RegExp(`\\.dark,\\nhtml\\.dark\\[data-brand="${id}"\\]`));
+    // must not glue light palette onto bare .dark (single-mode darkDefault hack)
+    expect(css).not.toMatch(new RegExp(`:root,\\n\\.dark,\\nhtml\\[data-brand="${id}"\\]`));
+  });
+
+  it("clears to factory", () => {
+    applyLanguage("stripe");
+    clearLanguage();
+    expect(getActiveLanguageId()).toBe("factory");
+    expect(document.documentElement.dataset.brand).toBeUndefined();
+    expect(document.getElementById("nebutra-brand-skin")).toBeNull();
+  });
+
+  it("applyLanguage('factory') clears brand", () => {
+    applyLanguage("gsap");
+    applyLanguage("factory");
+    expect(getActiveLanguageId()).toBe("factory");
+    expect(document.getElementById("nebutra-brand-skin")).toBeNull();
+  });
+});

package/src/__tests__/languages.test.ts

@@ -0,0 +1,100 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { listBuiltInBrandIds } from "../built-in-packages";
+import {
+  DEFAULT_LANGUAGE,
+  getLanguageById,
+  isLanguageId,
+  LANGUAGE_IDS,
+  LANGUAGE_REGISTRY,
+  listSkinLanguages,
+} from "../languages";
+
+const tokensRoot = resolve(fileURLToPath(new URL("../../../tokens", import.meta.url)));
+const brandsRoot = resolve(tokensRoot, "brands");
+
+describe("@nebutra/theme design-language catalog", () => {
+  it("lists factory + stress-test fixtures as languages", () => {
+    expect(DEFAULT_LANGUAGE).toBe("factory");
+    expect(LANGUAGE_IDS).toEqual(
+      expect.arrayContaining([
+        "factory",
+        "linear",
+        "gsap",
+        "raycast",
+        "vercel",
+        "vanta",
+        "stripe",
+        "notion",
+      ]),
+    );
+    expect(LANGUAGE_IDS[0]).toBe("factory");
+  });
+
+  it("documents contract proofs per skin language", () => {
+    for (const lang of listSkinLanguages()) {
+      expect(lang.proves.length).toBeGreaterThan(0);
+      expect(lang.brandPath).toMatch(/^brands\/.+\/brand\.json$/);
+      expect(lang.skinPath).toMatch(/^skins\/.+\.css$/);
+      expect(lang.compatibility.brandPackage).toBe(true);
+      expect(lang.compatibility.dataBrand).toBe(true);
+    }
+  });
+
+  it("keeps brand.json + published skins/<id>.css for each non-factory language", () => {
+    for (const lang of listSkinLanguages()) {
+      expect(lang.brandPath).toBeTruthy();
+      expect(lang.skinPath).toBeTruthy();
+      if (!lang.brandPath || !lang.skinPath) continue;
+      expect(existsSync(resolve(tokensRoot, lang.brandPath))).toBe(true);
+      expect(existsSync(resolve(tokensRoot, lang.skinPath))).toBe(true);
+      // No dual-write brands/<id>/skin.css
+      expect(existsSync(resolve(tokensRoot, "brands", lang.id, "skin.css"))).toBe(false);
+    }
+  });
+
+  it("supports lookup without hardcoding fixture lists in apps", () => {
+    expect(getLanguageById("vanta")?.proves.some((p) => /brand-mark|action/i.test(p))).toBe(true);
+    expect(getLanguageById("missing")).toBeUndefined();
+    expect(isLanguageId("linear")).toBe(true);
+    expect(isLanguageId("nebutra")).toBe(false);
+  });
+
+  it("describes the package as design-language swap not mood tint", () => {
+    expect(LANGUAGE_REGISTRY.description).toMatch(/Brand Package/i);
+    expect(LANGUAGE_REGISTRY.description).toMatch(/roles|recipe/i);
+  });
+
+  it("keeps languages.json, brands/ dirs, and built-in packages in sync", () => {
+    const diskBrandIds = readdirSync(brandsRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+    const catalogSkinIds = listSkinLanguages()
+      .map((l) => l.id)
+      .sort();
+    const builtInIds = listBuiltInBrandIds().sort();
+
+    expect(catalogSkinIds).toEqual(diskBrandIds);
+    expect(builtInIds).toEqual(diskBrandIds);
+
+    for (const id of diskBrandIds) {
+      const lang = getLanguageById(id);
+      expect(lang?.brandPath).toBe(`brands/${id}/brand.json`);
+      expect(lang?.skinPath).toBe(`skins/${id}.css`);
+      expect(existsSync(resolve(brandsRoot, id, "brand.json"))).toBe(true);
+    }
+  });
+
+  it("derives catalog names/darkDefault from brand.json (sync-languages SSOT)", () => {
+    for (const lang of listSkinLanguages()) {
+      const brand = JSON.parse(
+        readFileSync(resolve(tokensRoot, lang.brandPath as string), "utf8"),
+      ) as { name: string; darkDefault: boolean };
+      expect(lang.name).toBe(brand.name);
+      expect(lang.darkDefault).toBe(brand.darkDefault);
+    }
+  });
+});

package/src/__tests__/theme-registry.test.ts

@@ -1,49 +1,27 @@
-import { readFile } from "node:fs/promises";
+/**
+ * Mood catalog is deleted — only design languages remain.
+ * Empty registry shim was removed; assert LANGUAGE_REGISTRY is the sole catalog.
+ */
 import { describe, expect, it } from "vitest";
-import { getThemeById, THEME_IDS, THEME_REGISTRY } from "../index";
+import { DEFAULT_LANGUAGE, isLanguageId, LANGUAGE_IDS, LANGUAGE_REGISTRY } from "../languages";
 
-function getTokenAtPath(tokens: Record<string, unknown>, tokenPath: string): unknown {
-  return tokenPath.split(".").reduce<unknown>((node, key) => {
-    if (!node || typeof node !== "object") return undefined;
-    return (node as Record<string, unknown>)[key];
-  }, tokens);
-}
-
-describe("@nebutra/theme registry contract", () => {
-  it("exports deterministic theme ids from the registry", () => {
-    expect(THEME_IDS).toEqual(["neon", "gradient", "dark-dense", "minimal", "vibrant", "ocean"]);
+describe("@nebutra/theme — no mood registry", () => {
+  it("ships design languages only (factory + skins)", () => {
+    expect(DEFAULT_LANGUAGE).toBe("factory");
+    expect(LANGUAGE_IDS).toContain("factory");
+    expect(LANGUAGE_IDS.length).toBeGreaterThan(1);
+    expect(LANGUAGE_REGISTRY.languages.length).toBe(LANGUAGE_IDS.length);
   });
 
-  it("exposes install and governance metadata for each built-in theme", () => {
-    for (const theme of THEME_REGISTRY.themes) {
-      expect(theme.id).toMatch(/^[a-z0-9-]+$/u);
-      expect(theme.tokenPath).toBe(`tokens/themes/${theme.id}.json`);
-      expect(theme.install.command).toContain(`nebutra theme add ${theme.id}`);
-      expect(theme.governance.requiredTokens.length).toBeGreaterThan(0);
-      expect(theme.governance.wcag).toBe("AA");
-      expect(theme.compatibility.tailwind).toBe("4");
-      expect(theme.compatibility.figmaVariables).toBe(true);
-    }
+  it("rejects legacy oklch mood ids", () => {
+    expect(isLanguageId("crimson-light-vivid")).toBe(false);
+    expect(isLanguageId("vibrant")).toBe(false);
+    expect(isLanguageId("azure-dark-muted")).toBe(false);
   });
 
-  it("keeps registry token paths and required tokens backed by DTCG files", async () => {
-    for (const theme of THEME_REGISTRY.themes) {
-      const tokenFile = new URL(`../../../design-tokens/${theme.tokenPath}`, import.meta.url);
-      const tokens = JSON.parse(await readFile(tokenFile, "utf8")) as Record<string, unknown>;
-
-      expect(tokens.theme).toBe(theme.id);
-
-      for (const requiredToken of theme.governance.requiredTokens) {
-        expect(getTokenAtPath(tokens, requiredToken)).toMatchObject({
-          $type: expect.any(String),
-          $value: expect.any(String),
-        });
-      }
+  it("accepts design language ids", () => {
+    for (const id of LANGUAGE_IDS) {
+      expect(isLanguageId(id)).toBe(true);
     }
   });
-
-  it("supports lookup by id without callers hardcoding theme details", () => {
-    expect(getThemeById("neon")?.mood).toContain("AI");
-    expect(getThemeById("missing")).toBeUndefined();
-  });
 });

package/src/apply-language.ts

@@ -0,0 +1,87 @@
+/**
+ * Runtime design-language switch — Create Center / SaaS global theme swap.
+ *
+ * Light/dark remains class="dark" on @nebutra/tokens ThemeProvider.
+ * Design language is html[data-brand] + Brand Package CSS inject.
+ *
+ * Built-in languages load Brand Packages automatically; pass `package` only for
+ * custom / compile-time packages (Create Center preview).
+ */
+
+import {
+  type ApplyBrandOptions,
+  applyBrandPackage,
+  type BrandPackage,
+  clearBrand,
+  getActiveBrandId,
+  normalizeBrandPackage,
+  validateBrandPackage,
+} from "@nebutra/tokens/brand-package";
+import { getBuiltInBrandPackage } from "./built-in-packages";
+import { type DesignLanguageEntry, getLanguageById } from "./languages";
+
+export type { ApplyBrandOptions };
+
+export interface ApplyLanguageOptions extends ApplyBrandOptions {
+  /**
+   * Preloaded Brand Package (Create Center compile result or override).
+   * When omitted, built-in languages resolve from brands/<id>/brand.json.
+   */
+  package?: BrandPackage;
+}
+
+/**
+ * Apply a design language by id.
+ * - `factory` / unknown without package → clearBrand (tokens SSOT)
+ * - built-in id without package → load shipped Brand Package
+ * - with `package` → applyBrandPackage (full carrier swap)
+ */
+export function applyLanguage(
+  languageId: string,
+  options: ApplyLanguageOptions = {},
+): DesignLanguageEntry | null {
+  const entry = getLanguageById(languageId);
+
+  if (!entry || entry.id === "factory" || entry.brandPath == null) {
+    if (options.package) {
+      const v = validateBrandPackage(options.package);
+      if (!v.ok) {
+        throw new Error(`Invalid Brand Package: ${v.errors.join("; ")}`);
+      }
+      applyBrandPackage(normalizeBrandPackage(options.package), options);
+      return entry ?? null;
+    }
+    clearBrand(options);
+    return entry ?? getLanguageById("factory") ?? null;
+  }
+
+  const pkg = options.package ?? getBuiltInBrandPackage(languageId);
+  if (!pkg) {
+    throw new Error(
+      `Language "${languageId}" has no built-in Brand Package and no options.package. ` +
+        `Load @nebutra/tokens/${entry.brandPath} or compileReferoTokens(), then ` +
+        `applyLanguage("${languageId}", { package }). ` +
+        `Or import the single skin CSS: ${entry.install.cssImport ?? "(none)"}.`,
+    );
+  }
+
+  const v = validateBrandPackage(pkg);
+  if (!v.ok) {
+    throw new Error(`Invalid Brand Package for ${languageId}: ${v.errors.join("; ")}`);
+  }
+  const normalized = normalizeBrandPackage({
+    ...pkg,
+    id: languageId,
+  });
+  applyBrandPackage(normalized, options);
+  return entry;
+}
+
+/** Restore factory product chrome (clear data-brand + injected skin). */
+export function clearLanguage(options: ApplyBrandOptions = {}): void {
+  clearBrand(options);
+}
+
+export function getActiveLanguageId(doc?: Document): string {
+  return getActiveBrandId(doc) ?? "factory";
+}

package/src/brand-package-surface.ts

@@ -0,0 +1,30 @@
+/**
+ * Tooling / Create Center surface — compile + iframe preview + emit.
+ * Prefer `@nebutra/tokens/brand-package` in new code; this re-export keeps
+ * historical `@nebutra/theme` compile entry points without bloating the root.
+ */
+
+export {
+  applyBrandCss,
+  applyBrandPackage,
+  applyBrandToIframe,
+  BRAND_STORAGE_KEY,
+  type BrandPackage,
+  type BrandPackageInput,
+  type BrandRecipe,
+  type BrandRecipeInput,
+  type CompileResult,
+  clearBrand,
+  compileReferoTokens,
+  type EmitBrandCssMode,
+  type EmitBrandCssOptions,
+  emitBrandCss,
+  emitGlobalSkinSelector,
+  getActiveBrandId,
+  normalizeBrandPackage,
+  restorePersistedBrand,
+  useBrand,
+  useBrandIframePreview,
+  type ValidationResult,
+  validateBrandPackage,
+} from "@nebutra/tokens/brand-package";

package/src/built-in-packages.generated.ts

@@ -0,0 +1,39 @@
+/**
+ * AUTO-GENERATED by scripts/sync-languages.mjs — DO NOT EDIT.
+ * Built-in Brand Packages for applyLanguage(id) without manual JSON import.
+ * Source: packages/design/tokens/brands/<id>/brand.json
+ */
+
+import { type BrandPackage, normalizeBrandPackage } from "@nebutra/tokens/brand-package";
+import gsap from "@nebutra/tokens/brands/gsap/brand.json" with { type: "json" };
+import linear from "@nebutra/tokens/brands/linear/brand.json" with { type: "json" };
+import notion from "@nebutra/tokens/brands/notion/brand.json" with { type: "json" };
+import raycast from "@nebutra/tokens/brands/raycast/brand.json" with { type: "json" };
+import stripe from "@nebutra/tokens/brands/stripe/brand.json" with { type: "json" };
+import vanta from "@nebutra/tokens/brands/vanta/brand.json" with { type: "json" };
+import vercel from "@nebutra/tokens/brands/vercel/brand.json" with { type: "json" };
+
+const RAW_BUILT_IN: Record<string, BrandPackage> = {
+  gsap: gsap as BrandPackage,
+  linear: linear as BrandPackage,
+  notion: notion as BrandPackage,
+  raycast: raycast as BrandPackage,
+  stripe: stripe as BrandPackage,
+  vanta: vanta as BrandPackage,
+  vercel: vercel as BrandPackage,
+};
+
+/** Normalized package for a shipped design-language id, or undefined. */
+export function getBuiltInBrandPackage(id: string): BrandPackage | undefined {
+  const raw = RAW_BUILT_IN[id];
+  if (!raw) return undefined;
+  return normalizeBrandPackage({ ...raw, id });
+}
+
+export function listBuiltInBrandIds(): string[] {
+  return Object.keys(RAW_BUILT_IN);
+}
+
+export function hasBuiltInBrandPackage(id: string): boolean {
+  return id in RAW_BUILT_IN;
+}

package/src/built-in-packages.ts

@@ -0,0 +1,14 @@
+/**
+ * Built-in Brand Packages for design-language ids.
+ *
+ * Implementation is AUTO-GENERATED — see built-in-packages.generated.ts
+ * (pnpm --filter @nebutra/theme sync:languages).
+ *
+ * SSOT remains packages/design/tokens/brands/<id>/brand.json.
+ */
+
+export {
+  getBuiltInBrandPackage,
+  hasBuiltInBrandPackage,
+  listBuiltInBrandIds,
+} from "./built-in-packages.generated";

package/src/client.ts

@@ -0,0 +1,35 @@
+/**
+ * Explicit client entry — same lean surface as package root.
+ * Use: `import { applyLanguage } from "@nebutra/theme/client"`
+ *
+ * Light/dark: `import { ThemeProvider, useTheme } from "@nebutra/tokens"`
+ */
+
+export {
+  applyBrandPackage,
+  type BrandPackage,
+  clearBrand,
+  normalizeBrandPackage,
+} from "@nebutra/tokens/brand-package";
+export {
+  type ApplyLanguageOptions,
+  applyLanguage,
+  clearLanguage,
+  getActiveLanguageId,
+} from "./apply-language";
+export {
+  getBuiltInBrandPackage,
+  hasBuiltInBrandPackage,
+  listBuiltInBrandIds,
+} from "./built-in-packages";
+export {
+  BUILT_IN_LANGUAGE_IDS,
+  DEFAULT_LANGUAGE,
+  type DesignLanguageEntry,
+  type DesignLanguageRegistry,
+  getLanguageById,
+  isLanguageId,
+  LANGUAGE_IDS,
+  LANGUAGE_REGISTRY,
+  listSkinLanguages,
+} from "./languages";

package/src/index.ts

@@ -1,20 +1,53 @@
-// packages/design/theme/src/index.ts
-// Re-export next-themes for convenience — all apps import from @nebutra/theme.
-// Theme catalog metadata lives in ./registry so CLI/preset/docs/Figma sync all
-// discover the same built-in theme contract.
-
-export type { ThemeProviderProps } from "next-themes";
-export { ThemeProvider, useTheme } from "next-themes";
+/**
+ * @nebutra/theme — Design-language switch surface (client-safe root)
+ *
+ * Root exports are intentionally lean for app bundles:
+ *   applyLanguage / LANGUAGE_REGISTRY / built-in packages
+ *
+ * Light/dark ThemeProvider: import from `@nebutra/tokens` only (not here).
+ *
+ * Compile & Create Center tooling:
+ *   @nebutra/tokens/brand-package  (preferred)
+ *   @nebutra/theme/brand-package   (re-export alias)
+ *
+ * Layers:
+ *   @nebutra/tokens  product chrome SSOT (styles.css + recipe.css + ThemeProvider)
+ *   @nebutra/theme   LANGUAGE_REGISTRY + applyLanguage + skins.css
+ */
 
+// Re-export apply helpers used with applyLanguage({ package })
+export {
+  type ApplyBrandOptions,
+  applyBrandPackage,
+  type BrandPackage,
+  clearBrand,
+  getActiveBrandId,
+  normalizeBrandPackage,
+  type ValidationResult,
+  validateBrandPackage,
+} from "@nebutra/tokens/brand-package";
+export {
+  type ApplyLanguageOptions,
+  applyLanguage,
+  clearLanguage,
+  getActiveLanguageId,
+} from "./apply-language";
+export {
+  getBuiltInBrandPackage,
+  hasBuiltInBrandPackage,
+  listBuiltInBrandIds,
+} from "./built-in-packages";
 export {
-  BUILT_IN_THEME_IDS,
-  DEFAULT_THEME,
-  getThemeById,
-  isBuiltInThemeId,
-  isThemeId,
-  THEME_IDS,
-  THEME_REGISTRY,
-  type ThemeId,
-  type ThemeRegistry,
-  type ThemeRegistryEntry,
-} from "./registry";
+  BUILT_IN_LANGUAGE_IDS,
+  DEFAULT_LANGUAGE,
+  type DesignLanguageCompatibility,
+  type DesignLanguageEntry,
+  type DesignLanguageInstall,
+  type DesignLanguageRegistry,
+  getLanguageById,
+  isLanguageId,
+  LANGUAGE_IDS,
+  LANGUAGE_REGISTRY,
+  type LanguageId,
+  listSkinLanguages,
+} from "./languages";