code-theme.js

/**
 * Expressive Code themes for Datasheet.
 *
 * Starlight ships Expressive Code with its own syntax themes, which bake in a
 * full rainbow palette. That is exactly what Datasheet is not: the whole design
 * holds chroma back so the single per-site accent means something. A default
 * syntax theme puts six unrelated hues inside every code block and the page
 * stops reading as one thing.
 *
 * So these are near-monochrome. Structure is carried by weight and by the
 * neutral ramp; the accent appears on strings only, because strings are the
 * part of a config snippet a reader is usually looking for. Comments drop well
 * back — in reference docs they are asides, not content.
 *
 * The accent is baked in at build time rather than referenced as a CSS
 * variable, because Shiki resolves token colours to literal hex while
 * highlighting. That is fine: the accent is known when the plugin is
 * configured, and it cannot change at runtime.
 */

/**
 * @param {object} opts
 * @param {string} opts.accent  Site accent, used for strings.
 * @returns {object} A VS Code style theme object accepted by Expressive Code.
 */
export function datasheetDark({ accent }) {
  const bg = "#0e1014";
  const fg = "#c3c9d4";
  const bright = "#e2e5ec";
  const dim = "#9aa1b0";
  const faint = "#454b57";

  return {
    name: "datasheet-dark",
    type: "dark",
    colors: {
      "editor.background": bg,
      "editor.foreground": fg,
      "editor.selectionBackground": "#232733",
      "editorLineNumber.foreground": faint,
      "editorLineNumber.activeForeground": dim,
    },
    tokenColors: tokens({ fg, bright, dim, faint, accent }),
  };
}

/**
 * @param {object} opts
 * @param {string} opts.accent
 * @returns {object}
 */
export function datasheetLight({ accent }) {
  const bg = "#fbfbf9";
  const fg = "#3a3a36";
  const bright = "#141412";
  const dim = "#6a6a62";
  const faint = "#a8a79e";

  return {
    name: "datasheet-light",
    type: "light",
    colors: {
      "editor.background": bg,
      "editor.foreground": fg,
      "editor.selectionBackground": "#e6e6e0",
      "editorLineNumber.foreground": faint,
      "editorLineNumber.activeForeground": dim,
    },
    tokenColors: tokens({ fg, bright, dim, faint, accent }),
  };
}

/**
 * Shared scope mapping. Four roles only — keyword/identifier, value, muted,
 * comment — deliberately coarse so no snippet ends up speckled.
 */
function tokens({ fg, bright, dim, faint, accent }) {
  return [
    {
      scope: ["comment", "punctuation.definition.comment"],
      settings: { foreground: faint, fontStyle: "italic" },
    },
    {
      scope: [
        "string",
        "string.quoted",
        "string.template",
        "punctuation.definition.string",
      ],
      settings: { foreground: accent },
    },
    {
      scope: [
        "keyword",
        "storage",
        "storage.type",
        "keyword.control",
        "keyword.operator.new",
        "variable.language",
        "constant.language",
      ],
      settings: { foreground: bright, fontStyle: "bold" },
    },
    {
      scope: [
        "entity.name.tag",
        "entity.name.function",
        "support.function",
        "support.type",
        "support.class",
      ],
      settings: { foreground: bright },
    },
    {
      // YAML/TOML/JSON keys — the left-hand column of every options example.
      scope: [
        "entity.name.tag.yaml",
        "support.type.property-name",
        "meta.object-literal.key",
        "variable.other.key",
      ],
      settings: { foreground: bright },
    },
    {
      scope: [
        "constant.numeric",
        "constant.language.boolean",
        "constant.other",
      ],
      settings: { foreground: dim },
    },
    {
      scope: [
        "punctuation",
        "meta.brace",
        "keyword.operator",
        "punctuation.separator",
      ],
      settings: { foreground: dim },
    },
    {
      scope: ["variable", "variable.other", "meta.definition.variable.name"],
      settings: { foreground: fg },
    },
  ];
}

/**
 * Frame chrome — tab bars, borders, copy button — pulled onto the theme's
 * hairlines. These accept CSS variables because they are emitted as CSS, not
 * resolved by Shiki.
 *
 * @returns {object}
 */
export function datasheetStyleOverrides() {
  return {
    borderRadius: "2px",
    borderColor: "var(--sl-color-hairline)",
    codeBackground: "var(--gs-panel)",
    codeFontFamily: "var(--sl-font-mono)",
    uiFontFamily: "var(--sl-font-mono)",
    uiFontSize: "0.6875rem",
    frames: {
      editorBackground: "var(--gs-panel)",
      editorTabBarBackground: "var(--gs-bg)",
      editorTabBarBorderBottomColor: "var(--sl-color-hairline)",
      editorActiveTabBackground: "var(--gs-panel)",
      editorActiveTabForeground: "var(--sl-color-white)",
      editorActiveTabBorderColor: "var(--sl-color-hairline)",
      editorActiveTabIndicatorTopColor: "var(--gs-accent)",
      editorActiveTabIndicatorBottomColor: "transparent",
      terminalBackground: "var(--gs-panel)",
      terminalTitlebarBackground: "var(--gs-bg)",
      terminalTitlebarBorderBottomColor: "var(--sl-color-hairline)",
      terminalTitlebarForeground: "var(--gs-dim)",
      frameBoxShadowCssValue: "none",
    },
  };
}