Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

17.8 KB
Raw Blame
/**
 * Themes an installation imported, rather than the three the UI package ships.
 *
 * A theme is nothing but VALUES for the token contract (`@adelie/ui`'s tokens.ts) — every
 * component reads those names and none of them asks which theme is active, so a theme that
 * arrives as data repaints the whole app with no rebuild and no component knowing. What a shipped
 * theme declares in `themes/<id>.css` an imported one declares in a JSON file, and this module
 * turns that file into the CSS the browser would otherwise have been built with:
 *
 *     :root[data-theme="warm-paper"] { --ui-canvas: … }   ← the theme's light values
 *     :root[data-theme="warm-paper"].dark { … }           ← only what dark changes
 *
 * It lives in core, not in the UI package, because BOTH ends need it and they may not import each
 * other: the server reads the files and serves the stylesheet (it has no React and must not gain
 * one), and the app reads the same files back as data. The token NAMES are the UI package's —
 * they are a contract about components — so what is checked here is the shape and the safety of a
 * value, never whether a name exists; the app adds that judgement where the contract lives.
 *
 * THE BASE RULE REACHES BOTH MODES (`:root[data-theme="x"], :root[data-theme="x"].dark`) so the
 * cascade needs no promise about which sheet came first: a name the theme declares and dark does
 * not change keeps the theme's value in dark mode, exactly as a shipped theme's base rule beats
 * Primer's `.dark` rule. Everything the theme leaves out falls through to the default theme, whose
 * base rule is the bare `:root` — which is why a half-filled theme warns rather than fails: it
 * paints, it is just more Primer than its author meant.
 *
 * AND IT CARRIES THE PALETTE BRIDGE. Most of the app still paints with Tailwind palette classes
 * (`bg-white`, `text-gray-500`, `border-gray-200`) rather than the token utilities the contract
 * names, and a shipped theme keeps those following it by re-pointing Tailwind's `--color-gray-*`
 * from its own values — the "gray bridge" at the top of `github.css` and `geek.css`. An imported
 * theme cannot do that for itself (its names are the contract's own), so every theme this module
 * writes gets the same bridge, out of its own tokens: see {@link PALETTE_BRIDGE_LIGHT}.
 *
 * THE LAYERS ARE NAMED (`@layer ui-theme`, `@layer ui-accent`) for the same reason: an unlayered
 * rule beats every layered one, so an imported theme that declared `--ui-font-sans` unlayered
 * would override the user's own font pairing, which lives in `ui-font`, last of the three.
 *
 * A VALUE IS A VALUE. Nothing here is echoed into the sheet without passing {@link SAFE_VALUE},
 * which refuses the characters that would let an imported file leave its declaration — `;`, `{`,
 * `}`, `\`, `<`, a newline, `@` — and the two functions that fetch something (`url(`,
 * `image-set(`). An imported theme is therefore confined to the token names: it cannot add rules,
 * hide an element or call home. That is the whole trade — no new components, no new layout, one
 * set of values per mode.
 */

/** The file shape this module reads. A later shape bumps it rather than half-reading an old file. */
export const EXTERNAL_THEME_SCHEMA_VERSION = 1;

/**
 * The id space of a theme, open: an installation imports themes besides the three the UI package
 * ships, and one pattern covers both — the shipped ids are just short ones. The UI package carries
 * the same pattern for the pre-paint script (`@adelie/ui`'s THEME_ID_PATTERN), and a test in the
 * web app holds the two equal.
 */
export const THEME_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;

/** Whether a stored theme or accent id is one the app may put in a `data-*` attribute. */
export function isThemeId(value: unknown): value is string {
  return typeof value === "string" && THEME_ID_PATTERN.test(value);
}

/** The user-facing names are copy, so they are only bounded — not patterns. */
const NAME = /^[\s\S]{1,60}$/;

/**
 * What a declared value may look like. Length-bounded, one line, and free of the characters that
 * end a declaration, open a block, escape, or — with `url(`/`image-set(` — fetch something.
 */
const SAFE_VALUE = /^[^;{}<>\\@\n\r]{1,120}$/;
const FETCHES = /url\s*\(|image-set\s*\(|expression\s*\(/i;

/** A cap that keeps a runaway file from becoming a megabyte of stylesheet on every page load. */
const MAX_TOKENS = 400;
const MAX_ACCENTS = 12;

/**
 * How big a theme file may be. It lives here, with the format's other caps, because three places
 * have to agree on one number: the reader that refuses an oversized file it finds in the directory,
 * and the two import routes (an upload's bytes, a download's response) that must not write a file
 * the reader would then refuse. The format is values — a few hundred token names and their colours
 * — so the room is generous for what it holds and still nowhere near a megabyte.
 */
export const MAX_THEME_FILE_BYTES = 256 * 1024;

/** One accent preset an imported theme lists, shaped like the shipped themes' own. */
export interface ExternalThemeAccent {
  readonly id: string;
  /** The `--ui-accent` (and anything else the author wants) for light mode. */
  readonly light: Readonly<Record<string, string>>;
  /** Only what dark changes; absent means the light values hold in both modes. */
  readonly dark?: Readonly<Record<string, string>>;
}

/** A theme file, read and validated. */
export interface ExternalTheme {
  readonly id: string;
  /** Its name in the interface. `nameZh` is what a Chinese UI shows; absent falls back to `name`. */
  readonly name: string;
  readonly nameZh?: string;
  /** Every token the theme sets for light — the base both modes start from. */
  readonly light: Readonly<Record<string, string>>;
  readonly dark?: Readonly<Record<string, string>>;
  readonly accents?: readonly ExternalThemeAccent[];
}

export type ExternalThemeRead =
  | { readonly ok: true; readonly theme: ExternalTheme }
  | { readonly ok: false; readonly errors: readonly string[] };

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** One token map: `--ui-*` names only, values as above, within {@link MAX_TOKENS}. */
function readTokens(
  value: unknown,
  where: string,
  errors: string[],
): Record<string, string> | null {
  if (!isPlainObject(value)) {
    errors.push(`${where}: 必须是一个对象(名字 → 值)`);
    return null;
  }
  const entries = Object.entries(value);
  if (entries.length === 0) {
    errors.push(`${where}: 一个名字都没有`);
    return null;
  }
  if (entries.length > MAX_TOKENS) {
    errors.push(`${where}: ${entries.length} 个名字,超过上限 ${MAX_TOKENS}`);
    return null;
  }
  const out: Record<string, string> = {};
  for (const [name, raw] of entries) {
    if (!/^--[a-z0-9-]+$/.test(name)) {
      errors.push(`${where}: 「${name}」不是合法的令牌名(要 --小写-连字符)`);
      continue;
    }
    if (typeof raw !== "string" || !SAFE_VALUE.test(raw) || FETCHES.test(raw)) {
      errors.push(`${where}: 「${name}」的值不能用(不能有 ; { } < \\ @ 换行,也不能 url()`);
      continue;
    }
    out[name] = raw;
  }
  return Object.keys(out).length === 0 ? null : out;
}

function readAccents(value: unknown, errors: string[]): readonly ExternalThemeAccent[] | undefined {
  if (value === undefined) return undefined;
  if (!Array.isArray(value)) {
    errors.push("accents: 要是一个数组");
    return undefined;
  }
  if (value.length > MAX_ACCENTS) {
    errors.push(`accents: ${value.length} 个预设,超过上限 ${MAX_ACCENTS}`);
    return undefined;
  }
  const out: ExternalThemeAccent[] = [];
  const seen = new Set<string>();
  for (const [index, entry] of value.entries()) {
    const where = `accents[${index}]`;
    if (!isPlainObject(entry)) {
      errors.push(`${where}: 要是一个对象`);
      continue;
    }
    const id = entry.id;
    // `neutral` is the absence of a preset, so it can never be one.
    if (typeof id !== "string" || !THEME_ID_PATTERN.test(id) || id === "neutral") {
      errors.push(
        `${where}.id: 「${String(id)}」不是合法的预设名(要小写连字符,且不能叫 neutral)`,
      );
      continue;
    }
    if (seen.has(id)) {
      errors.push(`${where}.id: 「${id}」出现了两次`);
      continue;
    }
    const light = readTokens(entry.light, `${where}.light`, errors);
    if (light === null) continue;
    const dark = entry.dark === undefined ? null : readTokens(entry.dark, `${where}.dark`, errors);
    if (entry.dark !== undefined && dark === null) continue;
    seen.add(id);
    out.push({ id, light, ...(dark === null ? {} : { dark }) });
  }
  return out.length === 0 ? undefined : out;
}

/**
 * Reads a theme file. Errors are collected rather than thrown on the first one: whoever wrote the
 * file gets the whole list, and a file refused here never reaches a stylesheet. The shipped ids
 * are not refused here (this module does not know them); an imported theme can only ever paint
 * under its own `data-theme`, so a file that names a shipped theme simply never matches.
 */
export function readExternalTheme(value: unknown): ExternalThemeRead {
  if (!isPlainObject(value)) return { ok: false, errors: ["顶层必须是一个对象"] };
  const errors: string[] = [];

  const schema = value.schemaVersion;
  if (schema !== undefined && schema !== EXTERNAL_THEME_SCHEMA_VERSION) {
    errors.push(
      `schemaVersion: ${String(schema)} 不是本版本认识的 ${EXTERNAL_THEME_SCHEMA_VERSION}`,
    );
  }
  const id = value.id;
  if (typeof id !== "string" || !THEME_ID_PATTERN.test(id)) {
    errors.push(
      `id: 「${String(id)}」不是合法的主题名(要小写字母开头、小写字母数字连字符,最长 32)`,
    );
  }
  const name = value.name;
  if (typeof name !== "string" || !NAME.test(name)) {
    errors.push("name: 要有 1–60 个字的显示名");
  }
  const nameZh = value.nameZh;
  if (nameZh !== undefined && (typeof nameZh !== "string" || !NAME.test(nameZh))) {
    errors.push("nameZh: 要有 1–60 个字(不写就用 name)");
  }
  const light = readTokens(value.light, "light", errors);
  const dark = value.dark === undefined ? null : readTokens(value.dark, "dark", errors);
  if (value.dark !== undefined && dark === null && errors.length === 0) {
    errors.push("dark: 没有可用的值");
  }
  const accents = readAccents(value.accents, errors);

  if (
    errors.length > 0 ||
    light === null ||
    typeof id !== "string" ||
    typeof name !== "string" ||
    !THEME_ID_PATTERN.test(id)
  ) {
    return { ok: false, errors: errors.length > 0 ? errors : ["文件读不出一个主题"] };
  }
  return {
    ok: true,
    theme: {
      id,
      name,
      ...(typeof nameZh === "string" ? { nameZh } : {}),
      light,
      ...(dark === null ? {} : { dark }),
      ...(accents === undefined ? {} : { accents }),
    },
  };
}

/**
 * The palette bridge, light mode: every Tailwind gray rung the app still paints with, and the
 * contract token whose meaning it carries. `github.css` declares the same correspondence for
 * itself (`--ui-surface-muted` is its `--color-gray-50`, `--ui-line-muted` its `--color-gray-100`,
 * `--ui-line` its `--color-gray-200`, and so on into the ink), and a shipped theme writes the table
 * out by hand because its file IS css. An imported theme cannot: its values are confined to the
 * contract's `--ui-*` names, so a file that arrived as data would leave every `bg-white`,
 * `bg-gray-50` and `text-gray-500` in the app on the default theme's ramp — which is why a dark
 * imported theme showed dark `bg-white` cards (that one rung IS bridged by the default theme, to
 * `var(--ui-surface)`) with white `bg-gray-50` bands, light `border-gray-200` borders and unreadable
 * `text-gray-700` ink beside them. This module writes the bridge for it, out of its own tokens.
 *
 * WHY EVERY VALUE IS A REFERENCE AND NOT A COLOUR. `var(--ui-surface-muted)` is not this theme's
 * `--color-gray-50` — it is whatever that token means in the mode the rule matches, so ONE table
 * serves a light and a dark theme, and a theme that changes a token in `dark` moves the rung with
 * it. A literal would pin the rung to a single mode, which is exactly the failure being fixed.
 */
const PALETTE_BRIDGE_LIGHT: ReadonlyArray<readonly [string, string]> = [
  ["--color-gray-50", "--ui-surface-muted"],
  ["--color-gray-100", "--ui-line-muted"],
  ["--color-gray-200", "--ui-line"],
  ["--color-gray-300", "--ui-line-emphasis"],
  ["--color-gray-400", "--ui-fg-subtle"],
  ["--color-gray-500", "--ui-fg-muted"],
  ["--color-gray-600", "--ui-fg-muted"],
  ["--color-gray-700", "--ui-fg"],
  ["--color-gray-800", "--ui-fg"],
  ["--color-gray-900", "--ui-fg-emphasis"],
  ["--color-gray-950", "--ui-fg-emphasis"],
];

/**
 * The palette bridge, dark mode. The ramp inverts its roles: `dark:` pairs spell the washes, lines
 * and fills on the rungs the light side keeps for ink, and the ink on the rungs it keeps for
 * borders. The rungs follow `geek.css`, the one shipped theme that writes its dark bridge out with
 * its reasons — 100 carries the body ink, 300 and 400 the muted ink, 500 the subtle, 700 and 800
 * the lines, 900 the raised fill a panel sits on and 950 the recessed one.
 *
 * THREE RUNGS DEPART FROM THAT SHAPE, because the app's own usage says its dark ramp is not a pure
 * inversion: 50 stays a wash (nothing in the app spells `dark:*-50`, while `bg-gray-50` is a wash
 * in both modes), 200 follows the lines rather than the ink (its unpaired use is `border-gray-200`,
 * a border either way), and `--color-white` is absent on purpose — the default theme makes it
 * `var(--ui-surface)` in every mode, which is what a card wants and what a text on a fill does not
 * need since those fills are accents.
 */
const PALETTE_BRIDGE_DARK: ReadonlyArray<readonly [string, string]> = [
  ["--color-gray-50", "--ui-surface-muted"],
  ["--color-gray-100", "--ui-fg"],
  ["--color-gray-200", "--ui-line"],
  ["--color-gray-300", "--ui-fg-muted"],
  ["--color-gray-400", "--ui-fg-muted"],
  ["--color-gray-500", "--ui-fg-subtle"],
  ["--color-gray-600", "--ui-fg-subtle"],
  ["--color-gray-700", "--ui-line"],
  ["--color-gray-800", "--ui-line"],
  ["--color-gray-900", "--ui-surface"],
  ["--color-gray-950", "--ui-canvas"],
];

/**
 * One bridge rule's declarations, for the rungs whose token this theme actually declares.
 *
 * A rung whose token the theme leaves out is SKIPPED rather than defaulted: the default theme's
 * own value for that token is often an alias back to the rung being set (`--ui-fg` is
 * `var(--color-gray-900)` there), and a bridge entry pointing at it would make the two names
 * reference each other — a cycle, which css resolves by throwing away BOTH values. The theme's own
 * value is skipped for the same reason: a file that spells `--ui-line: var(--color-gray-200)` wants
 * the default ramp it inherited, not a loop through its own name.
 */
function paletteBridge(
  rungs: ReadonlyArray<readonly [string, string]>,
  declared: Readonly<Record<string, string>>,
): Record<string, string> {
  const out: Record<string, string> = {};
  for (const [name, token] of rungs) {
    const value = declared[token];
    if (value === undefined || value.includes("--color-")) continue;
    out[name] = `var(${token})`;
  }
  return out;
}

function declarations(tokens: Readonly<Record<string, string>>): string {
  return Object.entries(tokens)
    .map(([name, value]) => `${name}:${value}`)
    .join(";");
}

/** The two selectors a theme's base rule matches: the attribute, and itself under `.dark`. */
function roots(id: string, accent: string | null): [string, string] {
  const root =
    accent === null
      ? `:root[data-theme="${id}"]`
      : `:root[data-theme="${id}"][data-accent="${accent}"]`;
  return [root, `${root}.dark`];
}

/** One theme's rules, ready to be concatenated with the others into one stylesheet. */
export function externalThemeCss(theme: ExternalTheme): string {
  const out: string[] = [`/* ${theme.id} — ${theme.name} */`];
  const [base, baseDark] = roots(theme.id, null);
  out.push("@layer ui-theme{");
  out.push(`${base},${baseDark}{${declarations(theme.light)}}`);
  // The palette bridge follows the rule it bridges (and the dark one follows the dark rule, which
  // is what lets it win that selector: both carry `.dark`, so the later rule is the one that holds).
  const lightBridge = paletteBridge(PALETTE_BRIDGE_LIGHT, theme.light);
  if (Object.keys(lightBridge).length > 0) {
    out.push(`${base},${baseDark}{${declarations(lightBridge)}}`);
  }
  const dark = theme.dark;
  if (dark !== undefined && Object.keys(dark).length > 0) {
    out.push(`${baseDark}{${declarations(dark)}}`);
    // A theme with no dark rule keeps its own values in dark mode, and this bridge keeps its light
    // mapping with them; one is emitted only where the theme says what dark changes.
    const darkBridge = paletteBridge(PALETTE_BRIDGE_DARK, { ...theme.light, ...dark });
    if (Object.keys(darkBridge).length > 0) {
      out.push(`${baseDark}{${declarations(darkBridge)}}`);
    }
  }
  out.push("}");
  const accents = theme.accents ?? [];
  if (accents.length > 0) {
    out.push("@layer ui-accent{");
    for (const accent of accents) {
      const [light, dark] = roots(theme.id, accent.id);
      out.push(`${light},${dark}{${declarations(accent.light)}}`);
      if (accent.dark !== undefined && Object.keys(accent.dark).length > 0) {
        out.push(`${dark}{${declarations(accent.dark)}}`);
      }
    }
    out.push("}");
  }
  return out.join("\n");
}

/** Every imported theme's rules in one stylesheet; the shipped themes are not repeated here. */
export function externalThemesCss(themes: readonly ExternalTheme[]): string {
  if (themes.length === 0) return "/* no imported themes */\n";
  return themes.map(externalThemeCss).join("\n") + "\n";
}