@nebutra/tokens 0.1.2 → 0.1.3

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

@@ -1,207 +0,0 @@
-"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

@@ -1,108 +0,0 @@
-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

@@ -1,67 +0,0 @@
-/**
- * @nebutra/tokens — Runtime theme tokens & theme switching
- *
- * This package is the SINGLE SOURCE OF TRUTH for runtime design tokens.
- *
- * CSS tokens:  @import "@nebutra/tokens/styles.css"
- *   → Brand color scales (--nebutra-blue-*, --nebutra-cyan-*)
- *   → 12-step functional scales (--neutral-1..12, --blue-1..12, --cyan-1..12)
- *   → Semantic variables (--primary, --background, --border, etc.)
- *   → Light/dark mode via :root / .dark
- *   → Display-P3 wide gamut with sRGB fallback
- *   → Tailwind v4 @theme integration
- *
- * JS exports:  ThemeProvider, useTheme, THEME_STORAGE_KEY (custom — no next-themes)
- *   → App-level light/dark mode switching
- *   → ThemeProvider writes BOTH localStorage AND a cookie of the same name.
- *     Server Components read the cookie via `next/headers` cookies() and
- *     inject the resolved class directly into <html> — zero inline script,
- *     zero React 19 "script in component" warning, zero FOUC risk.
- *
- * Related packages:
- *   @nebutra/brand  → brand primitives (color definitions, motion language)
- *   @nebutra/theme  → design-language catalog (Brand Package global swap)
- *   @nebutra/ui     → component library (consumes tokens via CSS variables)
- */
-
-export {
-  THEME_STORAGE_KEY,
-  ThemeProvider,
-  type ThemeProviderProps,
-  useTheme,
-} from "./theme-provider";
-
-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

@@ -1,246 +0,0 @@
-"use client";
-
-/**
- * Custom ThemeProvider — replaces the upstream `next-themes` re-export.
- *
- * Why we own this: `next-themes@0.4.x` renders an inline `<script>` element
- * inside its Client-Component provider for FOUC prevention. React 19 +
- * Next.js 16 (Turbopack) now emit a console error when scripts appear
- * inside Client Components ("Scripts inside React components are never
- * executed when rendering on the client"). The script DID do its job at
- * SSR time, but the warning pollutes the dev console on every page load.
- *
- * Our architecture splits the two concerns cleanly:
- *   - {@link ThemeProvider}  (Client) — runtime state, OS sync, transitions
- *   - {@link ThemeScript}    (Server) — synchronous FOUC-prevention inline
- *                                       script rendered into the SSR HTML
- *
- * The API surface mirrors next-themes so the migration is a drop-in for
- * callers (same prop names: `attribute`, `defaultTheme`, `enableSystem`,
- * `disableTransitionOnChange`, `storageKey`, `nonce`).
- */
-
-import {
-  createContext,
-  type ReactNode,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useState,
-} from "react";
-
-type Theme = "light" | "dark" | "system";
-type ResolvedTheme = "light" | "dark";
-
-const THEMES = ["light", "dark", "system"] as const satisfies readonly Theme[];
-
-/**
- * Shared default storage key. Matches what `next-themes` uses, so any user
- * who already has a saved preference keeps it across the migration.
- */
-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). */
-  systemTheme: ResolvedTheme;
-  setTheme: (theme: Theme) => void;
-  themes: readonly Theme[];
-}
-
-const ThemeContext = createContext<ThemeContextValue | null>(null);
-
-/**
- * Read the active theme state. Safe to call outside a provider — returns
- * a sane default in that case so consumers don't need to null-check.
- */
-export function useTheme(): ThemeContextValue {
-  const ctx = useContext(ThemeContext);
-  if (ctx) return ctx;
-  return {
-    isProviderBound: false,
-    theme: "system",
-    forcedTheme: undefined,
-    resolvedTheme: "light",
-    systemTheme: "light",
-    setTheme: () => {
-      // no-op outside provider
-    },
-    themes: THEMES,
-  };
-}
-
-function resolveSystemTheme(): ResolvedTheme {
-  if (typeof window === "undefined") return "light";
-  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-}
-
-function readStoredTheme(storageKey: string, fallback: Theme): Theme {
-  if (typeof window === "undefined") return fallback;
-  try {
-    const v = window.localStorage.getItem(storageKey);
-    if (v === "light" || v === "dark" || v === "system") return v;
-  } catch {
-    // localStorage may be disabled (Safari private mode, etc.)
-  }
-  return fallback;
-}
-
-/** 1 year — long-lived because theme is a deliberate user choice. */
-const THEME_COOKIE_MAX_AGE = 365 * 24 * 60 * 60;
-
-/**
- * Mirror the resolved theme into a cookie so the next request can be
- * server-rendered with the correct `<html>` class — eliminating the
- * need for an inline FOUC-prevention `<script>` (which React 19 warns
- * about). The cookie value is always concrete ("light" | "dark"), never
- * "system" — Server Components shouldn't try to guess the OS preference.
- */
-function writeThemeCookie(resolved: ResolvedTheme, cookieName: string) {
-  if (typeof document === "undefined") return;
-  document.cookie = `${cookieName}=${resolved}; Max-Age=${THEME_COOKIE_MAX_AGE}; Path=/; SameSite=Lax`;
-}
-
-function applyThemeToDom(
-  resolved: ResolvedTheme,
-  attribute: "class" | "data-theme",
-  disableTransitionOnChange: boolean,
-  nonce?: string,
-) {
-  if (typeof document === "undefined") return;
-  const root = document.documentElement;
-
-  // 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}",
-      ),
-    );
-    document.head.appendChild(suppressor);
-    // Force a reflow so the rule applies before we swap classes
-    void window.getComputedStyle(suppressor).opacity;
-    // Remove the rule on the next tick; transitions resume afterwards
-    setTimeout(() => {
-      if (suppressor.parentNode) suppressor.parentNode.removeChild(suppressor);
-    }, 1);
-  }
-
-  if (attribute === "class") {
-    root.classList.remove("light", "dark");
-    root.classList.add(resolved);
-  } else {
-    root.setAttribute("data-theme", resolved);
-  }
-}
-
-export interface ThemeProviderProps {
-  children: ReactNode;
-  /** Which DOM attribute to set on `<html>`. Default: `"class"`. */
-  attribute?: "class" | "data-theme";
-  /** Default theme when no preference is stored. Default: `"system"`. */
-  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. */
-  storageKey?: string;
-  /** CSP nonce — accepted for API compatibility, currently unused by client logic. */
-  nonce?: string;
-}
-
-export function ThemeProvider({
-  children,
-  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 =
-    effectiveTheme === "system" ? (enableSystem ? systemTheme : "light") : effectiveTheme;
-
-  const setTheme = useCallback(
-    (next: Theme) => {
-      if (forcedTheme !== undefined) return;
-      setThemeState(next);
-      try {
-        if (next === "system") {
-          window.localStorage.removeItem(storageKey);
-        } else {
-          window.localStorage.setItem(storageKey, next);
-        }
-      } catch {
-        // localStorage may be disabled — accept the loss
-      }
-    },
-    [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, nonce);
-    writeThemeCookie(resolvedTheme, storageKey);
-  }, [resolvedTheme, attribute, disableTransitionOnChange, nonce, storageKey]);
-
-  // Follow OS preference changes when in `system` mode
-  useEffect(() => {
-    if (!enableSystem) return;
-    const mq = window.matchMedia("(prefers-color-scheme: dark)");
-    const handler = (event: MediaQueryListEvent) =>
-      setSystemTheme(event.matches ? "dark" : "light");
-    mq.addEventListener("change", handler);
-    return () => mq.removeEventListener("change", handler);
-  }, [enableSystem]);
-
-  // Sync across tabs / windows
-  useEffect(() => {
-    const handler = (event: StorageEvent) => {
-      if (event.key !== storageKey) return;
-      const next = event.newValue;
-      if (next === "light" || next === "dark" || next === "system") {
-        setThemeState(next);
-      } else if (next === null) {
-        setThemeState(defaultTheme);
-      }
-    };
-    window.addEventListener("storage", handler);
-    return () => window.removeEventListener("storage", handler);
-  }, [storageKey, defaultTheme]);
-
-  const value = useMemo<ThemeContextValue>(
-    () => ({
-      isProviderBound: true,
-      theme,
-      forcedTheme,
-      resolvedTheme,
-      systemTheme,
-      setTheme,
-      themes: THEMES,
-    }),
-    [theme, forcedTheme, resolvedTheme, systemTheme, setTheme],
-  );
-
-  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
-}

package/tsconfig.json

@@ -1,11 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "declaration": true,
-    "declarationMap": true,
-    "outDir": "dist",
-    "rootDir": "src",
-    "jsx": "react-jsx"
-  },
-  "include": ["src/**/*.ts", "src/**/*.tsx"]
-}

package/turbo.json

@@ -1,15 +0,0 @@
-{
-  "extends": ["//"],
-  "tasks": {
-    "build": {
-      "dependsOn": ["@nebutra/design-tokens#build"],
-      "inputs": [
-        "$TURBO_EXTENDS$",
-        "../design-tokens/build/css/styles.generated.css",
-        "brands/**",
-        "scripts/**"
-      ],
-      "outputs": ["styles.css", "skins/**"]
-    }
-  }
-}