@motion-proto/live-tokens 0.1.1 → 0.3.2

package/src/lib/columnsOverlay.ts

@@ -1,26 +1,30 @@
 import { writable } from 'svelte/store';
 import { storageKey } from './editorConfig';
+import { quietGet, quietSet } from './storage';
 
-const STORAGE_KEY = storageKey('columns-visible');
-
-function load(): boolean {
-  try {
-    return localStorage.getItem(STORAGE_KEY) === '1';
-  } catch {
-    return false;
-  }
+function getStorageKey(): string {
+  return storageKey('columns-visible');
 }
 
-export const columnsVisible = writable<boolean>(load());
-
-columnsVisible.subscribe((v) => {
-  try {
-    localStorage.setItem(STORAGE_KEY, v ? '1' : '0');
-  } catch {
-    // ignore quota errors
-  }
-});
+export const columnsVisible = writable<boolean>(false);
 
 export function toggleColumns() {
   columnsVisible.update((v) => !v);
 }
+
+let initialised = false;
+
+/**
+ * Idempotent host hook — call once during boot to hydrate the column-visibility
+ * store from localStorage and start persisting future writes. Importing the
+ * module no longer subscribes-then-persists, so SSR / test harnesses can pull
+ * `columnsVisible` without DOM/storage access.
+ */
+export function init(): void {
+  if (initialised) return;
+  initialised = true;
+  columnsVisible.set(quietGet(getStorageKey()) === '1');
+  columnsVisible.subscribe((v) => {
+    quietSet(getStorageKey(), v ? '1' : '0');
+  });
+}

package/src/lib/componentConfig.test.ts

@@ -0,0 +1,204 @@
+// @vitest-environment happy-dom
+import { beforeEach, describe, expect, it } from 'vitest';
+import { get } from 'svelte/store';
+import {
+  editorState,
+  componentDirty,
+  setComponentAlias,
+  clearComponentAlias,
+  setComponentConfig,
+  clearComponentConfig,
+  loadComponentActive,
+  markComponentSaved,
+  seedComponentsFromApi,
+  undo,
+  redo,
+  __resetForTests,
+} from './editorStore';
+
+const tokenRef = (name: string) => ({ kind: 'token' as const, name });
+
+beforeEach(() => {
+  __resetForTests();
+});
+
+describe('component aliases — editor-state round trip', () => {
+  it('setComponentAlias → undo restores previous state; redo reapplies', () => {
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-success-high'));
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-error-high'));
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-error-high'));
+
+    undo();
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+
+    redo();
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-error-high'));
+  });
+
+  it('clearComponentAlias removes the entry and is undoable', () => {
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-success-high'));
+    clearComponentAlias('button', '--button-primary-surface');
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toBeUndefined();
+
+    undo();
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+  });
+
+  it('setComponentAlias implicitly registers the slice with activeFile "default"', () => {
+    setComponentAlias('card', '--card-radius', tokenRef('--radius-lg'));
+    expect(get(editorState).components.card.activeFile).toBe('default');
+    expect(get(editorState).components.card.aliases['--card-radius']).toEqual(tokenRef('--radius-lg'));
+    expect(get(editorState).components.card.config).toEqual({});
+  });
+});
+
+describe('component config — literal-valued knobs', () => {
+  it('setComponentConfig stores the value and is undoable', () => {
+    setComponentConfig('dialog', '--dialog-confirm-variant', 'danger');
+    expect(get(editorState).components.dialog.config['--dialog-confirm-variant']).toBe('danger');
+
+    setComponentConfig('dialog', '--dialog-confirm-variant', 'warning');
+    expect(get(editorState).components.dialog.config['--dialog-confirm-variant']).toBe('warning');
+
+    undo();
+    expect(get(editorState).components.dialog.config['--dialog-confirm-variant']).toBe('danger');
+  });
+
+  it('clearComponentConfig removes the entry', () => {
+    setComponentConfig('dialog', '--dialog-confirm-variant', 'danger');
+    clearComponentConfig('dialog', '--dialog-confirm-variant');
+    expect(get(editorState).components.dialog.config['--dialog-confirm-variant']).toBeUndefined();
+  });
+
+  it('setComponentConfig implicitly registers the slice with empty aliases', () => {
+    setComponentConfig('dialog', '--dialog-cancel-variant', 'outline');
+    expect(get(editorState).components.dialog.activeFile).toBe('default');
+    expect(get(editorState).components.dialog.aliases).toEqual({});
+    expect(get(editorState).components.dialog.config['--dialog-cancel-variant']).toBe('outline');
+  });
+});
+
+describe('componentDirty — per-component scoping', () => {
+  it('marks a component dirty only after its aliases diverge from the saved baseline', () => {
+    loadComponentActive('button', 'default', { '--button-primary-surface': '--surface-success-high' });
+    expect(get(componentDirty).button).toBe(false);
+
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-error-high'));
+    expect(get(componentDirty).button).toBe(true);
+
+    markComponentSaved('button');
+    expect(get(componentDirty).button).toBe(false);
+  });
+
+  it('marks a component dirty when config diverges from the saved baseline', () => {
+    loadComponentActive('dialog', 'default', {}, { '--dialog-confirm-variant': 'primary' });
+    expect(get(componentDirty).dialog).toBe(false);
+
+    setComponentConfig('dialog', '--dialog-confirm-variant', 'danger');
+    expect(get(componentDirty).dialog).toBe(true);
+
+    markComponentSaved('dialog');
+    expect(get(componentDirty).dialog).toBe(false);
+  });
+
+  it('editing one component does not dirty another', () => {
+    loadComponentActive('button', 'default', { '--button-primary-surface': '--surface-success-high' });
+    loadComponentActive('card', 'default', { '--card-radius': '--radius-md' });
+    expect(get(componentDirty).button).toBe(false);
+    expect(get(componentDirty).card).toBe(false);
+
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-error-high'));
+    expect(get(componentDirty).button).toBe(true);
+    expect(get(componentDirty).card).toBe(false);
+  });
+
+  it('undo after a saved state marks dirty again', () => {
+    loadComponentActive('button', 'default', { '--button-primary-surface': '--surface-success-high' });
+    setComponentAlias('button', '--button-primary-surface', tokenRef('--surface-error-high'));
+    markComponentSaved('button');
+    expect(get(componentDirty).button).toBe(false);
+
+    undo();
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+    expect(get(componentDirty).button).toBe(true);
+  });
+});
+
+describe('loadComponentActive — split-on-load migration', () => {
+  it('routes legacy config keys from single-bucket aliases into the config bucket', () => {
+    loadComponentActive('dialog', 'default', {
+      '--dialog-surface': '--surface-neutral-low',
+      '--dialog-confirm-variant': 'danger',
+    });
+    const slice = get(editorState).components.dialog;
+    expect(slice.aliases['--dialog-surface']).toEqual(tokenRef('--surface-neutral-low'));
+    expect(slice.aliases['--dialog-confirm-variant']).toBeUndefined();
+    expect(slice.config['--dialog-confirm-variant']).toBe('danger');
+  });
+
+  it('keeps CSS-var-valued aliases (e.g. --button-shimmer → --shimmer-on) in the aliases bucket', () => {
+    loadComponentActive('button', 'default', {
+      '--button-primary-surface': '--surface-success-high',
+      '--button-shimmer': '--shimmer-on',
+    });
+    const slice = get(editorState).components.button;
+    expect(slice.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+    expect(slice.aliases['--button-shimmer']).toEqual(tokenRef('--shimmer-on'));
+    expect(slice.config['--button-shimmer']).toBeUndefined();
+  });
+
+  it('classifies literal alias values as kind "literal"', () => {
+    loadComponentActive('myComp', 'default', {
+      '--my-comp-token': '--some-token',
+      '--my-comp-color': 'rebeccapurple',
+    });
+    const slice = get(editorState).components.myComp;
+    expect(slice.aliases['--my-comp-token']).toEqual(tokenRef('--some-token'));
+    expect(slice.aliases['--my-comp-color']).toEqual({ kind: 'literal', value: 'rebeccapurple' });
+  });
+
+  it('explicit config field wins over legacy alias-bucketed value', () => {
+    loadComponentActive(
+      'dialog',
+      'default',
+      { '--dialog-confirm-variant': 'primary' },
+      { '--dialog-confirm-variant': 'danger' },
+    );
+    expect(get(editorState).components.dialog.config['--dialog-confirm-variant']).toBe('danger');
+  });
+});
+
+describe('seedComponentsFromApi — boot-time hydration', () => {
+  it('populates state and establishes the clean baseline', () => {
+    seedComponentsFromApi({
+      button: { activeFile: 'myConfig', aliases: { '--button-primary-surface': '--surface-success-high' } },
+    });
+    expect(get(editorState).components.button.activeFile).toBe('myConfig');
+    expect(get(editorState).components.button.aliases['--button-primary-surface']).toEqual(tokenRef('--surface-success-high'));
+    expect(get(componentDirty).button).toBe(false);
+  });
+
+  it('routes config keys when seeding from legacy single-bucket API payload', () => {
+    seedComponentsFromApi({
+      dialog: {
+        activeFile: 'default',
+        aliases: { '--dialog-confirm-variant': 'danger', '--dialog-shadow': '--shadow-2xl' },
+      },
+    });
+    const slice = get(editorState).components.dialog;
+    expect(slice.aliases['--dialog-shadow']).toEqual(tokenRef('--shadow-2xl'));
+    expect(slice.aliases['--dialog-confirm-variant']).toBeUndefined();
+    expect(slice.config['--dialog-confirm-variant']).toBe('danger');
+  });
+
+  it('replaces the full components slice', () => {
+    setComponentAlias('card', '--card-radius', tokenRef('--radius-md'));
+    seedComponentsFromApi({
+      button: { activeFile: 'default', aliases: {} },
+    });
+    expect(get(editorState).components.card).toBeUndefined();
+    expect(get(editorState).components.button).toBeDefined();
+  });
+});

package/src/lib/componentConfigKeys.ts

@@ -0,0 +1,19 @@
+// TODO(M3 schemaVersion / Wave 4): replace this enumerated list with a
+// per-component schema declaration (e.g. registerComponentSchema(...,
+// { kind: 'config' })). For now it's a flat set used by the on-load
+// migration that splits legacy single-bucket aliases into the new
+// {aliases, config} shape.
+//
+// What goes here: literal-valued knobs that don't translate to CSS vars
+// (e.g. Dialog's confirm/cancel variant string is consumed by Dialog.svelte
+// via `$editorState`, not via CSS cascade).
+//
+// What does NOT go here: aliases whose values are themselves CSS-var refs
+// — even if the value space is constrained (e.g. `--button-shimmer` →
+// `--shimmer-on` | `--shimmer-off`). Those are still aliases and must flow
+// through `componentsToVars` so SCSS that does `var(--button-shimmer)`
+// keeps resolving.
+export const KNOWN_COMPONENT_CONFIG_KEYS: ReadonlySet<string> = new Set([
+  '--dialog-confirm-variant',
+  '--dialog-cancel-variant',
+]);

package/src/lib/componentConfigService.ts

@@ -0,0 +1,88 @@
+import type { ComponentConfig, ComponentConfigMeta } from './themeTypes';
+import { versionedFileResource } from './files/versionedFileResource';
+
+/**
+ * REST client for per-component config files. Parallel to `themeService.ts`
+ * but scoped to `/api/component-configs/*`. Each component (button, card, …)
+ * has its own lifecycle: default.json (generated from the `.svelte` source),
+ * plus user-authored named configs, each with its own active / production
+ * pointer.
+ *
+ * Both this and `themeService` consume `versionedFileResource(...)`. Adding a
+ * third file-managed resource — per the user's "mirror theme-file lifecycle
+ * for new editor artifacts" invariant — is one helper call here, not a third
+ * round of copy-paste CRUD.
+ */
+
+export interface ComponentSummary {
+  name: string;
+  activeFile: string;
+  productionFile: string;
+}
+
+export interface ComponentProductionInfo {
+  fileName: string;
+  name: string;
+  aliases: Record<string, string>;
+}
+
+export interface ComponentConfigList {
+  component: string;
+  files: ComponentConfigMeta[];
+  activeFile: string;
+  productionFile: string;
+}
+
+export async function listComponents(): Promise<ComponentSummary[]> {
+  const res = await fetch('/api/component-configs');
+  if (!res.ok) throw new Error('Failed to list components');
+  const data = await res.json();
+  return data.components;
+}
+
+function resourceFor(component: string) {
+  return versionedFileResource<ComponentConfig, ComponentConfigMeta, ComponentProductionInfo>({
+    baseUrl: `/api/component-configs/${encodeURIComponent(component)}`,
+  });
+}
+
+export async function listComponentConfigs(component: string): Promise<ComponentConfigList> {
+  const data = await resourceFor(component).list();
+  return {
+    component,
+    files: data.files,
+    activeFile: data.activeFile ?? 'default',
+    productionFile: data.productionFile ?? 'default',
+  };
+}
+
+export const loadComponentConfig = (
+  component: string,
+  fileName: string,
+): Promise<ComponentConfig> => resourceFor(component).load(fileName);
+
+export const saveComponentConfig = (
+  component: string,
+  fileName: string,
+  data: ComponentConfig,
+): Promise<void> => resourceFor(component).save(fileName, data);
+
+export const deleteComponentConfig = (component: string, fileName: string): Promise<void> =>
+  resourceFor(component).remove(fileName);
+
+export const getActiveComponentConfig = (component: string): Promise<ComponentConfig | null> =>
+  resourceFor(component).getActive();
+
+export const setActiveComponentFile = (component: string, fileName: string): Promise<void> =>
+  resourceFor(component).setActive(fileName);
+
+export const getComponentProductionInfo = (component: string): Promise<ComponentProductionInfo> =>
+  resourceFor(component).getProductionInfo();
+
+export async function setComponentProductionFile(
+  component: string,
+  fileName: string,
+): Promise<{ ok: boolean; productionFile: string }> {
+  const data = await resourceFor(component).setProduction(fileName);
+  return { ok: data.ok, productionFile: data.fileName };
+}

package/src/lib/copyPopover.ts

@@ -0,0 +1,30 @@
+import { writable } from 'svelte/store';
+
+export type CopyPopoverState = {
+  visible: boolean;
+  value: string;
+  /** Viewport-relative anchor rect for the trigger element. */
+  anchor: { top: number; left: number; width: number; height: number } | null;
+  /** Monotonic id so consecutive copies of the same value re-trigger the timer. */
+  nonce: number;
+};
+
+const initial: CopyPopoverState = { visible: false, value: '', anchor: null, nonce: 0 };
+
+export const copyPopover = writable<CopyPopoverState>(initial);
+
+let hideTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function showCopyPopover(value: string, target: EventTarget | null, durationMs = 1500) {
+  const el = target instanceof Element ? target : null;
+  const rect = el?.getBoundingClientRect() ?? null;
+  const anchor = rect ? { top: rect.top, left: rect.left, width: rect.width, height: rect.height } : null;
+
+  copyPopover.update((s) => ({ visible: true, value, anchor, nonce: s.nonce + 1 }));
+
+  if (hideTimer) clearTimeout(hideTimer);
+  hideTimer = setTimeout(() => {
+    copyPopover.update((s) => ({ ...s, visible: false }));
+    hideTimer = null;
+  }, durationMs);
+}

package/src/lib/cssVarSync.ts

@@ -4,14 +4,24 @@
  * Writes to document.documentElement and — when running inside a same-origin
  * iframe (the live-preview overlay) — also writes to
  * window.parent.document.documentElement. This lets the overlay editor at
- * /admin drive the host site's :root in real time without any message-passing
+ * /editor drive the host site's :root in real time without any message-passing
  * infrastructure.
  *
- * When the editor runs standalone at /admin (not inside the overlay iframe),
+ * When the editor runs standalone at /editor (not inside the overlay iframe),
  * parentRoot is null and every call is a plain single-root write.
+ *
+ * Roots are resolved lazily — `init()` (or any setter call) populates them on
+ * first use so importing this module does not touch the DOM. This keeps the
+ * library importable from SSR / test harnesses and decouples consumers from
+ * module-load ordering.
  */
 
+let selfRoot: HTMLElement | null = null;
+let parentRoot: HTMLElement | null = null;
+let resolved = false;
+
 function resolveParentRoot(): HTMLElement | null {
+  if (typeof window === 'undefined') return null;
   try {
     if (window.parent !== window && window.parent?.document) {
       return window.parent.document.documentElement;
@@ -22,17 +32,56 @@ function resolveParentRoot(): HTMLElement | null {
   return null;
 }
 
-const selfRoot: HTMLElement = document.documentElement;
-const parentRoot: HTMLElement | null = resolveParentRoot();
+function ensureResolved(): void {
+  if (resolved) return;
+  resolved = true;
+  selfRoot = typeof document !== 'undefined' ? document.documentElement : null;
+  parentRoot = resolveParentRoot();
+}
+
+/**
+ * Idempotent host hook — call once during boot to eagerly resolve the self
+ * and parent document roots. Optional in practice (any setter call resolves
+ * lazily), but explicit init makes ordering legible.
+ */
+export function init(): void {
+  ensureResolved();
+}
+
+/**
+ * Return the self and parent document heads as a tuple, with parent omitted
+ * when not in an iframe. Consumers that need to mirror node injection (not
+ * just style properties) can iterate this list.
+ */
+export function getSyncedDocuments(): Document[] {
+  ensureResolved();
+  if (typeof document === 'undefined') return [];
+  const docs: Document[] = [document];
+  if (parentRoot && parentRoot.ownerDocument && parentRoot.ownerDocument !== document) {
+    docs.push(parentRoot.ownerDocument);
+  }
+  return docs;
+}
+
+export const CSS_VAR_CHANGE_EVENT = 'cssvar:change';
+
+function notifyChange(name: string): void {
+  if (typeof document === 'undefined') return;
+  document.dispatchEvent(new CustomEvent(CSS_VAR_CHANGE_EVENT, { detail: { name } }));
+}
 
 export function setCssVar(name: string, value: string): void {
-  selfRoot.style.setProperty(name, value);
+  ensureResolved();
+  selfRoot?.style.setProperty(name, value);
   parentRoot?.style.setProperty(name, value);
+  notifyChange(name);
 }
 
 export function removeCssVar(name: string): void {
-  selfRoot.style.removeProperty(name);
+  ensureResolved();
+  selfRoot?.style.removeProperty(name);
   parentRoot?.style.removeProperty(name);
+  notifyChange(name);
 }
 
 /** Apply a map of CSS variables to :root (and the parent :root when in an iframe). */
@@ -44,7 +93,8 @@ export function applyCssVariables(variables: Record<string, string>): void {
 
 /** Remove all inline CSS custom properties from :root on both self and parent. */
 export function clearAllCssVarOverrides(): void {
-  clearRoot(selfRoot);
+  ensureResolved();
+  if (selfRoot) clearRoot(selfRoot);
   if (parentRoot) clearRoot(parentRoot);
 }
 
@@ -60,6 +110,8 @@ function clearRoot(el: HTMLElement): void {
 
 /** Scrape all inline CSS custom properties currently on self :root. */
 export function scrapeCssVariables(): Record<string, string> {
+  ensureResolved();
+  if (!selfRoot) return {};
   const style = selfRoot.style;
   const variables: Record<string, string> = {};
   for (let i = 0; i < style.length; i++) {

package/src/lib/editorConfigStore.ts

@@ -1,14 +1,4 @@
 import { writable } from 'svelte/store';
-import type { PaletteConfig } from './tokenTypes';
-
-/** Each PaletteEditor pushes its config here keyed by label. Used when saving. */
-export const editorConfigs = writable<Record<string, PaletteConfig>>({});
-
-/** Set by the load flow. Each PaletteEditor watches for its label and applies the config. */
-export const loadedConfigs = writable<Record<string, PaletteConfig> | null>(null);
-
-/** True when editorConfigs were populated from a token file load or deliberate user edit, not just component defaults. */
-export const configsLoadedFromFile = writable<boolean>(false);
 
 /** The file name of the currently active token file. */
 export const activeFileName = writable<string>('default');