@nebutra/tokens 0.1.0 → 0.1.2

package/src/brand-package/use-brand.ts

@@ -0,0 +1,207 @@
+"use client";
+
+import { type RefObject, useCallback, useEffect, useRef, useState } from "react";
+import {
+  type ApplyBrandOptions,
+  applyBrandPackage,
+  clearBrand,
+  getActiveBrandId,
+  restorePersistedBrand,
+} from "./apply-brand";
+import { emitBrandCss } from "./emit-css";
+import type { BrandPackage } from "./types";
+
+export interface UseBrandOptions {
+  /** Restore from localStorage on mount */
+  autoRestore?: boolean;
+  /** Persist apply/clear to localStorage */
+  persist?: boolean;
+}
+
+export interface UseBrandResult {
+  brand: BrandPackage | null;
+  brandId: string | null;
+  apply: (brand: BrandPackage) => void;
+  clear: () => void;
+  restore: () => BrandPackage | null;
+}
+
+/**
+ * Create Center / app-level brand state for the host document.
+ */
+export function useBrand(options: UseBrandOptions = {}): UseBrandResult {
+  const { autoRestore = false, persist = true } = options;
+  const [brand, setBrand] = useState<BrandPackage | null>(null);
+  const [brandId, setBrandId] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!autoRestore) return;
+    const restored = restorePersistedBrand({ persist: false });
+    if (restored) {
+      setBrand(restored);
+      setBrandId(restored.id);
+    } else {
+      setBrandId(getActiveBrandId());
+    }
+  }, [autoRestore]);
+
+  const apply = useCallback(
+    (next: BrandPackage) => {
+      applyBrandPackage(next, { persist });
+      setBrand(next);
+      setBrandId(next.id);
+    },
+    [persist],
+  );
+
+  const clear = useCallback(() => {
+    clearBrand({ persist });
+    setBrand(null);
+    setBrandId(null);
+  }, [persist]);
+
+  const restore = useCallback(() => {
+    const restored = restorePersistedBrand({ persist: false });
+    if (restored) {
+      setBrand(restored);
+      setBrandId(restored.id);
+    }
+    return restored;
+  }, []);
+
+  return { brand, brandId, apply, clear, restore };
+}
+
+export interface BrandIframePreviewOptions {
+  /**
+   * Stylesheets the iframe must load before the brand skin
+   * (e.g. app CSS URL that already includes tokens + recipe).
+   */
+  baseStylesheetHrefs?: string[];
+  /** Extra head HTML (fonts CDN, etc.) */
+  headHtml?: string;
+  /** Minimal body wrapper class */
+  bodyClassName?: string;
+  /** Called after brand CSS is injected into the iframe */
+  onApplied?: (brand: BrandPackage | null) => void;
+}
+
+export interface UseBrandIframePreviewResult {
+  iframeRef: RefObject<HTMLIFrameElement | null>;
+  brand: BrandPackage | null;
+  /** Write/update brand inside the iframe document */
+  apply: (brand: BrandPackage) => void;
+  clear: () => void;
+  /**
+   * Optional: write a self-contained preview document.
+   * Use when the iframe has no host app styles yet.
+   */
+  writePreviewDocument: (brand: BrandPackage, bodyHtml?: string) => void;
+}
+
+function ensureIframeDoc(iframe: HTMLIFrameElement | null): Document | null {
+  if (!iframe) return null;
+  try {
+    return iframe.contentDocument;
+  } catch {
+    return null; // cross-origin
+  }
+}
+
+function injectBaseStyles(doc: Document, hrefs: string[] | undefined): void {
+  if (!hrefs?.length) return;
+  for (const href of hrefs) {
+    const id = `nebutra-base-${hashHref(href)}`;
+    if (doc.getElementById(id)) continue;
+    const link = doc.createElement("link");
+    link.id = id;
+    link.rel = "stylesheet";
+    link.href = href;
+    doc.head.appendChild(link);
+  }
+}
+
+function hashHref(href: string): string {
+  let h = 0;
+  for (let i = 0; i < href.length; i++) h = (h * 31 + href.charCodeAt(i)) | 0;
+  return Math.abs(h).toString(36);
+}
+
+/**
+ * Multi-tenant / Create Center iframe preview.
+ * Applies Brand Packages into the iframe's document without touching the host shell.
+ */
+export function useBrandIframePreview(
+  options: BrandIframePreviewOptions = {},
+): UseBrandIframePreviewResult {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null);
+  const [brand, setBrand] = useState<BrandPackage | null>(null);
+  const optsRef = useRef(options);
+  optsRef.current = options;
+
+  const apply = useCallback((next: BrandPackage) => {
+    const doc = ensureIframeDoc(iframeRef.current);
+    if (!doc?.documentElement) {
+      setBrand(next);
+      return;
+    }
+    injectBaseStyles(doc, optsRef.current.baseStylesheetHrefs);
+    applyBrandPackage(next, { doc, persist: false });
+    setBrand(next);
+    optsRef.current.onApplied?.(next);
+  }, []);
+
+  const clear = useCallback(() => {
+    const doc = ensureIframeDoc(iframeRef.current);
+    if (doc) clearBrand({ doc, persist: false });
+    setBrand(null);
+    optsRef.current.onApplied?.(null);
+  }, []);
+
+  const writePreviewDocument = useCallback((next: BrandPackage, bodyHtml = "") => {
+    const iframe = iframeRef.current;
+    if (!iframe) return;
+    const css = emitBrandCss(next);
+    const links = (optsRef.current.baseStylesheetHrefs ?? [])
+      .map((href) => `<link rel="stylesheet" href="${href}" />`)
+      .join("\n");
+    const html = `<!DOCTYPE html>
+<html lang="en" data-brand="${next.id}" class="${next.darkDefault ? "dark" : ""}">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  ${links}
+  ${optsRef.current.headHtml ?? ""}
+  <style id="nebutra-brand-skin">${css}</style>
+  <style>
+    html, body { margin: 0; min-height: 100%; }
+    body {
+      font-family: var(--font-sans, system-ui, sans-serif);
+      background: hsl(var(--background));
+      color: hsl(var(--foreground));
+    }
+  </style>
+</head>
+<body class="${optsRef.current.bodyClassName ?? "zone-product"} bg-background text-foreground">
+  ${bodyHtml}
+</body>
+</html>`;
+    iframe.srcdoc = html;
+    setBrand(next);
+    optsRef.current.onApplied?.(next);
+  }, []);
+
+  return { iframeRef, brand, apply, clear, writePreviewDocument };
+}
+
+/** Imperative helper for non-hook call sites */
+export function applyBrandToIframe(
+  iframe: HTMLIFrameElement,
+  brand: BrandPackage,
+  options: ApplyBrandOptions & { baseStylesheetHrefs?: string[] } = {},
+): void {
+  const doc = iframe.contentDocument;
+  if (!doc) return;
+  injectBaseStyles(doc, options.baseStylesheetHrefs);
+  applyBrandPackage(brand, { ...options, doc, persist: false });
+}

package/src/brand-package/validate.ts

@@ -0,0 +1,108 @@
+import { normalizeBrandPackage } from "./normalize";
+import type { BrandPackage, ButtonDefaultStyle } from "./types";
+
+const BUTTON_STYLES = new Set<ButtonDefaultStyle>(["solid", "outline", "gradient-stroke"]);
+
+export interface ValidationResult {
+  ok: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/** Validate carrier contract before Create Center publish. */
+export function validateBrandPackage(brand: unknown): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (!brand || typeof brand !== "object") {
+    return { ok: false, errors: ["Brand package must be an object"], warnings };
+  }
+  let b: BrandPackage;
+  try {
+    b = normalizeBrandPackage(brand as BrandPackage);
+  } catch (e) {
+    return { ok: false, errors: [`normalize failed: ${(e as Error).message}`], warnings };
+  }
+
+  if (!b.id || typeof b.id !== "string") errors.push("id is required");
+  if (!b.name || typeof b.name !== "string") errors.push("name is required");
+  if (!b.version || typeof b.version !== "string") errors.push("version is required");
+
+  if (!b.roles) {
+    errors.push("roles missing after normalize");
+  } else {
+    for (const key of ["canvas", "action", "actionForeground", "border"] as const) {
+      if (!b.roles[key]) errors.push(`roles.${key} is required`);
+    }
+    if (b.roles.brand && b.roles.brand === b.roles.action) {
+      warnings.push(
+        "roles.brand equals roles.action — brand mark is not separated from CTA (often intentional)",
+      );
+    }
+  }
+
+  if (!b.semantic || typeof b.semantic !== "object") {
+    errors.push("semantic is required");
+  } else {
+    for (const key of [
+      "background",
+      "foreground",
+      "primary",
+      "primaryForeground",
+      "border",
+      "ring",
+    ] as const) {
+      if (!b.semantic[key]) errors.push(`semantic.${key} is required`);
+    }
+    // Contract: primary must track action
+    if (b.roles && b.semantic.primary !== b.roles.action) {
+      errors.push("semantic.primary must equal roles.action (CTA bridge)");
+    }
+  }
+
+  if (!b.recipe || typeof b.recipe !== "object") {
+    errors.push("recipe is required");
+  } else {
+    if (!BUTTON_STYLES.has(b.recipe.buttonDefault as ButtonDefaultStyle)) {
+      errors.push(`recipe.buttonDefault must be one of ${[...BUTTON_STYLES].join(", ")}`);
+    }
+    if (!b.recipe.radii?.button) errors.push("recipe.radii.button is required");
+    if (!b.recipe.radii?.card) errors.push("recipe.radii.card is required");
+    if (!b.recipe.elevationTokens?.card) {
+      errors.push("recipe.elevationTokens.card is required (free CSS box-shadow)");
+    }
+    if (b.recipe.buttonDefault === "gradient-stroke" && !b.recipe.primaryStrokeGradient) {
+      warnings.push(
+        "gradient-stroke without primaryStrokeGradient — border falls back to solid primary",
+      );
+    }
+  }
+  if (!b.typography?.fontSans) errors.push("typography.fontSans is required");
+
+  if (b.typography?.faces) {
+    b.typography.faces.forEach((face, i) => {
+      if (!face.family) errors.push(`typography.faces[${i}].family is required`);
+      if (!face.src?.length) errors.push(`typography.faces[${i}].src must be non-empty`);
+      else {
+        for (const [j, src] of face.src.entries()) {
+          if (!src.url) errors.push(`typography.faces[${i}].src[${j}].url is required`);
+        }
+      }
+    });
+  }
+
+  if (b.zones?.marketing?.display && !b.zones.product) {
+    warnings.push(
+      "marketing.display set without product zone — app shell may inherit display size",
+    );
+  }
+
+  if (
+    b.recipe?.buttonDefault === "solid" &&
+    b.semantic?.primary === b.semantic?.primaryForeground
+  ) {
+    warnings.push("primary and primaryForeground are identical — check contrast");
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}

package/src/index.ts

@@ -20,7 +20,7 @@
  *
  * Related packages:
  *   @nebutra/brand  → brand primitives (color definitions, motion language)
- *   @nebutra/theme  → multi-theme presets (6 oklch variants for SaaS product)
+ *   @nebutra/theme  → design-language catalog (Brand Package global swap)
  *   @nebutra/ui     → component library (consumes tokens via CSS variables)
  */
 
@@ -35,3 +35,33 @@ export const THEME_IDS = ["light", "dark"] as const;
 export type ThemeId = (typeof THEME_IDS)[number];
 
 export const DEFAULT_THEME: ThemeId = "dark";
+
+/** Create Center brand package: carrier contract + runtime apply */
+export {
+  applyBrandCss,
+  applyBrandPackage,
+  applyBrandToIframe,
+  BRAND_STORAGE_KEY,
+  type BrandColorRoles,
+  type BrandElevationTokens,
+  type BrandFontFace,
+  type BrandPackage,
+  type BrandRadii,
+  type BrandRecipe,
+  type BrandZones,
+  type CompileResult,
+  clearBrand,
+  compileReferoTokens,
+  emitBrandCss,
+  getActiveBrandId,
+  hexToHslChannels,
+  inferRecipeFromDesignMd,
+  normalizeBrandPackage,
+  restorePersistedBrand,
+  rolesFromSemantic,
+  semanticFromRoles,
+  useBrand,
+  useBrandIframePreview,
+  type ValidationResult,
+  validateBrandPackage,
+} from "./brand-package";

package/src/theme-provider.tsx

@@ -42,8 +42,12 @@ const THEMES = ["light", "dark", "system"] as const satisfies readonly Theme[];
 export const THEME_STORAGE_KEY = "theme";
 
 interface ThemeContextValue {
+  /** Whether a real ThemeProvider is present above the consumer. */
+  isProviderBound: boolean;
   /** The raw user preference. May be "system". */
   theme: Theme;
+  /** Provider-level override for demos, locked routes, or embedded previews. */
+  forcedTheme?: Theme | undefined;
   /** The concretely-applied theme — always "light" or "dark". */
   resolvedTheme: ResolvedTheme;
   /** The OS-level preference (always concrete). */
@@ -62,7 +66,9 @@ export function useTheme(): ThemeContextValue {
   const ctx = useContext(ThemeContext);
   if (ctx) return ctx;
   return {
+    isProviderBound: false,
     theme: "system",
+    forcedTheme: undefined,
     resolvedTheme: "light",
     systemTheme: "light",
     setTheme: () => {
@@ -107,6 +113,7 @@ function applyThemeToDom(
   resolved: ResolvedTheme,
   attribute: "class" | "data-theme",
   disableTransitionOnChange: boolean,
+  nonce?: string,
 ) {
   if (typeof document === "undefined") return;
   const root = document.documentElement;
@@ -114,6 +121,7 @@ function applyThemeToDom(
   // Suppress CSS transitions during the swap so the change appears instant.
   if (disableTransitionOnChange) {
     const suppressor = document.createElement("style");
+    if (nonce) suppressor.setAttribute("nonce", nonce);
     suppressor.appendChild(
       document.createTextNode(
         "*,*::before,*::after{transition:none!important;animation-duration:0s!important}",
@@ -134,7 +142,6 @@ function applyThemeToDom(
   } else {
     root.setAttribute("data-theme", resolved);
   }
-  root.style.colorScheme = resolved;
 }
 
 export interface ThemeProviderProps {
@@ -145,6 +152,8 @@ export interface ThemeProviderProps {
   defaultTheme?: Theme;
   /** Whether `"system"` is a valid theme that tracks `prefers-color-scheme`. */
   enableSystem?: boolean;
+  /** Lock the rendered theme and expose read-only state to controls. */
+  forcedTheme?: Theme | undefined;
   /** Suppress CSS transitions during the swap. Default: `true`. */
   disableTransitionOnChange?: boolean;
   /** Storage key under which the preference is persisted. */
@@ -158,17 +167,21 @@ export function ThemeProvider({
   attribute = "class",
   defaultTheme = "system",
   enableSystem = true,
+  forcedTheme,
   disableTransitionOnChange = true,
   storageKey = THEME_STORAGE_KEY,
+  nonce,
 }: ThemeProviderProps) {
   const [theme, setThemeState] = useState<Theme>(() => readStoredTheme(storageKey, defaultTheme));
   const [systemTheme, setSystemTheme] = useState<ResolvedTheme>(() => resolveSystemTheme());
 
+  const effectiveTheme = forcedTheme ?? theme;
   const resolvedTheme: ResolvedTheme =
-    theme === "system" ? (enableSystem ? systemTheme : "light") : theme;
+    effectiveTheme === "system" ? (enableSystem ? systemTheme : "light") : effectiveTheme;
 
   const setTheme = useCallback(
     (next: Theme) => {
+      if (forcedTheme !== undefined) return;
       setThemeState(next);
       try {
         if (next === "system") {
@@ -180,16 +193,16 @@ export function ThemeProvider({
         // localStorage may be disabled — accept the loss
       }
     },
-    [storageKey],
+    [forcedTheme, storageKey],
   );
 
   // Apply the resolved theme to the DOM AND sync the cookie so the next
   // SSR can render the correct <html> class directly (no inline script,
   // no React 19 "script in component" warning).
   useEffect(() => {
-    applyThemeToDom(resolvedTheme, attribute, disableTransitionOnChange);
+    applyThemeToDom(resolvedTheme, attribute, disableTransitionOnChange, nonce);
     writeThemeCookie(resolvedTheme, storageKey);
-  }, [resolvedTheme, attribute, disableTransitionOnChange, storageKey]);
+  }, [resolvedTheme, attribute, disableTransitionOnChange, nonce, storageKey]);
 
   // Follow OS preference changes when in `system` mode
   useEffect(() => {
@@ -218,13 +231,15 @@ export function ThemeProvider({
 
   const value = useMemo<ThemeContextValue>(
     () => ({
+      isProviderBound: true,
       theme,
+      forcedTheme,
       resolvedTheme,
       systemTheme,
       setTheme,
       themes: THEMES,
     }),
-    [theme, resolvedTheme, systemTheme, setTheme],
+    [theme, forcedTheme, resolvedTheme, systemTheme, setTheme],
   );
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;