@timmo001/groundwork-tokens 0.9.37 → 0.9.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-tokens",
-  "version": "0.9.37",
+  "version": "0.9.39",
   "description": "Groundwork's design tokens: the theme schema, the OKLCH solver and every theme as CSS and JSON",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,6 +10,8 @@
     "./page": "./src/page.ts",
     "./webmcp": "./src/webmcp.ts",
     "./omarchy-current": "./src/omarchy-current.ts",
+    "./desktop-themes": "./src/desktop-themes.ts",
+    "./translate": "./src/translate.ts",
     "./opentui": "./generated/opentui.ts",
     "./themes.css": "./generated/themes.css",
     "./themes.json": "./generated/themes.json",

package/src/desktop-themes.ts

@@ -0,0 +1,253 @@
+/**
+ * The color themes a machine has, translated into mapped themes so an app can
+ * offer them beside its own: every installed Omarchy theme and the theme
+ * each terminal (Ghostty, kitty, Alacritty and foot) uses. It needs a file system, so it's an entry
+ * of its own; drop the ones an app already offers with `distinctThemes`.
+ *
+ * @module
+ */
+import type { Dirent } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+import { omarchyTheme } from "./omarchy.ts";
+import type { MappedTheme } from "./schema.ts";
+import {
+  alacrittyPalette,
+  colorsTomlPalette,
+  distinctThemes,
+  footPalette,
+  ghosttyPalette,
+  kittyPalette,
+  translatePalette,
+  type TerminalPalette,
+} from "./translate.ts";
+
+export { distinctThemes, sameTheme, translatePalette } from "./translate.ts";
+
+/** Where a desktop theme came from, such as `Omarchy` or `Ghostty`. */
+export type DesktopThemeSource =
+  "Omarchy" | "Ghostty" | "kitty" | "Alacritty" | "foot";
+
+const home = homedir();
+
+const config = process.env.XDG_CONFIG_HOME || join(home, ".config");
+const data = process.env.XDG_DATA_HOME || join(home, ".local", "share");
+
+const expand = (path: string, from: string) => {
+  const unquoted = path
+    .trim()
+    .replace(/^\?/, "")
+    .replace(/^["']|["']$/g, "");
+
+  const tilde = unquoted.replace(/^~(?=\/|$)/, home);
+
+  return isAbsolute(tilde) ? tilde : resolve(from, tilde);
+};
+
+const text = (path: string) => readFile(path, "utf8").catch(() => undefined);
+
+const folders = (path: string) =>
+  readdir(path, { withFileTypes: true }).catch((): Dirent[] => []);
+
+const slug = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+
+// `tokyo-night` reads as `Tokyo Night`
+const titled = (value: string) =>
+  value
+    .split(/[-_\s]+/)
+    .filter((word) => word !== "")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+const named = (source: DesktopThemeSource, name: string) => ({
+  id: `desktop-${slug(source)}-${slug(name)}`,
+  name: `${name} (${source})`,
+  family: source,
+});
+
+/** Every Omarchy theme installed, the shipped ones and the user's own. */
+const omarchyThemes = async () => {
+  const found: MappedTheme[] = [];
+
+  for (const root of [
+    join(data, "omarchy", "themes"),
+    join(config, "omarchy", "themes"),
+  ]) {
+    for (const entry of await folders(root)) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+      const folder = join(root, entry.name);
+      const theme = named("Omarchy", titled(entry.name));
+      const colors = await text(join(folder, "colors.toml"));
+
+      const parsed =
+        colors === undefined
+          ? undefined
+          : omarchyTheme(colors, theme.name, theme.id);
+
+      if (parsed?._tag === "Success") {
+        found.push(parsed.success);
+        continue;
+      }
+
+      // Older themes number their colors, or only have each app's file
+      for (const [file, palette] of [
+        ["colors.toml", colorsTomlPalette],
+        ["alacritty.toml", alacrittyPalette],
+        ["ghostty.conf", ghosttyPalette],
+        ["kitty.conf", kittyPalette],
+      ] as const) {
+        const read = await text(join(folder, file));
+
+        const translated =
+          read === undefined
+            ? undefined
+            : translatePalette(palette(read), theme);
+
+        if (translated !== undefined) {
+          found.push(translated);
+          break;
+        }
+      }
+    }
+  }
+
+  return found;
+};
+
+/**
+ * A terminal config with the files it includes, one level deep, joined in
+ * order so later colors win, as the terminal reads them.
+ */
+const withIncludes = async (
+  path: string,
+  include: RegExp,
+  extra: (text: string, from: string) => readonly string[] = () => [],
+) => {
+  const main = await text(path);
+
+  if (main === undefined) return undefined;
+
+  const from = dirname(path);
+  const parts: string[] = [];
+
+  for (const line of main.split(/\r?\n/)) {
+    const match = include.exec(line);
+
+    if (match?.[1] !== undefined) {
+      for (const file of match[1].split(/,\s*/)) {
+        const included = await text(expand(file.replace(/[[\]]/g, ""), from));
+
+        if (included !== undefined) parts.push(included);
+      }
+    }
+  }
+
+  for (const file of extra(main, from)) {
+    const included = await text(file);
+
+    if (included !== undefined) parts.push(included);
+  }
+
+  return [...parts, main].join("\n");
+};
+
+/** Ghostty's theme: its config, the files it pulls in, and a named `theme`. */
+const ghosttyConfig = () =>
+  withIncludes(
+    join(config, "ghostty", "config"),
+    /^\s*config-file\s*=\s*(.+)$/,
+    (main) => {
+      const theme = /^\s*theme\s*=\s*(.+)$/m.exec(main)?.[1]?.trim();
+
+      if (theme === undefined) return [];
+
+      // `light:A,dark:B` takes the dark one
+      const name =
+        /dark:([^,]+)/.exec(theme)?.[1]?.trim() ??
+        theme
+          .replace(/^light:/, "")
+          .split(",")[0]
+          ?.trim() ??
+        theme;
+
+      return [
+        join(config, "ghostty", "themes", name),
+        join("/usr/share/ghostty/themes", name),
+      ];
+    },
+  );
+
+const terminals: readonly {
+  readonly source: DesktopThemeSource;
+  readonly read: () => Promise<string | undefined>;
+  readonly palette: (text: string) => TerminalPalette;
+}[] = [
+  { source: "Ghostty", read: ghosttyConfig, palette: ghosttyPalette },
+  {
+    source: "kitty",
+    read: () =>
+      withIncludes(
+        join(config, "kitty", "kitty.conf"),
+        /^\s*(?:include|globinclude)\s+(.+)$/,
+      ),
+    palette: kittyPalette,
+  },
+  {
+    source: "Alacritty",
+    read: () =>
+      withIncludes(
+        join(config, "alacritty", "alacritty.toml"),
+        /^\s*(?:general\.)?import\s*=\s*\[(.+)\]/,
+      ),
+    palette: alacrittyPalette,
+  },
+  {
+    source: "foot",
+    read: () =>
+      withIncludes(join(config, "foot", "foot.ini"), /^\s*include\s*=\s*(.+)$/),
+    palette: footPalette,
+  },
+];
+
+/** The theme each terminal uses. */
+const terminalThemes = async () => {
+  const found: MappedTheme[] = [];
+
+  for (const terminal of terminals) {
+    const read = await terminal.read();
+
+    if (read === undefined) continue;
+
+    const translated = translatePalette(
+      terminal.palette(read),
+      named(terminal.source, terminal.source),
+    );
+
+    if (translated !== undefined) found.push(translated);
+  }
+
+  return found;
+};
+
+/**
+ * Every theme on the machine, translated: the terminals' first, as the ones
+ * in use, then Omarchy's. Themes that look the same are kept once; pass the
+ * app's own as `existing` to drop those too.
+ */
+export const readDesktopThemes = async (
+  existing: readonly Pick<MappedTheme, "name" | "palette">[] = [],
+): Promise<readonly MappedTheme[]> => {
+  const [terminal, omarchy] = await Promise.all([
+    terminalThemes(),
+    omarchyThemes(),
+  ]);
+
+  return distinctThemes([...terminal, ...omarchy], existing);
+};

package/src/generate.ts

@@ -756,12 +756,12 @@ export const optionalPage = (themes: readonly ResolvedTheme[]) => {
   return [
     "---",
     "title: Optional themes",
-    "description: Catppuccin and Tokyo Night, mapped onto the roles so they stay faithful to their palettes. Apps opt in.",
+    "description: Catppuccin, Tokyo Night and GitHub, mapped onto the roles so they stay faithful to their palettes. Apps opt in.",
     "---",
     "",
     `{/* ${header} */}`,
     "",
-    "Each flavor is one mode of its palette, mapped straight onto the roles rather than solved, so it looks the way the palette's authors intended. They take Base's style. The [contrast report](/themes/contrast) shows where a palette sits below the core targets.",
+    "Most flavors are one mode of their palette, and GitHub's cover both light and dark. Each is mapped straight onto the roles rather than solved, so it looks the way the palette's authors intended. They take Base's style. The [contrast report](/themes/contrast) shows where a palette sits below the core targets.",
     "",
     ...families.flatMap((family) => [
       `## ${family}`,

package/src/page.ts

@@ -11,10 +11,21 @@
  */
 import base from "../themes/base.json" with { type: "json" };
 import bridge from "../themes/bridge.json" with { type: "json" };
+import catppuccinFrappe from "../themes/catppuccin-frappe.json" with { type: "json" };
+import catppuccinLatte from "../themes/catppuccin-latte.json" with { type: "json" };
+import catppuccinMacchiato from "../themes/catppuccin-macchiato.json" with { type: "json" };
+import catppuccinMocha from "../themes/catppuccin-mocha.json" with { type: "json" };
+import githubDimmed from "../themes/github-dimmed.json" with { type: "json" };
+import githubHighContrast from "../themes/github-high-contrast.json" with { type: "json" };
+import github from "../themes/github.json" with { type: "json" };
 import glazing from "../themes/glazing.json" with { type: "json" };
 import slate from "../themes/slate.json" with { type: "json" };
 import snag from "../themes/snag.json" with { type: "json" };
 import survey from "../themes/survey.json" with { type: "json" };
+import tokyoNightDay from "../themes/tokyo-night-day.json" with { type: "json" };
+import tokyoNightMoon from "../themes/tokyo-night-moon.json" with { type: "json" };
+import tokyoNightStorm from "../themes/tokyo-night-storm.json" with { type: "json" };
+import tokyoNight from "../themes/tokyo-night.json" with { type: "json" };
 import type { OmarchyCurrentTheme } from "./omarchy.ts";
 import type { ThemeStore } from "./runtime.ts";
 import type { Theme } from "./schema.ts";
@@ -71,6 +82,8 @@ export interface ThemeChoice {
   readonly id: string;
   readonly name: string;
   readonly mode?: ThemeScheme | undefined;
+  /** The palette an optional theme comes from, such as `Catppuccin`. */
+  readonly family?: string | undefined;
 }
 
 /** Whether `choice` can show in `scheme`. */
@@ -87,6 +100,43 @@ export const coreThemeChoices: readonly ThemeChoice[] = [
   snag,
 ].map(({ id, name }) => ({ id, name }));
 
+/**
+ * The optional themes' documents, by family and then from light to dark.
+ * They're bundled with the module, so an app compiled to one binary has them
+ * without reading `node_modules`. Decode one with the `MappedTheme` Schema.
+ */
+export const optionalThemeDocuments = [
+  catppuccinLatte,
+  catppuccinFrappe,
+  catppuccinMacchiato,
+  catppuccinMocha,
+  tokyoNightDay,
+  tokyoNight,
+  tokyoNightStorm,
+  tokyoNightMoon,
+  github,
+  githubDimmed,
+  githubHighContrast,
+] as const;
+
+/**
+ * The optional themes, mapped from other palettes, by family and then from
+ * light to dark. One with a single mode is offered for that scheme alone;
+ * one with both, such as GitHub's, for either.
+ */
+export const optionalThemeChoices: readonly ThemeChoice[] =
+  optionalThemeDocuments.map((theme) => ({
+    id: theme.id,
+    name: theme.name,
+    family: theme.family,
+    mode:
+      "otherPalette" in theme
+        ? undefined
+        : theme.mode === "light"
+          ? "light"
+          : "dark",
+  }));
+
 export interface PageThemeOptions {
   /** The local storage key prefix, such as `my-site:theme`. */
   readonly key: string;
@@ -101,6 +151,12 @@ export interface PageThemeOptions {
   readonly defaultTheme: string;
   /** The mode to start with. Defaults to `auto`. */
   readonly defaultMode?: ThemeMode;
+  /**
+   * Whether the Omarchy theme takes over while the visitor hasn't picked
+   * one. With `false` it's only offered, and `defaultTheme` stays in use.
+   * Defaults to `true`.
+   */
+  readonly followOmarchy?: boolean;
   /** The element the attributes go on. Defaults to `<html>`. */
   readonly root?: HTMLElement;
   /**
@@ -178,21 +234,26 @@ const write = (key: string, value: string | null) => {
  * defaults as `pageTheme`.
  */
 export const themeBootScript = (
-  options: Pick<PageThemeOptions, "key" | "defaultTheme" | "defaultMode">,
+  options: Pick<
+    PageThemeOptions,
+    "key" | "defaultTheme" | "defaultMode" | "followOmarchy"
+  >,
 ) => {
   const config = JSON.stringify({
     keys: keys(options.key),
     omarchy: omarchyKeys(options.key),
     theme: options.defaultTheme,
     mode: options.defaultMode ?? "auto",
+    follow: options.followOmarchy !== false,
     custom: customThemeId,
     style: customThemeStyleId,
     omarchyId: omarchyThemeId,
     omarchyStyle: omarchyThemeStyleId,
   });
 
-  // With nothing picked, a cached Omarchy theme for the scheme is the default
-  return `(()=>{const c=${config};let s;try{s=localStorage}catch{}const g=(k)=>{try{return s?.getItem(k)??null}catch{return null}};const r=document.documentElement;const a=(id,css)=>{const e=document.createElement("style");e.id=id;e.textContent=css;document.head.append(e)};const m=g(c.keys.mode)??c.mode;const d=m==="dark"||m==="darker"||(m==="auto"&&matchMedia("(prefers-color-scheme: dark)").matches);const o=g(c.omarchy.css);let t=(d?g(c.keys.dark):null)??g(c.keys.theme)??(o&&g(c.omarchy.mode)===(d?"dark":"light")?c.omarchyId:c.theme);if(t===c.custom){const css=g(c.keys.css);if(css)a(c.style,css);else t=c.theme}else if(t===c.omarchyId){if(o)a(c.omarchyStyle,o);else t=c.theme}r.setAttribute("data-gw-theme",t);if(m==="auto")r.removeAttribute("data-gw-mode");else r.setAttribute("data-gw-mode",m)})();`;
+  // With nothing picked, a cached Omarchy theme for the scheme is the
+  // default, unless it's only offered
+  return `(()=>{const c=${config};let s;try{s=localStorage}catch{}const g=(k)=>{try{return s?.getItem(k)??null}catch{return null}};const r=document.documentElement;const a=(id,css)=>{const e=document.createElement("style");e.id=id;e.textContent=css;document.head.append(e)};const m=g(c.keys.mode)??c.mode;const d=m==="dark"||m==="darker"||(m==="auto"&&matchMedia("(prefers-color-scheme: dark)").matches);const o=g(c.omarchy.css);let t=(d?g(c.keys.dark):null)??g(c.keys.theme)??(c.follow&&o&&g(c.omarchy.mode)===(d?"dark":"light")?c.omarchyId:c.theme);if(t===c.custom){const css=g(c.keys.css);if(css)a(c.style,css);else t=c.theme}else if(t===c.omarchyId){if(o)a(c.omarchyStyle,o);else t=c.theme}r.setAttribute("data-gw-theme",t);if(m==="auto")r.removeAttribute("data-gw-mode");else r.setAttribute("data-gw-mode",m)})();`;
 };
 
 /** Reads a theme from JSON text or an Omarchy `colors.toml`. */
@@ -284,9 +345,12 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
       choices().some((theme) => theme.id === id && themeCovers(theme, scheme)));
 
   // The Omarchy theme comes first where it covers the scheme, so the app
-  // matches the desktop until the visitor picks another
+  // matches the desktop until the visitor picks another, unless it's only
+  // offered
   const fallback = (scheme: ThemeScheme) =>
-    omarchy !== null && themeCovers(omarchy, scheme)
+    options.followOmarchy !== false &&
+    omarchy !== null &&
+    themeCovers(omarchy, scheme)
       ? omarchy.id
       : options.themes.some(
             (theme) =>
@@ -437,7 +501,9 @@ export const pageTheme = (options: PageThemeOptions): PageTheme => {
         read(stored.dark),
       ].includes(omarchyThemeId);
 
-      const unpicked = read(stored.theme) === null;
+      const unpicked =
+        options.followOmarchy !== false && read(stored.theme) === null;
+
       let mode: ThemeScheme | undefined;
 
       if (theme !== null) {

package/src/schema.ts

@@ -108,15 +108,19 @@ export interface Palette extends Schema.Schema.Type<typeof Palette> {}
 
 /**
  * An optional theme mapped from an existing palette, such as Catppuccin, so it
- * stays faithful. Each flavor is one mode, and it takes Base's style.
+ * stays faithful. It takes Base's style. Most flavors are one mode; one that
+ * comes in both, such as GitHub's, also gives the other mode's palette.
  */
 export const MappedTheme = Schema.Struct({
   kind: Schema.tag("mapped"),
   id: Schema.String,
   name: Schema.String,
   family: Schema.String,
+  /** The mode `palette` is for. */
   mode: Schema.Literals(["light", "dark"]),
   palette: Palette,
+  /** The other mode's palette, for a theme that covers both. */
+  otherPalette: Schema.optionalKey(Palette),
 });
 
 export interface MappedTheme extends Schema.Schema.Type<typeof MappedTheme> {}

package/src/solve.ts

@@ -14,7 +14,7 @@ import {
   withLightness,
   type Oklch,
 } from "./color.ts";
-import type { MappedTheme, SolvedTheme, Style, Theme } from "./schema.ts";
+import type { Palette, SolvedTheme, Style, Theme } from "./schema.ts";
 
 export const statuses = [
   "info",
@@ -261,18 +261,17 @@ const darker = (dark: Roles, by = 0.045) => {
   };
 };
 
-const mappedRoles = (theme: MappedTheme) => {
+const mappedRoles = (source: Palette, dark: boolean) => {
   const palette = {
-    lower: fromHex(theme.palette.lower),
-    background: fromHex(theme.palette.background),
-    raised: fromHex(theme.palette.raised),
-    border: fromHex(theme.palette.border),
-    text: fromHex(theme.palette.text),
-    muted: fromHex(theme.palette.muted),
-    accent: fromHex(theme.palette.accent),
+    lower: fromHex(source.lower),
+    background: fromHex(source.background),
+    raised: fromHex(source.raised),
+    border: fromHex(source.border),
+    text: fromHex(source.text),
+    muted: fromHex(source.muted),
+    accent: fromHex(source.accent),
   };
 
-  const dark = theme.mode === "dark";
   const away = dark ? 1 : -1;
 
   const surfaces = {
@@ -281,11 +280,11 @@ const mappedRoles = (theme: MappedTheme) => {
   };
 
   const seeds: Record<Status, Oklch> = {
-    info: fromHex(theme.palette.info),
-    success: fromHex(theme.palette.success),
-    important: fromHex(theme.palette.important),
-    warning: fromHex(theme.palette.warning),
-    danger: fromHex(theme.palette.danger),
+    info: fromHex(source.info),
+    success: fromHex(source.success),
+    important: fromHex(source.important),
+    warning: fromHex(source.warning),
+    danger: fromHex(source.danger),
   };
 
   return {
@@ -338,7 +337,20 @@ const mappedStyle = (base: Style): Style => ({
 /** Resolve a theme into roles. Mapped themes take `baseStyle`, Base's style. */
 export const resolve = (theme: Theme, baseStyle: Style): ResolvedTheme => {
   if (theme.kind === "mapped") {
-    const roles = mappedRoles(theme);
+    // `palette` is for its own mode, `otherPalette` for the opposite one
+    const light = theme.mode === "light" ? theme.palette : theme.otherPalette;
+
+    const dark = theme.mode === "dark" ? theme.palette : theme.otherPalette;
+    const modes: Partial<Record<Mode, Roles>> = {};
+
+    if (light !== undefined) modes.light = mappedRoles(light, false);
+
+    if (dark !== undefined) {
+      const roles = mappedRoles(dark, true);
+
+      modes.dark = roles;
+      modes.darker = darker(roles);
+    }
 
     return {
       id: theme.id,
@@ -348,10 +360,7 @@ export const resolve = (theme: Theme, baseStyle: Style): ResolvedTheme => {
       family: theme.family,
       examples: [],
       style: mappedStyle(baseStyle),
-      modes:
-        theme.mode === "dark"
-          ? { dark: roles, darker: darker(roles) }
-          : { light: roles },
+      modes,
     };
   }