@sproutsocial/seeds-theme 0.1.0

package/src/compiler.js

@@ -0,0 +1,533 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import StyleDictionary from "style-dictionary";
+import { primitiveRoots } from "./primitives.js";
+import { formattedVariables } from "style-dictionary/utils";
+import {
+  assertThemeSelectors,
+  selectorsForTheme,
+  themeModes,
+} from "./contract.js";
+
+const LEGACY_ABBREVIATIONS = {
+  background: "bg",
+  foreground: "fg",
+};
+
+const SHADCN_COLOR_SLOTS = [
+  "background",
+  "foreground",
+  "card",
+  "card-foreground",
+  "popover",
+  "popover-foreground",
+  "primary",
+  "primary-foreground",
+  "secondary",
+  "secondary-foreground",
+  "muted",
+  "muted-foreground",
+  "accent",
+  "accent-foreground",
+  "destructive",
+  "destructive-foreground",
+  "border",
+  "input",
+  "ring",
+  "chart-1",
+  "chart-2",
+  "chart-3",
+  "chart-4",
+  "chart-5",
+  "sidebar",
+  "sidebar-foreground",
+  "sidebar-primary",
+  "sidebar-primary-foreground",
+  "sidebar-accent",
+  "sidebar-accent-foreground",
+  "sidebar-border",
+  "sidebar-ring",
+];
+
+const isObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isToken = (value) => isObject(value) && "$value" in value;
+const isPrimitiveToken = (token) => primitiveRoots.has(token.path[0]);
+const isShadcnToken = (token) => token.path[0] === "shadcn";
+const isLegacyToken = (token) => token.path[0] === "legacy";
+const isThemeToken = (token) =>
+  !isPrimitiveToken(token) && !isShadcnToken(token) && !isLegacyToken(token);
+
+function kebabCase(value) {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/[_\s]+/g, "-")
+    .toLowerCase();
+}
+
+function cssVariableName(tokenPath, node) {
+  const publicName = node?.$extensions?.["com.sproutsocial.theme"]?.cssName;
+  if (publicName !== undefined) {
+    if (!/^--[a-z][a-z0-9-]*$/.test(publicName))
+      throw new Error(`Invalid public CSS name: ${publicName}`);
+    return publicName;
+  }
+  if (tokenPath[0] === "legacy") {
+    return `--${tokenPath
+      .slice(1)
+      .map((segment) => LEGACY_ABBREVIATIONS[segment] ?? segment)
+      .join("-")}`;
+  }
+
+  if (tokenPath[0] === "css") return `--${tokenPath.slice(1).join("-")}`;
+
+  if (tokenPath[0] === "shadcn") {
+    const pathWithoutNamespace =
+      tokenPath[1] === "color" ? tokenPath.slice(2) : tokenPath.slice(1);
+    return `--${pathWithoutNamespace.join("-")}`;
+  }
+
+  return `--${tokenPath.map(kebabCase).join("-")}`;
+}
+
+function assertNoCssVariableCollisions(tokens, label) {
+  const variables = new Map();
+
+  function visit(node, tokenPath = []) {
+    if (isToken(node)) {
+      const variable = cssVariableName(tokenPath, node);
+      const previous = variables.get(variable);
+      if (
+        previous &&
+        JSON.stringify(previous.value) !== JSON.stringify(node.$value)
+      ) {
+        throw new Error(
+          `${label}: CSS variable ${variable} is generated with conflicting values by both ${
+            previous.path
+          } and ${tokenPath.join(".")}.`
+        );
+      }
+      variables.set(variable, {
+        path: tokenPath.join("."),
+        value: node.$value,
+      });
+      return;
+    }
+
+    if (!isObject(node)) return;
+    for (const [key, value] of Object.entries(node)) {
+      if (!key.startsWith("$")) visit(value, [...tokenPath, key]);
+    }
+  }
+
+  visit(tokens);
+}
+
+// The legacy layer reproduces the selectors `seeds-react-theme` shipped, because
+// keeping existing consumers working is its entire purpose. These are historical
+// facts rather than configuration, so a host does not get to choose them.
+//
+// `data-theme` meant color mode in that contract and identifies a brand in the
+// current one, so the two vocabularies cannot share a selector. An app still on
+// `data-theme="dark"` matches no current-contract block at all, which is why the
+// legacy blocks keep a bare `:root` base. `[data-color-mode="dark"]` is included
+// so an app can adopt the new mode mechanism before it migrates off these names.
+const LEGACY_SELECTORS = Object.freeze({
+  base: ":root",
+  dark: '[data-theme="dark"], .dark, .lights-out, [data-color-mode="dark"]',
+});
+
+function tailwindTheme(shadcn, darkVariant) {
+  const colorMappings = SHADCN_COLOR_SLOTS.filter((slot) => slot in shadcn).map(
+    (slot) => `  --color-${slot}: var(--${slot});`
+  );
+  const radiusMappings =
+    "radius" in shadcn
+      ? [
+          "  --radius-sm: calc(var(--radius) - 4px);",
+          "  --radius-md: calc(var(--radius) - 2px);",
+          "  --radius-lg: var(--radius);",
+          "  --radius-xl: calc(var(--radius) + 4px);",
+        ]
+      : [];
+
+  return `@custom-variant dark (${darkVariant});
+
+@theme inline {
+${[...colorMappings, ...radiusMappings].join("\n")}
+}
+`;
+}
+
+function selectRoots(tokens, predicate) {
+  return Object.fromEntries(
+    Object.entries(tokens)
+      .filter(([key]) => !key.startsWith("$"))
+      .filter(([key]) => predicate({ path: [key] }))
+      .map(([key, value]) => [key, structuredClone(value)])
+  );
+}
+
+function linesFor(dictionary, predicate, excludedNames = new Set()) {
+  const allTokens = dictionary.allTokens.filter(
+    (token) => predicate(token) && !excludedNames.has(`--${token.name}`)
+  );
+  if (allTokens.length === 0) return [];
+
+  return formattedVariables({
+    format: "css",
+    dictionary: { ...dictionary, allTokens },
+    outputReferences: true,
+    usesDtcg: true,
+    formatting: { indentation: "  " },
+  }).split("\n");
+}
+
+function variableName(line) {
+  return line.match(/^\s*(--[^:]+):/)?.[1];
+}
+
+function changedLines(lightLines, darkLines) {
+  const lightByName = new Map(
+    lightLines.map((line) => [variableName(line), line.trim()])
+  );
+  return darkLines.filter(
+    (line) => lightByName.get(variableName(line)) !== line.trim()
+  );
+}
+
+function cssBlock(selector, lines) {
+  if (lines.length === 0) return "";
+  return `${selector} {\n${lines.join("\n")}\n}\n`;
+}
+
+function darkCssBlock(selectors, lines) {
+  const block = cssBlock(selectors.dark, lines);
+  if (!block) return block;
+  return selectors.darkMedia
+    ? `@media ${selectors.darkMedia} {\n${block}}\n`
+    : block;
+}
+
+/** Compare declarations with references intact so inherited aliases remain live. */
+export async function compileExtensionCss(product, baseline, selectors) {
+  const layers = {};
+  for (const [name, theme] of Object.entries({ product, baseline })) {
+    layers[name] = {};
+    for (const mode of themeModes) {
+      assertNoCssVariableCollisions(theme.modes[mode], `${theme.name}/${mode}`);
+      const dictionary = await styleDictionary(
+        theme,
+        mode,
+        "."
+      ).getPlatformTokens("css");
+      layers[name][mode] = linesFor(dictionary, isThemeToken);
+    }
+  }
+  const light = changedLines(layers.baseline.light, layers.product.light);
+  // Product base outranks Seeds dark. Reset any light override that differs from
+  // the desired dark value, including when that value matches Seeds again.
+  const dark = changedLines(
+    [...layers.baseline.dark, ...light],
+    layers.product.dark
+  );
+  return `/* Generated extension of Seeds. Do not edit. */\n${cssBlock(
+    selectors.base,
+    light
+  )}${darkCssBlock(selectors, dark)}`;
+}
+
+function withImports(imports, blocks) {
+  const importsCss = imports
+    .map((filename) => `@import "${filename}";`)
+    .join("\n");
+  const blocksCss = blocks.filter(Boolean).join("\n");
+  return `${importsCss}${importsCss && blocksCss ? "\n\n" : ""}${blocksCss}`;
+}
+
+function shadcnValues(dictionary) {
+  const result = {};
+  for (const token of dictionary.allTokens.filter(
+    (token) => isShadcnToken(token) || token.path[0] === "css"
+  )) {
+    const pathWithoutNamespace =
+      token.path[1] === "color" ? token.path.slice(2) : token.path.slice(1);
+    const slot = pathWithoutNamespace.join("-");
+    if (SHADCN_COLOR_SLOTS.includes(slot) || slot === "radius") {
+      result[slot] = token.$value;
+    }
+  }
+  return result;
+}
+
+function styleDictionary(theme, mode, outputDirectory) {
+  const jsonFiles = [
+    {
+      destination: `theme-${mode}.json`,
+      format: "json/nested",
+      filter: isThemeToken,
+      options: { showFileHeader: false },
+    },
+  ];
+  const javascriptFiles = [
+    {
+      destination: `theme-${mode}.js`,
+      format: "javascript/es6",
+      filter: isThemeToken,
+      options: { showFileHeader: false },
+    },
+    {
+      destination: `theme-${mode}.d.ts`,
+      format: "typescript/es6-declarations",
+      filter: isThemeToken,
+      options: { showFileHeader: false },
+    },
+  ];
+
+  return new StyleDictionary({
+    tokens: theme.modes[mode],
+    log: { verbosity: "silent" },
+    platforms: {
+      css: {
+        transforms: [
+          // Avoid color/css first converting wide-gamut inputs to sRGB.
+          ...StyleDictionary.hooks.transformGroups.css.filter(
+            (name) => name !== "color/css"
+          ),
+          "seeds/theme/css-name",
+          "seeds/theme/css-value",
+          "seeds/theme/css-color",
+          "seeds/theme/legacy-value",
+          "seeds/theme/primitive-value",
+        ],
+      },
+      json: {
+        transformGroup: "js",
+        buildPath: `${outputDirectory}${path.sep}`,
+        files: jsonFiles,
+      },
+      javascript: {
+        transformGroup: "js",
+        buildPath: `${outputDirectory}${path.sep}`,
+        files: javascriptFiles,
+      },
+    },
+  });
+}
+
+StyleDictionary.registerTransform({
+  name: "seeds/theme/css-name",
+  type: "name",
+  transform: (token) => cssVariableName(token.path, token.original).slice(2),
+});
+
+StyleDictionary.registerTransform({
+  name: "seeds/theme/css-value",
+  type: "value",
+  filter: (token) =>
+    Boolean(token.original.$extensions?.["com.sproutsocial.theme"]?.cssName),
+  transform: (token) => token.original.$value,
+});
+
+// Style Dictionary owns color conversion. Keep runtime CSS expressions and
+// references intact; those are evaluated by CSS after theme selection.
+StyleDictionary.registerTransform({
+  name: "seeds/theme/css-color",
+  type: "value",
+  filter: (token) =>
+    token.$type === "color" &&
+    !isLegacyToken(token) &&
+    !isPrimitiveToken(token),
+  transform: (token, platform, options) => {
+    const value = token.original.$value;
+    // Already-OKLCH source values retain their authored precision.
+    if (typeof value === "string" && /^oklch\(/i.test(value)) return value;
+    if (
+      typeof value === "string" &&
+      /\{|\b(?:var|color-mix|light-dark|(?:repeating-)?(?:linear|radial|conic)-gradient)\s*\(|\(\s*from\b|^currentcolor$/i.test(
+        value
+      )
+    )
+      return value;
+    return StyleDictionary.hooks.transforms["color/oklch"].transform(
+      { ...token, $value: value },
+      platform,
+      options
+    );
+  },
+});
+
+// Migration data preserves the exact strings emitted by seeds-react-theme,
+// including gradients, var() references, casing, and transparent.
+StyleDictionary.registerTransform({
+  name: "seeds/theme/legacy-value",
+  type: "value",
+  filter: isLegacyToken,
+  transform: (token) => token.original.$value,
+});
+
+// Primitive values remain an input so semantic references resolve and the
+// migration layer can avoid redeclaring names owned by seeds-color.
+StyleDictionary.registerTransform({
+  name: "seeds/theme/primitive-value",
+  type: "value",
+  filter: isPrimitiveToken,
+  transform: (token) => token.original.$value,
+});
+
+export async function buildThemeArtifacts(
+  theme,
+  { outputDirectory, selectors = selectorsForTheme(theme.name) }
+) {
+  if (!outputDirectory) {
+    throw new TypeError("buildThemeArtifacts requires an outputDirectory.");
+  }
+  assertThemeSelectors(selectors);
+
+  await fs.mkdir(path.join(outputDirectory, "source"), { recursive: true });
+  const dictionaries = {};
+
+  for (const mode of themeModes) {
+    assertNoCssVariableCollisions(theme.modes[mode], `${theme.name}/${mode}`);
+    const dictionary = styleDictionary(theme, mode, outputDirectory);
+    await dictionary.buildPlatform("json");
+    await dictionary.buildPlatform("javascript");
+    dictionaries[mode] = await dictionary.getPlatformTokens("css");
+  }
+
+  const primitiveLight = linesFor(dictionaries.light, isPrimitiveToken);
+  const primitiveDark = linesFor(dictionaries.dark, isPrimitiveToken);
+  if (changedLines(primitiveLight, primitiveDark).length > 0) {
+    throw new Error("Primitive tokens must not change between color modes.");
+  }
+
+  // Legacy CSS has always supplied its border/spacing aliases itself. Only the
+  // historical color palette is external to that compatibility entry point.
+  const primitiveNames = new Set(
+    linesFor(dictionaries.light, (token) => token.path[0] === "color").map(
+      variableName
+    )
+  );
+  const layers = Object.fromEntries(
+    themeModes.map((mode) => {
+      const dictionary = dictionaries[mode];
+      return [
+        mode,
+        {
+          theme: linesFor(dictionary, isThemeToken),
+          shadcn: linesFor(dictionary, isShadcnToken),
+          legacy: linesFor(dictionary, isLegacyToken, primitiveNames),
+        },
+      ];
+    })
+  );
+
+  const files = {
+    "theme-light.css": cssBlock(selectors.base, layers.light.theme),
+    "theme-dark.css": darkCssBlock(selectors, layers.dark.theme),
+    "theme.css": withImports(
+      [],
+      [
+        cssBlock(selectors.base, layers.light.theme),
+        darkCssBlock(
+          selectors,
+          changedLines(layers.light.theme, layers.dark.theme)
+        ),
+      ]
+    ),
+    "shadcn-light.css": withImports(
+      ["./theme-light.css", "./tailwind.css"],
+      [cssBlock(selectors.base, layers.light.shadcn)]
+    ),
+    "shadcn-dark.css": withImports(
+      ["./theme-dark.css", "./tailwind.css"],
+      [darkCssBlock(selectors, layers.dark.shadcn)]
+    ),
+    "shadcn.css": withImports(
+      ["./theme.css", "./tailwind.css"],
+      [
+        cssBlock(selectors.base, layers.light.shadcn),
+        darkCssBlock(
+          selectors,
+          changedLines(layers.light.shadcn, layers.dark.shadcn)
+        ),
+      ]
+    ),
+    "legacy-light.css": withImports(
+      ["./theme-light.css"],
+      [cssBlock(LEGACY_SELECTORS.base, layers.light.legacy)]
+    ),
+    "legacy-dark.css": withImports(
+      ["./theme-dark.css"],
+      [cssBlock(LEGACY_SELECTORS.dark, layers.dark.legacy)]
+    ),
+    "legacy.css": withImports(
+      ["./theme.css"],
+      [
+        cssBlock(LEGACY_SELECTORS.base, layers.light.legacy),
+        cssBlock(
+          LEGACY_SELECTORS.dark,
+          changedLines(layers.light.legacy, layers.dark.legacy)
+        ),
+      ]
+    ),
+  };
+
+  const rawLayers = {
+    "theme-light": selectRoots(theme.modes.light, isThemeToken),
+    "theme-dark": selectRoots(theme.modes.dark, isThemeToken),
+    "shadcn-light": selectRoots(
+      theme.modes.light,
+      (token) => isShadcnToken(token) || token.path[0] === "css"
+    ),
+    "shadcn-dark": selectRoots(
+      theme.modes.dark,
+      (token) => isShadcnToken(token) || token.path[0] === "css"
+    ),
+  };
+  const shadcn = Object.fromEntries(
+    themeModes.map((mode) => [mode, shadcnValues(dictionaries[mode])])
+  );
+
+  await Promise.all([
+    ...Object.entries(files).map(([filename, content]) =>
+      fs.writeFile(path.join(outputDirectory, filename), content)
+    ),
+    ...Object.entries(rawLayers).map(([name, tokens]) =>
+      fs.writeFile(
+        path.join(outputDirectory, "source", `${name}.tokens.json`),
+        `${JSON.stringify(tokens, null, 2)}\n`
+      )
+    ),
+    fs.writeFile(
+      path.join(outputDirectory, "tailwind.css"),
+      tailwindTheme(shadcn.light, selectors.darkVariant)
+    ),
+    fs.writeFile(
+      path.join(outputDirectory, "shadcn.registry.json"),
+      `${JSON.stringify(
+        {
+          $schema: "https://ui.shadcn.com/schema/registry-item.json",
+          name: theme.name,
+          type: "registry:theme",
+          cssVars: shadcn,
+        },
+        null,
+        2
+      )}\n`
+    ),
+  ]);
+
+  return [
+    ...Object.keys(files),
+    ...Object.keys(rawLayers).map((name) => `source/${name}.tokens.json`),
+    ...themeModes.flatMap((mode) => [
+      `theme-${mode}.json`,
+      `theme-${mode}.js`,
+      `theme-${mode}.d.ts`,
+    ]),
+    "tailwind.css",
+    "shadcn.registry.json",
+  ].sort();
+}

package/src/config.d.ts

@@ -0,0 +1,39 @@
+import type { DtcgTokenTree, ThemeSelectors } from "./index.js";
+
+export type ProductThemeTokenSource = DtcgTokenTree | string;
+
+export type ProductThemeInput = {
+  name: string;
+  extensionRoots?: string[];
+  common?: ProductThemeTokenSource;
+  light: ProductThemeTokenSource;
+  dark: ProductThemeTokenSource;
+  outputDirectory?: string;
+  selectors?: ThemeSelectors;
+};
+
+export type ProductThemeConfig = {
+  kind: "product-theme-config";
+  name: string;
+  extensionRoots: string[];
+  sources: {
+    common: ProductThemeTokenSource;
+    light: ProductThemeTokenSource;
+    dark: ProductThemeTokenSource;
+  };
+  outputDirectory: string;
+  selectors?: ThemeSelectors;
+};
+
+export function defineProductTheme(
+  input: ProductThemeInput
+): ProductThemeConfig;
+
+export function buildProductTheme(
+  config: ProductThemeConfig | ProductThemeInput,
+  options?: {
+    configDirectory?: string;
+    baseTokenDirectory?: string;
+    primitiveTokens?: DtcgTokenTree;
+  }
+): Promise<string>;