@motion-proto/live-tokens 0.1.0 → 0.3.1

package/src/lib/themeService.ts

@@ -0,0 +1,101 @@
+import { tick } from 'svelte';
+import type { Theme, ThemeMeta } from './themeTypes';
+import type { EditorState } from './editorTypes';
+import {
+  versionedFileResource,
+  sanitizeFileName as sanitizeFileNameImpl,
+} from './files/versionedFileResource';
+import { loadFromFile as loadEditorState, toTheme, markSaved } from './editorStore';
+import { activeFileName } from './editorConfigStore';
+import { applyFontSources, applyFontStacks } from './fontLoader';
+import { migrateThemeFonts } from './fontMigration';
+
+// ── API helpers ──────────────────────────────────────────────
+//
+// All theme CRUD goes through `versionedFileResource('/api/themes')` —
+// shared with `componentConfigService`'s per-component clients. Theme-specific
+// response shapes (ThemeMeta list payload, ProductionInfo) are layered on top
+// via the generic type parameters.
+
+export interface ProductionInfo {
+  fileName: string;
+  name: string;
+  updatedAt: string;
+  cssVariables: Record<string, string>;
+}
+
+const themeResource = versionedFileResource<Theme, ThemeMeta, ProductionInfo>({
+  baseUrl: '/api/themes',
+});
+
+export async function listThemes(): Promise<ThemeMeta[]> {
+  const data = await themeResource.list();
+  return data.files;
+}
+
+export const loadTheme = (fileName: string): Promise<Theme> => themeResource.load(fileName);
+export const saveTheme = (fileName: string, data: Theme): Promise<void> =>
+  themeResource.save(fileName, data);
+export const deleteTheme = (fileName: string): Promise<void> => themeResource.remove(fileName);
+
+export async function getActiveTheme(): Promise<Theme | null> {
+  return themeResource.getActive();
+}
+
+export const setActiveFile = (fileName: string): Promise<void> => themeResource.setActive(fileName);
+
+// ── Production API helpers ─────────────────────────────────
+
+export const getProductionInfo = (): Promise<ProductionInfo> => themeResource.getProductionInfo();
+
+export async function setProductionFile(
+  fileName: string,
+): Promise<{ ok: boolean; fileName: string; name: string }> {
+  const data = await themeResource.setProduction(fileName);
+  return { ok: data.ok, fileName: data.fileName, name: data.name };
+}
+
+/** Sanitize a display name to a safe file name. Re-exported from the shared
+ * `files/versionedFileResource` so the dev-server plugin can import the
+ * canonical pure helper without depending on this module's CSS imports. */
+export const sanitizeFileName = sanitizeFileNameImpl;
+
+// ── Theme save/load orchestration ──────────────────────────
+//
+// `persistTheme` and `hydrateTheme` are the canonical entry points for
+// round-tripping editor state to disk. Callers (e.g. `EditorShell`) need
+// only handle UI-level concerns (status flashing, error chrome) and
+// delegate the actual orchestration here.
+
+/** Snapshot the editor state to disk under `fileName`, mark the file active,
+ *  and clear the dirty flag. The caller is responsible for surfacing
+ *  saving / saved / error UI states around this call. */
+export async function persistTheme(
+  state: EditorState,
+  fileName: string,
+  displayName: string,
+): Promise<void> {
+  await tick();
+  const theme = toTheme(state, { name: displayName });
+  await saveTheme(fileName, theme);
+  await setActiveFile(fileName);
+  activeFileName.set(fileName);
+  markSaved();
+}
+
+/** Load a theme file into the editor state and re-apply font side-effects
+ *  (@font-face rules + `--font-*` CSS vars on :root). */
+export async function hydrateTheme(fileName: string): Promise<void> {
+  const theme = await loadTheme(fileName);
+  migrateThemeFonts(theme);
+  loadEditorState(theme);
+  // Font data is in state.fonts via loadEditorState; the DOM-side-effect
+  // helpers still need to run so @font-face rules and --font-* CSS vars
+  // land on :root.
+  if (theme.fontSources && theme.fontSources.length > 0) {
+    applyFontSources(theme.fontSources);
+  }
+  if (theme.fontStacks && theme.fontStacks.length > 0) {
+    applyFontStacks(theme.fontStacks, theme.fontSources ?? []);
+  }
+}

package/src/lib/themeTypes.ts

@@ -0,0 +1,146 @@
+import type { CurveAnchor } from '../ui/curveEngine';
+
+export type GradientStyle = 'linear' | 'radial' | 'conic';
+
+export interface GradientStop {
+  position: number;
+  paletteLabel: string;
+}
+
+export interface PaletteConfig {
+  baseColor: string;
+  tintHue: number;
+  tintChroma?: number;
+  lightnessCurve: CurveAnchor[];
+  saturationCurve: CurveAnchor[];
+  grayLightnessCurve: CurveAnchor[];
+  graySaturationCurve: CurveAnchor[];
+  scaleCurves: Record<string, { lightness: CurveAnchor[]; saturation: CurveAnchor[] }>;
+  curveOffset: Record<string, number>;
+  overrides: Record<string, string>;
+  snappedScales: string[];
+  emptyMode?: 'solid' | 'gradient';
+  emptyStep?: string;
+  gradientStyle?: GradientStyle;
+  gradientAngle?: number;
+  gradientReverse?: boolean;
+  gradientStops?: GradientStop[];
+  gradientSize?: 'page' | 'window';
+  anchorToBase?: boolean;
+}
+
+export type FontSourceKind = 'google' | 'typekit' | 'css-url' | 'font-face';
+
+export interface FontFamily {
+  id: string;
+  name: string;
+  cssName: string;
+  weights?: number[];
+  italics?: boolean;
+}
+
+export interface FontSource {
+  id: string;
+  kind: FontSourceKind;
+  url?: string;
+  cssText?: string;
+  families: FontFamily[];
+  label?: string;
+}
+
+export type SystemCascadePreset = 'system-ui-sans' | 'system-ui-serif' | 'system-ui-mono';
+export type GenericFamily = 'sans-serif' | 'serif' | 'monospace' | 'cursive' | 'fantasy';
+export type FontStackVariable = '--font-display' | '--font-sans' | '--font-serif' | '--font-mono';
+
+export type FontStackSlot =
+  | { kind: 'project'; familyId: string }
+  | { kind: 'system'; preset: SystemCascadePreset }
+  | { kind: 'generic'; value: GenericFamily };
+
+export interface FontStack {
+  variable: FontStackVariable;
+  slots: FontStackSlot[];
+}
+
+export interface Theme {
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  editorConfigs: Record<string, PaletteConfig>;
+  cssVariables: Record<string, string>;
+  fontSources?: FontSource[];
+  fontStacks?: FontStack[];
+  /**
+   * Server-attached file-name marker for round-tripping the file identity
+   * back to the client. Set by `themeFileApi`'s GET handlers; read by
+   * `themeInit` to seed `activeFileName`. Optional and not persisted to disk.
+   */
+  _fileName?: string;
+  /**
+   * Migration stamp. Absent on legacy files, treated as 0; the loader runs
+   * any registered theme migrations whose `fromVersion >= file.schemaVersion`.
+   * Save paths stamp the current value so resaved files skip past
+   * migrations.
+   */
+  schemaVersion?: number;
+}
+
+export interface ThemeMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+}
+
+export interface ComponentConfig {
+  name: string;
+  component: string;
+  createdAt: string;
+  updatedAt: string;
+  aliases: Record<string, string>;
+  config?: Record<string, unknown>;
+  /**
+   * Server-attached file-name marker. Same role as `Theme._fileName`. Set by
+   * the component-configs GET handlers; not persisted to disk.
+   */
+  _fileName?: string;
+  /**
+   * Migration stamp. Absent on legacy files, treated as 0. See `Theme.schemaVersion`.
+   */
+  schemaVersion?: number;
+}
+
+export interface ComponentConfigMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+  isProduction: boolean;
+}
+
+/**
+ * Manifest that captures an entire site state — the active theme plus the
+ * active config for every component. Loading a preset flips the relevant
+ * `_active.json` pointers; the underlying theme + component-config files stay
+ * the source of truth, so editing them flows through any preset that
+ * references them.
+ */
+export interface Preset {
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  /** File basename (no `.json`) of the theme this preset pins. */
+  theme: string;
+  /** Map of componentId → config file basename. Components omitted here fall
+   *  back to "default" at apply time. */
+  componentConfigs: Record<string, string>;
+  /** Server-attached file-name marker. Same role as `Theme._fileName`. */
+  _fileName?: string;
+}
+
+export interface PresetMeta {
+  name: string;
+  fileName: string;
+  updatedAt: string;
+  isActive: boolean;
+}

package/src/lib/tokenRegistry.ts

@@ -0,0 +1,148 @@
+/**
+ * Static registry of CSS custom-property declarations.
+ *
+ * Layer-1 design tokens live in tokens.css (the single source of truth for
+ * shared primitives). Layer-2 component tokens live inside each component's
+ * `<style>` block as `:global(:root) { ... }` declarations — owned by the
+ * component that uses them.
+ *
+ * Token-picking UIs need to recover the semantic identity of an arbitrary
+ * variable — e.g. to display "info text / primary" rather than a raw hex. For
+ * alias variables we must follow the `var(--x)` chain from the declaration to
+ * find the underlying token whose *name* the selector can parse.
+ *
+ * This module parses both sources at import time (tokens.css via Vite's
+ * ?raw loader, component files via import.meta.glob) and exposes helpers that
+ * walk those aliases. The pure `buildTokenRegistry` and `extractGlobalRootBody`
+ * helpers are also exported so tests can construct a registry from fs-loaded
+ * files (Vitest's default CSS plugin swallows `?raw` imports for .css files).
+ */
+
+import { derived, type Readable } from 'svelte/store';
+import tokensCss from '../styles/tokens.css?raw';
+import { editorState } from './editorStore';
+import type { EditorState } from './editorTypes';
+import { extractGlobalRootBody } from './parsers/globalRootBlock';
+
+// Re-exported for tests and downstream consumers that previously imported it
+// from this module. The canonical implementation lives in `./parsers/globalRootBlock`
+// so the dev-server vite plugin can share it.
+export { extractGlobalRootBody };
+
+const componentSources = import.meta.glob('../components/*.svelte', {
+  query: '?raw',
+  import: 'default',
+  eager: true,
+}) as Record<string, string>;
+
+export interface TokenRegistry {
+  getDeclaredValue(varName: string): string | null;
+  resolveAliasChain(varName: string): string[];
+}
+
+/**
+ * Pure constructor: parses a CSS source string (possibly concatenated from
+ * multiple files) and returns a registry bound to that snapshot.
+ */
+export function buildTokenRegistry(cssText: string): TokenRegistry {
+  const declarations = new Map<string, string>();
+  const re = /(--[a-z0-9-]+)\s*:\s*([^;]+);/gi;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(cssText)) !== null) {
+    declarations.set(m[1], m[2].trim());
+  }
+
+  function resolveAliasChain(varName: string): string[] {
+    const chain = [varName];
+    const visited = new Set<string>([varName]);
+    let current = varName;
+    while (true) {
+      const decl = declarations.get(current);
+      if (!decl) return chain;
+      const aliasMatch = decl.match(/var\((--[a-z0-9-]+)\)/i);
+      if (!aliasMatch) return chain;
+      const next = aliasMatch[1];
+      if (visited.has(next)) return chain;
+      visited.add(next);
+      chain.push(next);
+      current = next;
+    }
+  }
+
+  return {
+    getDeclaredValue: (v) => declarations.get(v) ?? null,
+    resolveAliasChain,
+  };
+}
+
+const componentTokenCss = Object.values(componentSources)
+  .map(extractGlobalRootBody)
+  .join('\n');
+
+const defaultRegistry = buildTokenRegistry(tokensCss + '\n' + componentTokenCss);
+
+/** Raw declared value from tokens.css, or null if not declared. */
+export const getDeclaredValue = defaultRegistry.getDeclaredValue;
+
+/**
+ * Walk the alias chain starting at `varName`, returning each successive
+ * variable reference (including the starting one). Stops when a declaration is
+ * a literal value (e.g. hex) or when the next link is absent from the
+ * registry. Guards against cycles.
+ *
+ * Example: `--notification-info-title` → `--text-info` → stops (literal hex).
+ * Returns `['--notification-info-title', '--text-info']`.
+ *
+ * This is a static snapshot: it only sees declarations from tokens.css + the
+ * baked-in `:global(:root)` blocks at module load. For state-aware resolution
+ * that includes live component-alias edits, subscribe to `tokenRegistry$`.
+ */
+export const resolveAliasChain = defaultRegistry.resolveAliasChain;
+
+/**
+ * Build a registry that layers live component-alias overrides on top of the
+ * static base. Cheap enough to rebuild per editorState tick — components
+ * count is small and the alias walk is lazy.
+ */
+function buildOverlayRegistry(
+  base: TokenRegistry,
+  components: EditorState['components'],
+): TokenRegistry {
+  const overrides = new Map<string, string>();
+  for (const slice of Object.values(components)) {
+    for (const [varName, ref] of Object.entries(slice.aliases)) {
+      overrides.set(varName, ref.kind === 'token' ? `var(${ref.name})` : ref.value);
+    }
+  }
+  const getDeclared = (v: string): string | null =>
+    overrides.has(v) ? overrides.get(v)! : base.getDeclaredValue(v);
+  return {
+    getDeclaredValue: getDeclared,
+    resolveAliasChain(varName: string): string[] {
+      const chain = [varName];
+      const visited = new Set<string>([varName]);
+      let current = varName;
+      while (true) {
+        const decl = getDeclared(current);
+        if (!decl) return chain;
+        const aliasMatch = decl.match(/var\((--[a-z0-9-]+)\)/i);
+        if (!aliasMatch) return chain;
+        const next = aliasMatch[1];
+        if (visited.has(next)) return chain;
+        visited.add(next);
+        chain.push(next);
+        current = next;
+      }
+    },
+  };
+}
+
+/**
+ * State-aware token registry: overlays live `state.components[*].aliases`
+ * on top of the static base registry. Consume with `$tokenRegistry$` in
+ * Svelte components when the UI needs to reflect in-flight alias edits
+ * (e.g. selectors displaying the currently-selected semantic token).
+ */
+export const tokenRegistry$: Readable<TokenRegistry> = derived(editorState, ($state) =>
+  buildOverlayRegistry(defaultRegistry, $state.components),
+);