@ccheever/exact-facet-core 0.1.0

package/src/theme-store.ts

@@ -0,0 +1,456 @@
+// @system @ref LLP 0157 §2 — the consolidated Facet theme store.
+//
+// One store, many bindings: the React `FacetThemeProvider` registers a scope
+// per provider instance (preserving today's subtree semantics), a Contract
+// root registers a scope through the theme capability, and the agent
+// endpoints read/write the same process-global inputs. The semantics here
+// are a written contract (LLP 0157 §2) with parity tests — resolution must
+// match the legacy provider exactly:
+//
+//   precedence (highest wins): agent override → scope `overrides`
+//     → scope custom theme → base scheme
+//   animation passes through applyMotionPreference(reduced motion) at
+//     resolution time
+//   the designated default scope publishes the agent snapshot in the
+//     legacy shape `{ scheme, themeName, tokens{7}, updatedAt }`
+//   contrast validation warns when any override is active
+
+import {
+  getThemeOverride,
+  setThemeSnapshot,
+  subscribeThemeOverride,
+} from '@exact/core/agent/experience-registry';
+
+import {
+  applyMotionPreference,
+  deepMerge,
+  resolveSizeClassForWidth,
+  validateFacetContrast,
+  warnFacetOnce,
+  type DeepPartial,
+  type FacetTheme,
+  type Scheme,
+} from './internals.js';
+import {
+  defaultThemeDefinition,
+  resolveFacetTheme,
+  type FacetThemeDefinition,
+} from './theme-definition.js';
+import {
+  createHostInput,
+  createPreferenceStore,
+  type HostInput,
+  type PreferenceStore,
+} from './store-machinery.js';
+import {
+  getAppThemeOverrides,
+  getThemeDefinitionOverrides,
+  subscribeFacetOverrides,
+} from './facet-overrides.js';
+
+export type ThemeSchemePreference = Scheme | 'system';
+
+export interface ThemeScopeConfig {
+  /** Mirrors `FacetThemeProvider`'s `theme` prop: a scheme, 'system', or a full custom theme. */
+  theme?: ThemeSchemePreference | FacetTheme;
+  /** Mirrors `FacetThemeProvider`'s `scheme` prop; used when `theme` is absent. */
+  scheme?: ThemeSchemePreference;
+  /** Deep-partial token overrides, merged above the base theme. */
+  overrides?: DeepPartial<FacetTheme> | null;
+}
+
+export interface ThemeScope {
+  readonly id: number;
+  /** Resolved theme for this scope (cached until an input or config changes). */
+  getTheme(): FacetTheme;
+  subscribe(listener: () => void): () => void;
+  update(config: ThemeScopeConfig): void;
+  dispose(): void;
+  /** Whether this scope currently backs the agent snapshot. */
+  isDefault(): boolean;
+}
+
+interface ScopeRecord {
+  id: number;
+  config: ThemeScopeConfig;
+  listeners: Set<() => void>;
+  cachedTheme: FacetTheme | null;
+  cachedAtVersion: number;
+  disposed: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Process-global inputs (LLP 0157 §2 "Inputs")
+// ---------------------------------------------------------------------------
+
+/** Host-fed system appearance. Bindings feed this from their host signal. */
+const systemAppearanceInput: HostInput<Scheme> = createHostInput<Scheme>('light');
+
+/** Host-fed reduced-motion preference. */
+const reducedMotionInput: HostInput<boolean> = createHostInput<boolean>(false);
+
+/** Host-fed viewport width for LLP 0195 size-class resolution. */
+const viewportWidthInput: HostInput<number> = createHostInput<number>(390);
+
+/**
+ * Process-global scheme preference with injected persistence (used by scopes
+ * that do not pin a theme/scheme locally; the React provider always passes
+ * its props, so this input only matters for preference-driven bindings).
+ */
+const schemePreferenceStore: PreferenceStore<ThemeSchemePreference> = createPreferenceStore({
+  defaultValue: 'system',
+  normalize: (raw) => (raw === 'light' || raw === 'dark' || raw === 'system' ? raw : null),
+});
+
+let globalVersion = 0;
+const scopes = new Map<number, ScopeRecord>();
+const scopeOrder: number[] = [];
+const storeListeners = new Set<() => void>();
+let nextScopeId = 1;
+let agentOverrideSubscription: (() => void) | null = null;
+
+function bumpGlobalVersion(): void {
+  globalVersion += 1;
+  for (const id of scopeOrder) {
+    const record = scopes.get(id);
+    if (!record) {
+      continue;
+    }
+    for (const listener of record.listeners) {
+      listener();
+    }
+  }
+  for (const listener of storeListeners) {
+    listener();
+  }
+  publishDefaultScopeSnapshot();
+}
+
+systemAppearanceInput.subscribe(bumpGlobalVersion);
+reducedMotionInput.subscribe(bumpGlobalVersion);
+viewportWidthInput.subscribe(bumpGlobalVersion);
+schemePreferenceStore.subscribe(bumpGlobalVersion);
+
+function ensureAgentOverrideSubscription(): void {
+  // Design Mode's file-backed overrides (LLP 0158 §6.2) are an input like
+  // the agent registry: a change to either layer bumps the global version.
+  ensureFacetOverridesSubscription();
+  if (agentOverrideSubscription) {
+    return;
+  }
+  // The pre-F0 standalone override registry in @exact/core folds into the
+  // store as an input: POST /agent/theme/override still writes the registry,
+  // and the store reacts to it like any other input.
+  agentOverrideSubscription = subscribeThemeOverride(bumpGlobalVersion);
+}
+
+let facetOverridesSubscription: (() => void) | null = null;
+
+function ensureFacetOverridesSubscription(): void {
+  if (facetOverridesSubscription) {
+    return;
+  }
+  facetOverridesSubscription = subscribeFacetOverrides(bumpGlobalVersion);
+}
+
+export function setThemeSystemAppearance(scheme: Scheme): void {
+  systemAppearanceInput.set(scheme);
+}
+
+export function getThemeSystemAppearance(): Scheme {
+  return systemAppearanceInput.get();
+}
+
+export function setThemeReducedMotion(reducedMotion: boolean): void {
+  reducedMotionInput.set(reducedMotion);
+}
+
+export function getThemeReducedMotion(): boolean {
+  return reducedMotionInput.get();
+}
+
+export function setThemeViewportWidth(width: number): void {
+  viewportWidthInput.set(Number.isFinite(width) ? Math.max(0, width) : 0);
+}
+
+export function getThemeViewportWidth(): number {
+  return viewportWidthInput.get();
+}
+
+export function setThemeSchemePreference(preference: ThemeSchemePreference): void {
+  schemePreferenceStore.set(preference);
+}
+
+export function getThemeSchemePreference(): ThemeSchemePreference {
+  return schemePreferenceStore.get();
+}
+
+export const configureThemePreferencePersistence =
+  schemePreferenceStore.configurePersistence.bind(schemePreferenceStore);
+
+/**
+ * Subscribes to any process-global theme input change (system appearance,
+ * reduced motion, scheme preference, agent override). Bindings use this with
+ * `getThemeStoreVersion` for useSyncExternalStore-style integration.
+ */
+export function subscribeToThemeStore(listener: () => void): () => void {
+  ensureAgentOverrideSubscription();
+  storeListeners.add(listener);
+  return () => {
+    storeListeners.delete(listener);
+  };
+}
+
+export function getThemeStoreVersion(): number {
+  return globalVersion;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution (verbatim semantics from the legacy FacetThemeProvider)
+// ---------------------------------------------------------------------------
+
+export interface ThemeResolutionInputs {
+  /** Overrides the host-fed system appearance for this resolution. */
+  systemAppearance?: Scheme;
+  /** Overrides the host-fed reduced-motion preference for this resolution. */
+  reducedMotion?: boolean;
+  /** Overrides the host-fed viewport width for size-class token resolution. */
+  viewportWidth?: number;
+}
+
+function resolveScopeTheme(config: ThemeScopeConfig, inputs?: ThemeResolutionInputs): {
+  theme: FacetTheme;
+  hasCustomThemeOverride: boolean;
+} {
+  const registryOverride = getThemeOverride();
+  const requestedTheme = config.theme ?? config.scheme ?? schemePreferenceStore.get();
+  const systemAppearance = inputs?.systemAppearance ?? systemAppearanceInput.get();
+  const prefersReducedMotion = inputs?.reducedMotion ?? reducedMotionInput.get();
+  const viewportWidth = inputs?.viewportWidth ?? viewportWidthInput.get();
+
+  // LLP 0269 cascade, lowest → highest: definition → resolved tokens (level 1)
+  // < app token overrides (theme.overrides.ts, level 3) < scope/instance
+  // overrides < agent registry override. A dial edit is broad; a token/instance
+  // override wins locally ("most-specific wins").
+  const definitionOverrides = getThemeDefinitionOverrides();
+  const activeDefinition: FacetThemeDefinition = definitionOverrides
+    ? deepMerge(defaultThemeDefinition, definitionOverrides)
+    : defaultThemeDefinition;
+
+  const baseTheme: FacetTheme =
+    typeof requestedTheme === 'object'
+      // A fully-resolved custom theme passed directly (rare; the React provider
+      // still allows it). Used verbatim as the cascade base.
+      ? requestedTheme
+      : resolveFacetTheme(activeDefinition, {
+          scheme:
+            (requestedTheme === 'system' ? systemAppearance : requestedTheme) === 'dark'
+              ? 'dark'
+              : 'light',
+          reducedMotion: prefersReducedMotion,
+          viewportWidth,
+        });
+
+  const appOverrides = getAppThemeOverrides();
+  const mergedTheme = deepMerge(
+    deepMerge(deepMerge(baseTheme, appOverrides), config.overrides),
+    registryOverride as DeepPartial<FacetTheme> | null | undefined,
+  );
+  const hasCustomThemeOverride =
+    typeof requestedTheme === 'object' ||
+    config.overrides != null ||
+    appOverrides != null ||
+    definitionOverrides != null ||
+    registryOverride != null;
+  const theme: FacetTheme = {
+    ...mergedTheme,
+    sizeClass: resolveSizeClassForWidth(viewportWidth, mergedTheme.sizeClasses),
+    motion: applyMotionPreference(mergedTheme.motion, prefersReducedMotion),
+  };
+
+  return { theme, hasCustomThemeOverride };
+}
+
+function validateScopeContrast(theme: FacetTheme, hasCustomThemeOverride: boolean): void {
+  if (!hasCustomThemeOverride) {
+    return;
+  }
+  const failures = validateFacetContrast(theme);
+  if (failures.length === 0) {
+    return;
+  }
+  warnFacetOnce(`[Facet] Theme override contrast check failed: ${failures.join('; ')}`);
+}
+
+// ---------------------------------------------------------------------------
+// Snapshot publication (default scope only)
+// ---------------------------------------------------------------------------
+
+function defaultScopeRecord(): ScopeRecord | null {
+  // Newest live scope backs the agent snapshot. This matches the legacy
+  // multi-provider outcome at mount (every provider's effect republished
+  // last-write-wins, and React runs parent effects after children, so the
+  // outermost provider won — and it registers last here too).
+  for (let index = scopeOrder.length - 1; index >= 0; index -= 1) {
+    const record = scopes.get(scopeOrder[index]);
+    if (record && !record.disposed) {
+      return record;
+    }
+  }
+  return null;
+}
+
+function publishDefaultScopeSnapshot(): void {
+  const record = defaultScopeRecord();
+  if (!record) {
+    return;
+  }
+  const { theme, hasCustomThemeOverride } = resolveScopeTheme(record.config);
+  validateScopeContrast(theme, hasCustomThemeOverride);
+  setThemeSnapshot({
+    scheme: theme.scheme,
+    themeName: theme.name,
+    // The agent snapshot keeps its stable 7-token shape, now sourced from the
+    // resolved semantic taxonomy (LLP 0269): old surface→card (raised),
+    // old surfaceAlt→surface (recessed).
+    tokens: {
+      background: theme.color.background.body,
+      surface: theme.color.background.card,
+      surfaceAlt: theme.color.background.surface,
+      border: theme.color.border.default,
+      text: theme.color.text.primary,
+      accent: theme.color.accent.fill,
+      muted: theme.color.text.secondary,
+    },
+    updatedAt: Date.now(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Scopes (LLP 0157 §2 "Scopes")
+// ---------------------------------------------------------------------------
+
+/**
+ * Registers a theme scope. The first live scope is the designated default
+ * scope and backs the agent snapshot; when it disposes, the next-oldest
+ * scope takes over. (Pre-F0, multiple React providers raced on the snapshot
+ * effect last-write-wins; first-registered-wins is the strictly-better
+ * clarification recorded in LLP 0157 §2.)
+ */
+export function registerThemeScope(config: ThemeScopeConfig = {}): ThemeScope {
+  ensureAgentOverrideSubscription();
+
+  const record: ScopeRecord = {
+    id: nextScopeId++,
+    config,
+    listeners: new Set(),
+    cachedTheme: null,
+    cachedAtVersion: -1,
+    disposed: false,
+  };
+  scopes.set(record.id, record);
+  scopeOrder.push(record.id);
+  publishDefaultScopeSnapshot();
+
+  let scopeVersion = 0;
+
+  function resolutionVersion(): number {
+    // Cache key over every input that can change resolution output.
+    return globalVersion * 1_000_000 + scopeVersion;
+  }
+
+  return {
+    id: record.id,
+
+    getTheme(): FacetTheme {
+      const version = resolutionVersion();
+      if (record.cachedTheme && record.cachedAtVersion === version) {
+        return record.cachedTheme;
+      }
+      const { theme, hasCustomThemeOverride } = resolveScopeTheme(record.config);
+      validateScopeContrast(theme, hasCustomThemeOverride);
+      record.cachedTheme = theme;
+      record.cachedAtVersion = version;
+      return theme;
+    },
+
+    subscribe(listener: () => void): () => void {
+      record.listeners.add(listener);
+      return () => {
+        record.listeners.delete(listener);
+      };
+    },
+
+    update(config: ThemeScopeConfig): void {
+      record.config = config;
+      record.cachedTheme = null;
+      scopeVersion += 1;
+      for (const listener of record.listeners) {
+        listener();
+      }
+      if (defaultScopeRecord() === record) {
+        publishDefaultScopeSnapshot();
+      }
+    },
+
+    dispose(): void {
+      if (record.disposed) {
+        return;
+      }
+      const wasDefault = defaultScopeRecord() === record;
+      record.disposed = true;
+      record.listeners.clear();
+      scopes.delete(record.id);
+      const index = scopeOrder.indexOf(record.id);
+      if (index >= 0) {
+        scopeOrder.splice(index, 1);
+      }
+      if (wasDefault) {
+        publishDefaultScopeSnapshot();
+      }
+    },
+
+    isDefault(): boolean {
+      return defaultScopeRecord() === record;
+    },
+  };
+}
+
+/**
+ * Resolves a theme without registering a scope (one-shot resolution with
+ * identical semantics, including the contrast warning when any override is
+ * active — the legacy provider warned per instance). The React binding uses
+ * this for its synchronous render path, passing its hook-read inputs; tests
+ * use it for the parity matrix.
+ */
+export function resolveThemeForConfig(
+  config: ThemeScopeConfig = {},
+  inputs?: ThemeResolutionInputs,
+): FacetTheme {
+  const { theme, hasCustomThemeOverride } = resolveScopeTheme(config, inputs);
+  validateScopeContrast(theme, hasCustomThemeOverride);
+  return theme;
+}
+
+// Wire the agent-override input eagerly so an override write that lands
+// before any scope/binding subscribes still bumps the store version (the
+// legacy provider's useSyncExternalStore snapshot caught exactly this race).
+ensureAgentOverrideSubscription();
+
+/** Test-only: clears all scopes and global inputs back to initial state. */
+export function _resetThemeStoreForTesting(): void {
+  scopes.clear();
+  scopeOrder.length = 0;
+  storeListeners.clear();
+  nextScopeId = 1;
+  systemAppearanceInput.set('light');
+  reducedMotionInput.set(false);
+  viewportWidthInput.set(390);
+  if (schemePreferenceStore.get() !== 'system') {
+    schemePreferenceStore.set('system');
+  }
+  if (agentOverrideSubscription) {
+    agentOverrideSubscription();
+    agentOverrideSubscription = null;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@exact/core": ["../exact-core/src/index.ts"],
+      "@exact/core/*": ["../exact-core/src/*"]
+    }
+  },
+  "include": ["src/**/*", "facet-registry.json"]
+}