@ccheever/exact-facet-core 0.1.0

package/src/facet-overrides.ts

@@ -0,0 +1,322 @@
+// @system @ref LLP 0158 §6.2 — Design Mode D1: the facet overrides layer.
+//
+// Two process-global, file-backed override inputs plus the recipe-parameter
+// resolver. This is the NEW resolution layer the round-1 review demanded be
+// specified rather than assumed: theme overrides answer "what is
+// theme.space.md"; THIS layer answers "what is FacetButton·primary's
+// paddingX parameter before the recipe runs."
+//
+// Inputs are set by the app's generated authority files
+// (js/src/theme.overrides.ts, js/src/facets.overrides.ts via their loader)
+// and previewed in-memory by Design Mode; the theme store subscribes both
+// and bumps its global version, so every binding re-renders on change.
+// Precedence at parameter resolution time (LLP 0158 §6.2):
+//   override(variant) → override(base) → recipe default.
+// A value is either a literal or a token rebind `{ token: "space.md" }` —
+// the two stay distinct in source, provenance, and diffs.
+
+import { resolveDensityPadding, type DeepPartial, type FacetTheme } from './internals.js';
+import type { FacetThemeDefinition } from './theme-definition.js';
+
+// ---------------------------------------------------------------------------
+// Recipe parameter declarations (LLP 0158 §6.2 "parameter reification")
+// ---------------------------------------------------------------------------
+
+/**
+ * The tunable-parameter table. D1 reifies the state-independent geometry
+ * parameters of the interactive trio; color/state-aware parameters need a
+ * richer declaration (per-state values) and are deliberately deferred —
+ * color edits in D1 are theme-scope token edits. Keys are the facet
+ * component call names as they appear at Contract boundaries.
+ *
+ * LLP 0163 §5.4 (E1c): the AUTHORITY is the `params` sections in the
+ * facet components' own .contract files; this table is GENERATED output
+ * (bun run generate:facet-params), re-exported here so every consumer —
+ * the overrides authority's types (`FacetParamOverrides`), the resolver's
+ * call sites, the Design Mode panel, the prompt lane — keeps reading the
+ * same neutral data, indifferent to who wrote it. facet-core has no
+ * runtime import on facet-contract or the compiler: the dependency is
+ * generator-time data flow only.
+ */
+export { RECIPE_PARAMETERS } from './facet-params.generated.js';
+import { RECIPE_PARAMETERS } from './facet-params.generated.js';
+
+export type FacetParamComponent = keyof typeof RECIPE_PARAMETERS;
+
+export type FacetParamValue = string | number | boolean | { token: string };
+
+/** Shape of the facets.overrides.ts authority, derived from the table. */
+export type FacetParamOverrides = {
+  [Component in FacetParamComponent]?: {
+    base?: Partial<Record<keyof (typeof RECIPE_PARAMETERS)[Component]['params'], FacetParamValue>>;
+    variants?: Record<
+      string,
+      Partial<Record<keyof (typeof RECIPE_PARAMETERS)[Component]['params'], FacetParamValue>>
+    >;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Process-global state
+// ---------------------------------------------------------------------------
+
+/** Definition-level dial overrides (the theme.definition.ts authority, LLP
+ * 0269). This is the *generative* layer Design Mode dials and agents edit:
+ * accent, density, type, radius, motion. It resolves below every token
+ * override — a dial is broad, a token/instance override wins locally. */
+export type ThemeDefinitionOverrides = DeepPartial<FacetThemeDefinition>;
+
+interface FacetOverridesState {
+  themeDefinitionOverrides: ThemeDefinitionOverrides | null;
+  appThemeOverrides: DeepPartial<FacetTheme> | null;
+  facetParamOverrides: FacetParamOverrides | null;
+  listeners: Set<() => void>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __exactFacetOverridesState: FacetOverridesState | undefined;
+}
+
+function getState(): FacetOverridesState {
+  if (globalThis.__exactFacetOverridesState) {
+    return globalThis.__exactFacetOverridesState;
+  }
+  const state: FacetOverridesState = {
+    themeDefinitionOverrides: null,
+    appThemeOverrides: null,
+    facetParamOverrides: null,
+    listeners: new Set(),
+  };
+  globalThis.__exactFacetOverridesState = state;
+  return state;
+}
+
+function notify(): void {
+  for (const listener of getState().listeners) {
+    listener();
+  }
+}
+
+/** Definition-level dial overrides (the theme.definition.ts authority). */
+export function setThemeDefinitionOverrides(overrides: ThemeDefinitionOverrides | null): void {
+  getState().themeDefinitionOverrides =
+    overrides && Object.keys(overrides).length > 0 ? overrides : null;
+  notify();
+}
+
+export function getThemeDefinitionOverrides(): ThemeDefinitionOverrides | null {
+  return getState().themeDefinitionOverrides;
+}
+
+/** App-level theme token overrides (the theme.overrides.ts authority). */
+export function setAppThemeOverrides(overrides: DeepPartial<FacetTheme> | null): void {
+  getState().appThemeOverrides = overrides && Object.keys(overrides).length > 0 ? overrides : null;
+  notify();
+}
+
+export function getAppThemeOverrides(): DeepPartial<FacetTheme> | null {
+  return getState().appThemeOverrides;
+}
+
+/** Facet recipe-parameter overrides (the facets.overrides.ts authority). */
+export function setFacetParamOverrides(overrides: FacetParamOverrides | null): void {
+  getState().facetParamOverrides =
+    overrides && Object.keys(overrides).length > 0 ? overrides : null;
+  notify();
+}
+
+export function getFacetParamOverrides(): FacetParamOverrides | null {
+  return getState().facetParamOverrides;
+}
+
+/** One subscription covers both layers; the theme store bumps on either. */
+export function subscribeFacetOverrides(listener: () => void): () => void {
+  const state = getState();
+  state.listeners.add(listener);
+  return () => {
+    state.listeners.delete(listener);
+  };
+}
+
+export function _resetFacetOverridesForTests(): void {
+  const state = getState();
+  state.themeDefinitionOverrides = null;
+  state.appThemeOverrides = null;
+  state.facetParamOverrides = null;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+function readTokenPath(theme: FacetTheme, path: string): unknown {
+  let cursor: unknown = theme;
+  for (const segment of path.split('.')) {
+    if (cursor === null || typeof cursor !== 'object') {
+      return undefined;
+    }
+    cursor = (cursor as Record<string, unknown>)[segment];
+  }
+  return cursor;
+}
+
+/** Value kind of a theme token leaf (LLP 0166 §4.4 schema kinds). */
+export type ThemeTokenValueKind = 'dimension' | 'color' | 'duration' | 'number' | 'string' | 'boolean';
+
+/**
+ * Flattens a theme into the token schema `$` references validate against
+ * (LLP 0166 §4.4): every leaf path mapped to its value kind. Paths name
+ * schema positions, not concrete values — any complete theme yields the
+ * same path set, so callers typically pass a base theme.
+ */
+export function collectThemeTokenSchema(theme: FacetTheme): {
+  paths: Record<string, ThemeTokenValueKind>;
+} {
+  const paths: Record<string, ThemeTokenValueKind> = {};
+  const DURATION_LEAVES = new Set(['fast', 'normal', 'slow']);
+  const kindFor = (rootKey: string, leafKey: string, value: unknown): ThemeTokenValueKind => {
+    if (rootKey === 'color' || leafKey === 'color') {
+      return 'color';
+    }
+    if (rootKey === 'space' || rootKey === 'radius') {
+      return 'dimension';
+    }
+    if (rootKey === 'density') {
+      return leafKey === 'paddingScale'
+        ? 'number'
+        : typeof value === 'number'
+          ? 'dimension'
+          : typeof value === 'boolean'
+            ? 'boolean'
+            : 'string';
+    }
+    if (rootKey === 'type') {
+      if (leafKey === 'fontWeight' || leafKey === 'letterSpacing') {
+        return 'number';
+      }
+      return typeof value === 'number' ? 'dimension' : 'string';
+    }
+    if (rootKey === 'elevation') {
+      return typeof value === 'number' ? 'dimension' : 'string';
+    }
+    if (rootKey === 'motion' && typeof value === 'number') {
+      return DURATION_LEAVES.has(leafKey) ? 'duration' : 'number';
+    }
+    if (typeof value === 'number') {
+      return 'number';
+    }
+    if (typeof value === 'boolean') {
+      return 'boolean';
+    }
+    return 'string';
+  };
+  const walk = (value: unknown, prefix: string, rootKey: string): void => {
+    // Arrays (e.g. type.*.fontFamily stacks) are token leaves, not branches.
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      Object.keys(value as Record<string, unknown>).forEach((key) => {
+        walk(
+          (value as Record<string, unknown>)[key],
+          prefix === '' ? key : `${prefix}.${key}`,
+          prefix === '' ? key : rootKey,
+        );
+      });
+      return;
+    }
+    const leafKey = prefix.split('.').pop() ?? prefix;
+    paths[prefix] = kindFor(rootKey, leafKey, value);
+  };
+  const roots: Array<keyof FacetTheme> = [
+    'color',
+    'space',
+    'density',
+    'type',
+    'radius',
+    'elevation',
+    'zIndex',
+    'motion',
+    'adaptation',
+  ];
+  roots.forEach((root) => {
+    walk(theme[root], root, root);
+  });
+  return { paths };
+}
+
+/**
+ * Resolves one recipe parameter: override(variant) → override(base) →
+ * `fallback` (the recipe's existing expression, so empty overrides are
+ * byte-identical to pre-reification output). Token rebinds read through the
+ * live theme — including the sentinel tracing twin, so traced origins stay
+ * correct under rebinding for free.
+ */
+/**
+ * Button padding recipe (LLP 0269 §5, D10): the density-scaled space defaults
+ * behind the LLP 0158 §6.2 override layer. Both bindings (React `Button`,
+ * facet-contract `buttonStyle`) call this one helper, so the density dial and
+ * the override layer cannot drift per framework. An explicit override is an
+ * absolute author value and is NOT re-scaled by density (most-specific-wins:
+ * the override already states the final geometry).
+ */
+export function resolveButtonPadding(
+  theme: FacetTheme,
+  variant: string | null | undefined,
+): { paddingX: number; paddingY: number } {
+  return {
+    paddingX: resolveRecipeParam(
+      theme,
+      'FacetButton',
+      variant ?? null,
+      'paddingX',
+      resolveDensityPadding(theme, theme.space.md),
+    ),
+    paddingY: resolveRecipeParam(
+      theme,
+      'FacetButton',
+      variant ?? null,
+      'paddingY',
+      resolveDensityPadding(theme, theme.space.xs),
+    ),
+  };
+}
+
+/** Card padding recipe (LLP 0269 §5, D10) — same contract as
+ * `resolveButtonPadding`: density-scaled default, absolute override wins. */
+export function resolveCardPadding(theme: FacetTheme): number {
+  return resolveRecipeParam(
+    theme,
+    'FacetCard',
+    null,
+    'padding',
+    resolveDensityPadding(theme, theme.space.lg),
+  );
+}
+
+export function resolveRecipeParam<T>(
+  theme: FacetTheme,
+  component: string,
+  variant: string | null | undefined,
+  param: string,
+  fallback: T,
+): T {
+  const overrides = getState().facetParamOverrides?.[component as FacetParamComponent];
+  if (!overrides) {
+    return fallback;
+  }
+  const fromVariant =
+    variant != null
+      ? (overrides.variants?.[variant] as Record<string, FacetParamValue> | undefined)?.[param]
+      : undefined;
+  const value =
+    fromVariant !== undefined
+      ? fromVariant
+      : (overrides.base as Record<string, FacetParamValue> | undefined)?.[param];
+  if (value === undefined) {
+    return fallback;
+  }
+  if (value !== null && typeof value === 'object' && 'token' in value) {
+    const resolved = readTokenPath(theme, value.token);
+    return resolved === undefined ? fallback : (resolved as T);
+  }
+  return value as T;
+}

package/src/facet-params.generated.ts

@@ -0,0 +1,65 @@
+// AUTO-GENERATED — DO NOT EDIT.
+// AUTHORITY: the `params` sections in
+// packages/exact-facet-contract/src/components/*.contract (LLP 0163 §5.4).
+// Generator: bun run generate:facet-params (scripts/generate-facet-params.mjs).
+//
+// The reified recipe-parameter table (LLP 0158 §6.2): the overrides
+// authority's types derive from it, resolveRecipeParam's callers consult
+// it, the Design Mode panel enumerates it, and the prompt lane validates
+// against it. It is DERIVED OUTPUT — change the params sections and
+// regenerate; never hand-edit (verified by design-provenance-fixtures).
+
+export const RECIPE_PARAMETERS = {
+  FacetBadge: {
+    variants: [
+      'neutral',
+      'accent',
+      'success',
+      'danger'
+    ],
+    params: {
+      radius: {
+        defaultToken: 'radius.full',
+        kind: 'dimension'
+      }
+    }
+  },
+  FacetButton: {
+    variants: [
+      'primary',
+      'secondary',
+      'ghost'
+    ],
+    params: {
+      paddingX: {
+        defaultToken: 'space.md',
+        kind: 'dimension'
+      },
+      paddingY: {
+        defaultToken: 'space.xs',
+        kind: 'dimension'
+      },
+      radius: {
+        defaultToken: 'radius.element',
+        kind: 'dimension'
+      }
+    }
+  },
+  FacetCard: {
+    variants: [],
+    params: {
+      padding: {
+        defaultToken: 'space.lg',
+        kind: 'dimension'
+      },
+      gap: {
+        defaultToken: 'space.md',
+        kind: 'dimension'
+      },
+      radius: {
+        defaultToken: 'radius.container',
+        kind: 'dimension'
+      }
+    }
+  }
+} as const;

package/src/facet-scorecard.ts

@@ -0,0 +1,60 @@
+export type FacetScoreValue = 0 | 1 | 2 | 3;
+
+export interface FacetComponentScorecard {
+  animation: FacetScoreValue;
+  interaction: FacetScoreValue;
+  accessibility: FacetScoreValue;
+  testing: FacetScoreValue;
+  notes: string;
+}
+
+function scorecard(
+  animation: FacetScoreValue,
+  interaction: FacetScoreValue,
+  accessibility: FacetScoreValue,
+  testing: FacetScoreValue,
+  notes: string,
+): FacetComponentScorecard {
+  return {
+    animation,
+    interaction,
+    accessibility,
+    testing,
+    notes,
+  };
+}
+
+export const facetScorecards: Record<string, FacetComponentScorecard> = {
+  Button: scorecard(3, 3, 3, 3, 'Primary pathfinder component with dedicated tree, interaction, and screenshot coverage.'),
+  Input: scorecard(3, 3, 3, 3, 'Shared input chrome has hover, focus, validation, reduced-motion, and regression coverage.'),
+  Textarea: scorecard(3, 3, 3, 3, 'Textarea rides the same shell and tests as Input, including FormField wiring.'),
+  FormField: scorecard(1, 2, 3, 3, 'Static wrapper, but labels, descriptions, messages, and aria wiring are covered in the form matrix.'),
+  Card: scorecard(3, 3, 2, 3, 'Interactive cards now carry hover, focus, and press treatment with tree and screenshot checks.'),
+  Badge: scorecard(3, 3, 2, 3, 'Interactive badges share the control motion surface and have dedicated interaction assertions.'),
+  Label: scorecard(0, 1, 3, 2, 'Mostly semantic text, but it now participates in the shared form-field contract.'),
+  Separator: scorecard(0, 0, 2, 2, 'Pure presentational divider with basic catalog and tree coverage.'),
+  Avatar: scorecard(1, 0, 2, 2, 'Static feedback primitive with catalog and fixture coverage, but no richer interaction path.'),
+  Skeleton: scorecard(1, 0, 1, 2, 'Static loading placeholder with catalog coverage; no interaction surface.'),
+  Progress: scorecard(2, 0, 2, 2, 'Determinate progress has semantics and catalog coverage, but no dedicated interaction path.'),
+  Spinner: scorecard(2, 0, 2, 2, 'Indeterminate loading state is visually covered but intentionally non-interactive.'),
+  Alert: scorecard(2, 0, 3, 2, 'Live-region alert surface is semantically strong and visible in the catalog/fixture pages.'),
+  Toggle: scorecard(3, 3, 3, 3, 'Toggle now has full interaction-state coverage plus reduced-motion and tree assertions.'),
+  Checkbox: scorecard(3, 3, 3, 3, 'Checkbox carries hover, focus, press, and checked states with dedicated regression tests.'),
+  Slider: scorecard(2, 2, 3, 2, 'Accessible stepper fallback exists, but the composed fallback still lacks a richer drag-path test story.'),
+  RadioGroup: scorecard(3, 3, 3, 3, 'Roving focus, selection motion, and interaction-state coverage are in place.'),
+  Dialog: scorecard(3, 3, 3, 3, 'Dialog has presence-backed motion, focus behavior, and dedicated screenshot/tree coverage.'),
+  AlertDialog: scorecard(3, 2, 3, 2, 'Modal semantics are strong, but the screenshot matrix only covers it through the shared fixture surface today.'),
+  Sheet: scorecard(3, 2, 3, 2, 'Sheet reuses the dialog stack and motion surface, with baseline catalog coverage but fewer dedicated checks.'),
+  Accordion: scorecard(3, 3, 3, 3, 'Presence-backed content, trigger interaction states, and dedicated tree/screenshot tests are in place.'),
+  Collapsible: scorecard(3, 3, 3, 3, 'Standalone disclosure primitive ships with presence motion, interaction states, and dedicated behavior plus visual coverage.'),
+  Tabs: scorecard(3, 3, 3, 3, 'Animated indicator, focus states, and dedicated tree/screenshot coverage are in place.'),
+  Toast: scorecard(3, 2, 3, 3, 'Toast has presence-backed motion, semantics, and dedicated visual/tree regression coverage.'),
+  Popover: scorecard(3, 3, 2, 3, 'Floating placement and presence motion are covered in both interaction and screenshot tests.'),
+  Tooltip: scorecard(3, 2, 2, 2, 'Tooltip motion is polished, but focus/hover and screenshot coverage are still lighter than Dialog/Popover.'),
+  DropdownMenu: scorecard(3, 3, 2, 2, 'Menu behavior exists, but the visual regression surface is still mostly catalog-level.'),
+  Select: scorecard(3, 3, 3, 3, 'Select now has its own trigger path, value state, and both interaction and screenshot coverage.'),
+  Combobox: scorecard(3, 3, 3, 3, 'Combobox adds searchable filtering, keyboard selection, and dedicated regression coverage on top of the floating listbox stack.'),
+  Command: scorecard(3, 3, 3, 3, 'Command ships as a dialog-backed palette with grouped filtering, keyboard selection, and dedicated visual plus interaction coverage.'),
+  Table: scorecard(3, 3, 3, 3, 'Table now provides semantic row and header structure, sortable headers, interactive rows, and dedicated coverage.'),
+  ContextMenu: scorecard(3, 2, 2, 2, 'Context menu behavior exists, but its visual and accessibility checks are still less exhaustive than top-level menus.'),
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+// @system @ref LLP 0157 — @exact/facet-core public surface.
+//
+// Framework-neutral heart of the Facet design system: theme types and
+// definitions, every variant recipe, motion builders, color and control
+// math, catalog/scorecard metadata, and the consolidated theme store.
+// `@exact/facet` (React) and `@exact/facet-contract` (Contract) are thin
+// bindings over this package.
+
+export * from './internals.js';
+export * from './theme-definition.js';
+export * from './facet-catalog.js';
+export * from './facet-scorecard.js';
+export * from './theme-store.js';
+export * from './store-machinery.js';
+export * from './provenance-trace.js';
+export * from './facet-overrides.js';