Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file statusRoleDerivation.ts
 * @input A theme's portable and local token maps
 * @output Concrete values for the status roles the theme does not set
 * @position Theme generation step for architecture:theme-compilation INV17,
 *   called by generateThemeRules for runtime and static output alike.
 *
 * Each status (`info`, `success`, `warning`, `error`) has one strong fill,
 * `--color-<status>`. A theme that sets a fill, its content, its pale fill, or
 * a surface gets the roles it leaves unset, computed against its own colours:
 * - `--color-on-<status>`: the theme's light or dark content colour
 *   (`--color-on-dark` or `--color-on-light`), whichever contrasts more with
 *   the fill, or pure white or black when neither reaches 4.5:1;
 * - `--color-text-<status>`: the fill's hue at 4.5:1 on surface and card;
 * - `--color-on-<status>-muted`: the fill's hue at 4.5:1 on the pale fill over
 *   the surface.
 * Fills are never derived: a fill a theme does not set is Core's. Icon and
 * border roles alias the text role through the scoped status-role aliases in
 * generateThemeRules, so they are not computed here.
 */

import {colorDefaults} from './tokens.stylex';
import {
  composite,
  contrastRatio,
  isChromatic,
  parseConcreteColor,
  solveLightness,
  toHex,
} from './statusColor';
import type {RGBA} from '../utils/color';

export const STATUS_NAMES = ['info', 'success', 'warning', 'error'] as const;
export type StatusName = (typeof STATUS_NAMES)[number];

type ResolvedThemeMode = 'light' | 'dark';

const TEXT_RATIO = 4.5;
// Solve slightly above the floor so rounding to #RRGGBB never lands below it.
const SOLVE_RATIO = TEXT_RATIO + 0.08;
const MODES: ReadonlyArray<ResolvedThemeMode> = ['light', 'dark'];

/** The strong fill of a status, the source its other roles derive from. */
export function statusSourceToken(status: StatusName): string {
  return `--color-${status}`;
}

function splitTopLevel(input: string): string[] {
  const parts: string[] = [];
  let depth = 0;
  let current = '';
  for (const ch of input) {
    if (ch === '(') {
      depth++;
    }
    if (ch === ')') {
      depth--;
    }
    if (ch === ',' && depth === 0) {
      parts.push(current.trim());
      current = '';
      continue;
    }
    current += ch;
  }
  parts.push(current.trim());
  return parts;
}

/**
 * Resolve one token to a concrete value for a mode, following `light-dark()`
 * and `var()` through the theme's tokens and then Core's colour defaults.
 * This stays local (rather than using tokens.ts) so theme generation does not
 * import the runtime token helpers that themselves depend on defineTheme.
 */
function resolveToken(
  tokens: Record<string, unknown>,
  name: string,
  mode: ResolvedThemeMode,
  seen: ReadonlySet<string> = new Set(),
): string | undefined {
  if (seen.has(name)) {
    return undefined;
  }
  const raw = tokens[name] ?? (colorDefaults as Record<string, string>)[name];
  return resolveValue(tokens, raw, mode, new Set([...seen, name]));
}

function resolveValue(
  tokens: Record<string, unknown>,
  raw: unknown,
  mode: ResolvedThemeMode,
  seen: ReadonlySet<string>,
): string | undefined {
  if (Array.isArray(raw)) {
    return resolveValue(tokens, raw[mode === 'light' ? 0 : 1], mode, seen);
  }
  if (typeof raw !== 'string') {
    return undefined;
  }
  const value = raw.trim();
  if (/^light-dark\(/i.test(value) && value.endsWith(')')) {
    const [light, dark] = splitTopLevel(
      value.slice(value.indexOf('(') + 1, -1),
    );
    return resolveValue(tokens, mode === 'light' ? light : dark, mode, seen);
  }
  const ref = /^var\(\s*(--[\w-]+)\s*(?:,(.*))?\)$/s.exec(value);
  if (ref) {
    const resolved = resolveToken(tokens, ref[1], mode, seen);
    return (
      resolved ??
      (ref[2] ? resolveValue(tokens, ref[2], mode, seen) : undefined)
    );
  }
  return value;
}

const CORE_TOKENS: Record<string, unknown> = {};

function resolveModes(
  tokens: Record<string, unknown>,
): Record<ResolvedThemeMode, Record<string, string>> {
  const names = new Set([
    ...Object.keys(colorDefaults),
    ...Object.keys(tokens),
  ]);
  const at = (mode: ResolvedThemeMode): Record<string, string> => {
    const out: Record<string, string> = {};
    for (const name of names) {
      const value = resolveToken(tokens, name, mode);
      if (value !== undefined) {
        out[name] = value;
      }
    }
    return out;
  };
  return {light: at('light'), dark: at('dark')};
}

let coreCache: Record<ResolvedThemeMode, Record<string, string>> | undefined;
function core(): Record<ResolvedThemeMode, Record<string, string>> {
  coreCache ??= resolveModes(CORE_TOKENS);
  return coreCache;
}

function statusHue(
  status: StatusName,
  resolved: Record<string, string>,
  mode: ResolvedThemeMode,
): RGBA | null {
  const color = parseConcreteColor(resolved[statusSourceToken(status)]);
  if (color !== null && isChromatic(color)) {
    return {...color, a: 1};
  }
  // A grey source falls back to Core's own status hue, so derived text stays
  // chromatic.
  const fallback = parseConcreteColor(core()[mode][statusSourceToken(status)]);
  return fallback === null ? null : {...fallback, a: 1};
}

function opaqueOver(color: RGBA, under: RGBA): RGBA {
  return color.a < 1 ? composite(color, under) : color;
}

interface ModeRoles {
  on?: RGBA;
  text?: RGBA;
  onMuted?: RGBA;
}

function deriveForMode(
  status: StatusName,
  resolved: Record<string, string>,
  mode: ResolvedThemeMode,
): ModeRoles | null {
  // Every colour the computations measure must be concrete. When one is not
  // (an oklch() value, an unknown reference), the status keeps its scoped
  // aliases instead of a guess (architecture:theme-compilation INV17).
  const source = parseConcreteColor(resolved[statusSourceToken(status)]);
  const hue = statusHue(status, resolved, mode);
  const surface = parseConcreteColor(resolved['--color-background-surface']);
  const cardColor = parseConcreteColor(resolved['--color-background-card']);
  const muted = parseConcreteColor(resolved[`--color-${status}-muted`]);
  const onDark = parseConcreteColor(resolved['--color-on-dark']);
  const onLight = parseConcreteColor(resolved['--color-on-light']);
  if (
    source === null ||
    hue === null ||
    surface === null ||
    cardColor === null ||
    muted === null ||
    onDark === null ||
    onLight === null
  ) {
    return null;
  }
  const opaqueSurface = opaqueOver(surface, {r: 255, g: 255, b: 255, a: 1});
  const card = opaqueOver(cardColor, opaqueSurface);
  const fill = opaqueOver(source, opaqueSurface);
  const roles: ModeRoles = {};

  const lightInk = opaqueOver(onDark, fill);
  const darkInk = opaqueOver(onLight, fill);
  const themeInk =
    contrastRatio(lightInk, fill) >= contrastRatio(darkInk, fill)
      ? lightInk
      : darkInk;
  // A theme's off-white and off-black content can both miss the floor on a
  // mid-tone fill; pure white or black always reaches it.
  const white = {r: 255, g: 255, b: 255, a: 1};
  const black = {r: 0, g: 0, b: 0, a: 1};
  roles.on =
    contrastRatio(themeInk, fill) >= TEXT_RATIO
      ? themeInk
      : contrastRatio(white, fill) >= contrastRatio(black, fill)
        ? white
        : black;

  const text = solveLightness(hue, [opaqueSurface, card], SOLVE_RATIO);
  if (text !== null) {
    roles.text = text;
  }

  const pale = composite(muted.a < 1 ? muted : {...muted, a: 1}, opaqueSurface);
  const onMuted = solveLightness(hue, [pale], SOLVE_RATIO);
  if (onMuted !== null) {
    roles.onMuted = onMuted;
  }
  return roles;
}

const ROLE_TOKENS: Record<keyof ModeRoles, (status: StatusName) => string> = {
  on: s => `--color-on-${s}`,
  text: s => `--color-text-${s}`,
  onMuted: s => `--color-on-${s}-muted`,
};

/**
 * Concrete `light-dark()` values for every status role a theme leaves unset
 * while setting a colour that role is measured against. Authored roles are
 * never overridden.
 */
export function deriveStatusRoleTokens(
  tokens: Record<string, string>,
  localTokens: Record<string, string> = {},
): [string, string][] {
  const authored = new Set(Object.keys(tokens));
  const surfaceSet =
    authored.has('--color-background-surface') ||
    authored.has('--color-background-card');
  const inkSet =
    authored.has('--color-on-dark') || authored.has('--color-on-light');
  const resolved = resolveModes({...localTokens, ...tokens});
  const entries: [string, string][] = [];
  for (const status of STATUS_NAMES) {
    const fillSet = authored.has(statusSourceToken(status));
    const mutedSet = authored.has(`--color-${status}-muted`);
    // Which roles this theme's own colours affect.
    const affects: Record<keyof ModeRoles, boolean> = {
      on: fillSet || inkSet,
      text: fillSet || surfaceSet,
      onMuted: fillSet || mutedSet || surfaceSet,
    };
    if (!affects.on && !affects.text && !affects.onMuted) {
      continue;
    }
    const perMode = MODES.map(mode =>
      deriveForMode(status, resolved[mode], mode),
    );
    if (perMode.some(r => r === null)) {
      continue;
    }
    for (const key of Object.keys(ROLE_TOKENS) as (keyof ModeRoles)[]) {
      const token = ROLE_TOKENS[key](status);
      if (!affects[key] || authored.has(token)) {
        continue;
      }
      const [light, dark] = perMode.map(r => r?.[key]);
      if (light === undefined || dark === undefined) {
        continue;
      }
      entries.push([token, `light-dark(${toHex(light)}, ${toHex(dark)})`]);
    }
  }
  return entries;
}