@ccheever/exact-facet-core 0.1.0

package/src/theme-definition.ts

@@ -0,0 +1,566 @@
+// @system @ref LLP 0269 Part III — the Facet theme definition and resolver.
+//
+// This is the styling layer's `projections = resolve(definition)` instance:
+//
+//   FacetThemeDefinition  — a small, serializable, generative set of dials
+//                           (accent, density, type base+ratio, radius, motion).
+//   resolveFacetTheme()   — a deterministic function: definition + runtime
+//                           inputs (scheme, reduced motion, text scale, size
+//                           class) -> the resolved semantic `FacetTheme`.
+//
+// A human turns dials and an agent emits structured edits over the *definition*;
+// the resolver expands ~200 purpose-named tokens. Nobody edits the resolved
+// output. Context-computed values (concentric radius, per-instance control
+// sizing) are NOT pure functions of the definition, so the resolver emits the
+// *inputs* (radius scale, density maps, `concentricRadius`) and recipes finish
+// the computation at apply-time with the instance in hand (LLP 0269 §6).
+//
+// Pre-release execution note (LLP 0269): the resolver is the runtime path, not a
+// build-time/native compiler, and there is no backward-compat layer — the old
+// flat `FacetTheme` was deleted, not aliased.
+
+import {
+  buildFacetMotion,
+  clamp,
+  defaultSizeClasses,
+  facetSansFontFamily,
+  mixColors,
+  resolveSizeClassForWidth,
+  resolveThemeColorContrastPair,
+  withAlpha,
+  type DensitySize,
+  type FacetAdaptationTokens,
+  type FacetColorTokens,
+  type FacetDensityTokens,
+  type FacetElevationTokens,
+  type FacetRadiusTokens,
+  type FacetTheme,
+  type FacetTypeRole,
+  type FacetTypeTokens,
+  type FacetZIndexTokens,
+  type PlatformFamily,
+  type Scheme,
+  type SizeClass,
+  type SizeClassTokens,
+  type StatusColorSet,
+  type ThemeContrast,
+  type ThemeDensity,
+} from './internals.js';
+
+// ---------------------------------------------------------------------------
+// Definition
+// ---------------------------------------------------------------------------
+
+/** Modular type-scale ratios (LLP 0269 §4). */
+export type TypeRatioName =
+  | 'minorSecond'
+  | 'minorThird'
+  | 'majorThird'
+  | 'perfectFourth'
+  | 'augmentedFourth'
+  | 'perfectFifth'
+  | 'golden';
+
+/** Named radius shape scales (LLP 0269 §6). */
+export type RadiusScaleName = 'facetDefault' | 'platformSoft' | 'sharp' | 'round';
+
+/** Optional per-status hue overrides on the definition. */
+export interface StatusHueDefinition {
+  success?: string;
+  warning?: string;
+  danger?: string;
+  info?: string;
+}
+
+/**
+ * The serializable design artifact a human's dials and an agent's edits both
+ * write. Small and generative — this *is* the styling design. Everything a
+ * component reads is `resolve()`d from it.
+ */
+export interface FacetThemeDefinition {
+  name: string;
+  version: 1;
+  baseScheme: 'light' | 'dark' | 'system';
+  /** The single brand accent the whole accent family generates from. */
+  accent: string;
+  /** Optional neutral tint applied to the built-in grey ramp. */
+  neutral?: string;
+  /** Optional status hue overrides; defaults reproduce the shipped palette. */
+  status?: StatusHueDefinition;
+  density: ThemeDensity;
+  type: {
+    baseSize: number;
+    ratio: TypeRatioName;
+    headingFamily?: string;
+    bodyFamily?: string;
+    monoFamily?: string;
+  };
+  radius: {
+    scale: RadiusScaleName;
+    multiplier: number;
+  };
+  motion: {
+    multiplier: number;
+  };
+}
+
+/** Runtime inputs the resolver folds in on top of the definition. They are
+ * *not* part of the design — they are the host/user environment (LLP 0269 §9). */
+export interface ThemeResolveInputs {
+  scheme?: Scheme;
+  reducedMotion?: boolean;
+  textScale?: number;
+  contrast?: ThemeContrast;
+  platform?: PlatformFamily;
+  sizeClass?: SizeClass;
+  sizeClasses?: SizeClassTokens;
+  viewportWidth?: number;
+}
+
+/**
+ * The default Facet definition. Its resolved output is the shipped Facet look:
+ * a cool near-monochrome neutral ramp, hairline borders, and a single indigo
+ * accent — the Linear / Vercel / Stripe family. Turning these dials is how you
+ * rebrand, densify, round, or calm the entire system.
+ */
+export const defaultThemeDefinition: FacetThemeDefinition = {
+  name: 'facet',
+  version: 1,
+  baseScheme: 'system',
+  accent: '#5e6ad2',
+  density: 'default',
+  type: { baseSize: 14, ratio: 'minorThird' },
+  radius: { scale: 'facetDefault', multiplier: 1 },
+  motion: { multiplier: 1 },
+};
+
+// ---------------------------------------------------------------------------
+// Built-in ramps the resolver expands
+// ---------------------------------------------------------------------------
+
+interface NeutralRamp {
+  body: string;
+  /** The recessed neutral surface (secondary control fill). */
+  surface: string;
+  /** The raised card/panel surface. */
+  card: string;
+  popover: string;
+  inverted: string;
+  textPrimary: string;
+  textSecondary: string;
+  borderDefault: string;
+  overlayScrim: string;
+  overlayHover: string;
+  overlayPressed: string;
+  shadowColor: string;
+}
+
+// The shipped neutral ramps, carried verbatim from the pre-revision flat themes
+// so the default definition resolves pixel-faithfully. `surface` is the old
+// `surfaceAlt` (recessed) and `card` is the old `surface` (raised) — see the
+// `FacetColorTokens.background` doc comment in internals.ts.
+const LIGHT_NEUTRALS: NeutralRamp = {
+  body: '#fbfbfc',
+  surface: '#f3f3f5',
+  card: '#ffffff',
+  popover: '#ffffff',
+  inverted: '#1c1d21',
+  textPrimary: '#1c1d21',
+  textSecondary: '#5f636c',
+  borderDefault: '#e4e4e9',
+  overlayScrim: 'rgba(20, 21, 26, 0.40)',
+  overlayHover: 'rgba(28, 29, 33, 0.05)',
+  overlayPressed: 'rgba(28, 29, 33, 0.10)',
+  shadowColor: '#101828',
+};
+
+const DARK_NEUTRALS: NeutralRamp = {
+  body: '#08090a',
+  surface: '#141517',
+  card: '#0f1011',
+  popover: '#0f1011',
+  inverted: '#f7f8f8',
+  textPrimary: '#f7f8f8',
+  textSecondary: '#a4a8b0',
+  borderDefault: '#212327',
+  overlayScrim: 'rgba(2, 3, 4, 0.66)',
+  overlayHover: 'rgba(247, 248, 248, 0.06)',
+  overlayPressed: 'rgba(247, 248, 248, 0.10)',
+  shadowColor: '#000000',
+};
+
+const DEFAULT_STATUS: Required<StatusHueDefinition> = {
+  success: '#2a8447',
+  danger: '#c4392f',
+  warning: '#b7791f',
+  info: '#2563c9',
+};
+
+const TYPE_RATIOS: Record<TypeRatioName, number> = {
+  minorSecond: 1.067,
+  minorThird: 1.2,
+  majorThird: 1.25,
+  perfectFourth: 1.333,
+  augmentedFourth: 1.414,
+  perfectFifth: 1.5,
+  golden: 1.618,
+};
+
+// Semantic radius levels per scale. `none`/`full` are fixed anchors added by
+// `resolveRadius`. `facetDefault` reproduces the shipped sm/md/lg (8/10/14).
+const RADIUS_SCALES: Record<RadiusScaleName, { inner: number; element: number; container: number; page: number }> = {
+  facetDefault: { inner: 6, element: 8, container: 10, page: 14 },
+  platformSoft: { inner: 8, element: 12, container: 16, page: 22 },
+  sharp: { inner: 2, element: 4, container: 6, page: 8 },
+  round: { inner: 10, element: 16, container: 22, page: 28 },
+};
+
+const DENSITY_TABLE: Record<ThemeDensity, Omit<FacetDensityTokens, 'mode'>> = {
+  compact: {
+    controlHeight: { sm: 28, md: 34, lg: 40 },
+    rowHeight: 36,
+    iconSize: { sm: 14, md: 18, lg: 22 },
+    minHitTarget: 40,
+    paddingScale: 0.85,
+  },
+  default: {
+    controlHeight: { sm: 32, md: 40, lg: 48 },
+    rowHeight: 44,
+    iconSize: { sm: 16, md: 20, lg: 24 },
+    minHitTarget: 44,
+    paddingScale: 1,
+  },
+  comfortable: {
+    controlHeight: { sm: 36, md: 44, lg: 52 },
+    rowHeight: 52,
+    iconSize: { sm: 18, md: 22, lg: 26 },
+    minHitTarget: 48,
+    paddingScale: 1.15,
+  },
+  gigantic: {
+    controlHeight: { sm: 44, md: 56, lg: 68 },
+    rowHeight: 64,
+    iconSize: { sm: 22, md: 28, lg: 34 },
+    minHitTarget: 56,
+    paddingScale: 1.4,
+  },
+};
+
+const FACET_MONO_FAMILY = [
+  'ui-monospace',
+  'SFMono-Regular',
+  'SF Mono',
+  'Menlo',
+  'Consolas',
+  'Liberation Mono',
+  'monospace',
+] as const;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Pick whichever of two foreground colours has the higher contrast on `bg`. */
+function onColorFor(bg: string, light: string, dark: string): string {
+  const lightRatio = resolveThemeColorContrastPair(light, bg) ?? 0;
+  const darkRatio = resolveThemeColorContrastPair(dark, bg) ?? 0;
+  return lightRatio >= darkRatio ? light : dark;
+}
+
+/**
+ * Concentric inner radius: a rounded surface nested inside another with
+ * `padding` between them stays visually concentric when its radius is the
+ * outer radius minus the padding (LLP 0269 §6). Recipes call this at
+ * apply-time; it is exported as a resolver *input*, not a resolved token.
+ */
+export function concentricRadius(outerRadius: number, padding: number): number {
+  return Math.max(0, Math.round(outerRadius - padding));
+}
+
+/**
+ * The outward form of concentricity (LLP 0269 §6): a surface that *wraps* a
+ * rounded inner chrome at `inset` distance (a focus halo around a field)
+ * stays visually concentric when its radius is the inner radius plus the
+ * inset. Like `concentricRadius`, this is a resolver *input* recipes call at
+ * apply-time with the instance's geometry in hand.
+ */
+export function concentricOuterRadius(innerRadius: number, inset: number): number {
+  return Math.max(0, Math.round(innerRadius + inset));
+}
+
+function resolveNeutralRamp(scheme: Scheme, neutral: string | undefined): NeutralRamp {
+  const base = scheme === 'dark' ? DARK_NEUTRALS : LIGHT_NEUTRALS;
+  if (!neutral) {
+    return base;
+  }
+  // A neutral dial tints the grey ramp toward the chosen hue without disturbing
+  // the lightness relationships that keep contrast intact.
+  const tint = (color: string, amount: number): string => mixColors(color, neutral, amount);
+  return {
+    ...base,
+    body: tint(base.body, 0.04),
+    surface: tint(base.surface, 0.05),
+    card: tint(base.card, 0.03),
+    popover: tint(base.popover, 0.03),
+    borderDefault: tint(base.borderDefault, 0.08),
+  };
+}
+
+function resolveColor(
+  scheme: Scheme,
+  ramp: NeutralRamp,
+  accent: string,
+  status: Required<StatusHueDefinition>,
+  contrast: ThemeContrast,
+): FacetColorTokens {
+  // On-colors are chosen by the *fill's* lightness, not the scheme: a light
+  // amber warning needs dark ink in dark mode too. So the candidates are always
+  // paper-white and a fixed near-black ink, never the scheme's text color.
+  const onLight = '#ffffff';
+  const onDark = '#0e0f12';
+
+  const accentOnFill = onColorFor(accent, onLight, onDark);
+  const accentSet = {
+    fill: accent,
+    hover: mixColors(accent, '#000000', 0.1),
+    pressed: mixColors(accent, '#000000', 0.2),
+    // Link/text accent: lift toward the surface in dark mode for legibility on
+    // dark backgrounds, keep the brand accent in light mode.
+    text: scheme === 'dark' ? mixColors(accent, '#ffffff', 0.18) : accent,
+    onFill: accentOnFill,
+  };
+
+  const statusSet = (hue: string): StatusColorSet => ({
+    fill: hue,
+    muted: mixColors(hue, ramp.card, scheme === 'dark' ? 0.82 : 0.86),
+    text: scheme === 'dark' ? mixColors(hue, '#ffffff', 0.28) : mixColors(hue, '#000000', 0.12),
+    onFill: onColorFor(hue, onLight, onDark),
+    border: mixColors(hue, ramp.card, scheme === 'dark' ? 0.52 : 0.58),
+  });
+
+  const textSecondary = contrast === 'increased'
+    ? mixColors(ramp.textSecondary, ramp.textPrimary, 0.4)
+    : ramp.textSecondary;
+  const textDisabled = mixColors(ramp.textSecondary, ramp.card, 0.45);
+  const borderDefault = contrast === 'increased'
+    ? mixColors(ramp.borderDefault, ramp.textPrimary, 0.3)
+    : ramp.borderDefault;
+  const borderSubtle = mixColors(ramp.borderDefault, ramp.body, 0.5);
+  const borderStrong = mixColors(ramp.borderDefault, ramp.textPrimary, 0.3);
+
+  return {
+    background: {
+      body: ramp.body,
+      surface: ramp.surface,
+      card: ramp.card,
+      popover: ramp.popover,
+      inverted: ramp.inverted,
+    },
+    text: {
+      primary: ramp.textPrimary,
+      secondary: textSecondary,
+      disabled: textDisabled,
+      accent: accentSet.text,
+      onAccent: accentSet.onFill,
+      onDanger: onColorFor(status.danger, onLight, onDark),
+      onSuccess: onColorFor(status.success, onLight, onDark),
+      onWarning: onColorFor(status.warning, onLight, onDark),
+    },
+    icon: {
+      primary: ramp.textPrimary,
+      secondary: textSecondary,
+      disabled: textDisabled,
+      accent: accentSet.fill,
+    },
+    border: {
+      subtle: borderSubtle,
+      default: borderDefault,
+      strong: borderStrong,
+      focus: accentSet.fill,
+    },
+    status: {
+      success: statusSet(status.success),
+      warning: statusSet(status.warning),
+      danger: statusSet(status.danger),
+      info: statusSet(status.info),
+    },
+    overlay: {
+      scrim: ramp.overlayScrim,
+      hover: ramp.overlayHover,
+      pressed: ramp.overlayPressed,
+      selected: withAlpha(accent, scheme === 'dark' ? 0.22 : 0.12),
+    },
+    accent: accentSet,
+  };
+}
+
+function resolveType(
+  def: FacetThemeDefinition,
+  textScale: number,
+): FacetTypeTokens {
+  const ratio = TYPE_RATIOS[def.type.ratio] ?? TYPE_RATIOS.minorThird;
+  const base = def.type.baseSize * (textScale > 0 ? textScale : 1);
+  const sizeAt = (steps: number): number => Math.round(base * Math.pow(ratio, steps));
+
+  const bodyFamily = def.type.bodyFamily
+    ? [def.type.bodyFamily, ...facetSansFontFamily]
+    : [...facetSansFontFamily];
+  const headingFamily = def.type.headingFamily
+    ? [def.type.headingFamily, ...facetSansFontFamily]
+    : bodyFamily;
+  const monoFamily = def.type.monoFamily
+    ? [def.type.monoFamily, ...FACET_MONO_FAMILY]
+    : [...FACET_MONO_FAMILY];
+
+  const role = (
+    fontSize: number,
+    fontWeight: number,
+    fontFamily: readonly string[],
+    tight: boolean,
+    letterSpacing?: number,
+  ): FacetTypeRole => ({
+    fontSize,
+    lineHeight: Math.round(fontSize * (tight ? 1.25 : 1.5)),
+    fontWeight,
+    fontFamily,
+    letterSpacing,
+  });
+
+  return {
+    caption: role(sizeAt(-1), 400, bodyFamily, false),
+    body: role(sizeAt(0), 400, bodyFamily, false),
+    bodyStrong: role(sizeAt(0), 600, bodyFamily, false),
+    label: role(sizeAt(0), 500, bodyFamily, false),
+    title: role(sizeAt(1), 600, headingFamily, true),
+    heading: role(sizeAt(2), 700, headingFamily, true, -0.2),
+    display: role(sizeAt(3), 700, headingFamily, true, -0.4),
+    code: role(sizeAt(0), 400, monoFamily, false),
+    families: { body: bodyFamily, heading: headingFamily, mono: monoFamily },
+  };
+}
+
+function resolveRadius(def: FacetThemeDefinition): FacetRadiusTokens {
+  const scale = RADIUS_SCALES[def.radius.scale] ?? RADIUS_SCALES.facetDefault;
+  const multiplier = Number.isFinite(def.radius.multiplier) ? clamp(def.radius.multiplier, 0, 4) : 1;
+  const scaled = (value: number): number => Math.round(value * multiplier);
+  return {
+    none: 0,
+    inner: scaled(scale.inner),
+    element: scaled(scale.element),
+    container: scaled(scale.container),
+    page: scaled(scale.page),
+    full: 999,
+  };
+}
+
+function resolveDensity(mode: ThemeDensity): FacetDensityTokens {
+  const table = DENSITY_TABLE[mode] ?? DENSITY_TABLE.default;
+  return {
+    mode,
+    controlHeight: { ...table.controlHeight } as Record<DensitySize, number>,
+    rowHeight: table.rowHeight,
+    iconSize: { ...table.iconSize } as Record<DensitySize, number>,
+    minHitTarget: table.minHitTarget,
+    paddingScale: table.paddingScale,
+  };
+}
+
+function resolveElevation(scheme: Scheme): FacetElevationTokens {
+  if (scheme === 'dark') {
+    return {
+      low: { x: 0, y: 1, blur: 2, color: '#000000', opacity: 0.5 },
+      medium: { x: 0, y: 8, blur: 24, color: '#000000', opacity: 0.52 },
+      high: { x: 0, y: 18, blur: 50, color: '#000000', opacity: 0.55 },
+    };
+  }
+  return {
+    low: { x: 0, y: 1, blur: 2, color: '#101828', opacity: 0.07 },
+    medium: { x: 0, y: 6, blur: 20, color: '#101828', opacity: 0.12 },
+    high: { x: 0, y: 16, blur: 48, color: '#101828', opacity: 0.16 },
+  };
+}
+
+const ZINDEX: FacetZIndexTokens = {
+  base: 0,
+  dropdown: 1000,
+  sticky: 1100,
+  modal: 1400,
+  toast: 1700,
+  tooltip: 1800,
+};
+
+// ---------------------------------------------------------------------------
+// The resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * `resolve(definition)`. Deterministic: the same definition + inputs always
+ * yields the same resolved theme (the property the golden check asserts).
+ * System scheme is resolved upstream (theme-store passes a concrete scheme);
+ * if absent it falls back to the definition's `baseScheme`.
+ */
+export function resolveFacetTheme(
+  definition: FacetThemeDefinition,
+  inputs: ThemeResolveInputs = {},
+): FacetTheme {
+  const scheme: Scheme = inputs.scheme
+    ?? (definition.baseScheme === 'dark' ? 'dark' : 'light');
+  const reducedMotion = inputs.reducedMotion ?? false;
+  const textScale = inputs.textScale ?? 1;
+  const contrast = inputs.contrast ?? 'standard';
+  const platform = inputs.platform ?? 'web';
+  const sizeClasses = inputs.sizeClasses ?? defaultSizeClasses;
+  const sizeClass = inputs.sizeClass
+    ?? resolveSizeClassForWidth(inputs.viewportWidth ?? 0, sizeClasses);
+
+  const ramp = resolveNeutralRamp(scheme, definition.neutral);
+  const status: Required<StatusHueDefinition> = { ...DEFAULT_STATUS, ...(definition.status ?? {}) };
+
+  const color = resolveColor(scheme, ramp, definition.accent, status, contrast);
+  const motion = buildFacetMotion(reducedMotion, definition.motion.multiplier);
+
+  const adaptation: FacetAdaptationTokens = {
+    scheme,
+    sizeClass,
+    reducedMotion,
+    textScale,
+    contrast,
+    platform,
+  };
+
+  // Space is the base scale; density's `paddingScale` is applied by recipes at
+  // apply-time rather than mutating the shared spacing tokens.
+  const space = { xs: 6, sm: 10, md: 14, lg: 20, xl: 28 };
+
+  return {
+    name: definition.name,
+    scheme,
+    sizeClass,
+    sizeClasses,
+    color,
+    space,
+    density: resolveDensity(definition.density),
+    type: resolveType(definition, textScale),
+    radius: resolveRadius(definition),
+    elevation: resolveElevation(scheme),
+    zIndex: { ...ZINDEX },
+    motion,
+    adaptation,
+  };
+}
+
+// The shipped light/dark themes are now resolver output, not hand-authored
+// token bags. `index.ts` re-exports these as the package's `lightTheme` /
+// `darkTheme`.
+export const lightTheme: FacetTheme = resolveFacetTheme(defaultThemeDefinition, { scheme: 'light' });
+export const darkTheme: FacetTheme = resolveFacetTheme(defaultThemeDefinition, { scheme: 'dark' });
+
+/** Convenience for `definition.baseScheme === 'system'`-aware resolution that a
+ * host has already collapsed to a concrete scheme. */
+export function resolveSchemeTheme(
+  definition: FacetThemeDefinition,
+  scheme: Scheme,
+  inputs: Omit<ThemeResolveInputs, 'scheme'> = {},
+): FacetTheme {
+  return resolveFacetTheme(definition, { ...inputs, scheme });
+}