@sproutsocial/seeds-theme 0.1.0

package/src/config.js

@@ -0,0 +1,280 @@
+import { loadSeedsPrimitives } from "./primitives.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { buildThemeArtifacts } from "./compiler.js";
+import {
+  assertThemeSelectors,
+  composeTheme,
+  defineTheme,
+  defineThemeExtension,
+} from "./contract.js";
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const manifestFilename = ".seeds-theme-manifest.json";
+
+const isObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+function assertTokenSource(source, label) {
+  if (typeof source !== "string" && !isObject(source)) {
+    throw new TypeError(`${label} must be a DTCG object or a JSON file path.`);
+  }
+}
+
+export function defineProductTheme({
+  name,
+  extensionRoots = [],
+  common = {},
+  light,
+  dark,
+  outputDirectory = "src/theme/generated",
+  selectors,
+}) {
+  if (typeof name !== "string" || !name) {
+    throw new TypeError("Product theme name is required.");
+  }
+  if (!Array.isArray(extensionRoots)) {
+    throw new TypeError("extensionRoots must be an array of token paths.");
+  }
+  assertTokenSource(common, "common");
+  assertTokenSource(light, "light");
+  assertTokenSource(dark, "dark");
+  if (typeof outputDirectory !== "string" || !outputDirectory) {
+    throw new TypeError("outputDirectory must be a non-empty path.");
+  }
+  // A host application owns its own theme and color-mode mechanism, so it may
+  // override the emitted selectors. Validated here so a bad config fails at
+  // definition rather than part-way through a build.
+  if (selectors !== undefined) assertThemeSelectors(selectors);
+
+  return {
+    kind: "product-theme-config",
+    name,
+    extensionRoots: [...extensionRoots],
+    sources: { common, light, dark },
+    outputDirectory,
+    ...(selectors === undefined ? {} : { selectors: { ...selectors } }),
+  };
+}
+
+async function readTokenSource(source, configDirectory) {
+  if (isObject(source)) return structuredClone(source);
+  const filename = path.resolve(configDirectory, source);
+  return JSON.parse(await fs.readFile(filename, "utf8"));
+}
+
+function resolveGeneratedArtifact(outputDirectory, filename) {
+  if (typeof filename !== "string" || !filename) {
+    throw new TypeError("Generated theme manifests must contain file paths.");
+  }
+
+  const normalized = path.normalize(filename);
+  const portableNormalized = normalized.split(path.sep).join("/");
+  const target = path.resolve(outputDirectory, normalized);
+  const relative = path.relative(outputDirectory, target);
+  if (
+    path.isAbsolute(filename) ||
+    portableNormalized !== filename ||
+    relative === "" ||
+    relative === ".." ||
+    relative.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relative)
+  ) {
+    throw new Error(
+      `Generated theme manifest path must stay inside the output directory: ${filename}`
+    );
+  }
+
+  return target;
+}
+
+async function readGeneratedManifest(outputDirectory) {
+  const manifestPath = path.join(outputDirectory, manifestFilename);
+
+  try {
+    const manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
+    if (manifest.version !== 1 || !Array.isArray(manifest.files)) {
+      throw new Error("Unsupported generated theme manifest format.");
+    }
+    return manifest.files.map((filename) => ({
+      filename,
+      path: resolveGeneratedArtifact(outputDirectory, filename),
+    }));
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+async function removeEmptyGeneratedDirectories(outputDirectory, artifacts) {
+  const directories = new Set();
+  for (const { path: artifactPath } of artifacts) {
+    let directory = path.dirname(artifactPath);
+    while (directory !== outputDirectory) {
+      directories.add(directory);
+      directory = path.dirname(directory);
+    }
+  }
+
+  for (const directory of [...directories].sort(
+    (left, right) => right.length - left.length
+  )) {
+    try {
+      await fs.rmdir(directory);
+    } catch (error) {
+      if (error?.code !== "ENOENT" && error?.code !== "ENOTEMPTY") throw error;
+    }
+  }
+}
+
+async function removeGeneratedArtifact(outputDirectory, artifactPath) {
+  let artifact;
+  try {
+    artifact = await fs.lstat(artifactPath);
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+
+  if (artifact.isDirectory()) {
+    throw new Error(
+      `Refusing to recursively remove generated artifact directory: ${artifactPath}`
+    );
+  }
+
+  const [realOutputDirectory, realParentDirectory] = await Promise.all([
+    fs.realpath(outputDirectory),
+    fs.realpath(path.dirname(artifactPath)),
+  ]);
+  const relativeParent = path.relative(
+    realOutputDirectory,
+    realParentDirectory
+  );
+  if (
+    relativeParent === ".." ||
+    relativeParent.startsWith(`..${path.sep}`) ||
+    path.isAbsolute(relativeParent)
+  ) {
+    throw new Error(
+      `Refusing to remove generated artifact through a directory outside the output directory: ${artifactPath}`
+    );
+  }
+
+  await fs.rm(artifactPath);
+}
+
+async function updateGeneratedManifest(
+  outputDirectory,
+  previousArtifacts,
+  generatedFiles
+) {
+  const currentFiles = new Set(generatedFiles);
+  const staleArtifacts = previousArtifacts.filter(
+    ({ filename }) => !currentFiles.has(filename)
+  );
+
+  await Promise.all(
+    staleArtifacts.map(({ path: artifactPath }) =>
+      removeGeneratedArtifact(outputDirectory, artifactPath)
+    )
+  );
+  await removeEmptyGeneratedDirectories(outputDirectory, staleArtifacts);
+  await fs.writeFile(
+    path.join(outputDirectory, manifestFilename),
+    `${JSON.stringify(
+      { version: 1, files: [...currentFiles].sort() },
+      null,
+      2
+    )}\n`
+  );
+}
+
+export async function buildProductTheme(
+  input,
+  {
+    configDirectory = process.cwd(),
+    baseTokenDirectory = path.join(packageRoot, "dist", "source"),
+    primitiveTokens,
+  } = {}
+) {
+  const config =
+    input?.kind === "product-theme-config"
+      ? input
+      : defineProductTheme(input ?? {});
+  const [
+    primitives,
+    baseLight,
+    baseDark,
+    shadcnLight,
+    shadcnDark,
+    common,
+    light,
+    dark,
+  ] = await Promise.all([
+    primitiveTokens
+      ? Promise.resolve(structuredClone(primitiveTokens))
+      : loadSeedsPrimitives(),
+    fs
+      .readFile(
+        path.join(baseTokenDirectory, "theme-light.tokens.json"),
+        "utf8"
+      )
+      .then(JSON.parse),
+    fs
+      .readFile(path.join(baseTokenDirectory, "theme-dark.tokens.json"), "utf8")
+      .then(JSON.parse),
+    fs
+      .readFile(
+        path.join(baseTokenDirectory, "shadcn-light.tokens.json"),
+        "utf8"
+      )
+      .then(JSON.parse),
+    fs
+      .readFile(
+        path.join(baseTokenDirectory, "shadcn-dark.tokens.json"),
+        "utf8"
+      )
+      .then(JSON.parse),
+    readTokenSource(config.sources.common, configDirectory),
+    readTokenSource(config.sources.light, configDirectory),
+    readTokenSource(config.sources.dark, configDirectory),
+  ]);
+
+  const seeds = defineTheme({
+    name: "seeds",
+    common: primitives,
+    modes: {
+      light: { ...baseLight, ...shadcnLight },
+      dark: { ...baseDark, ...shadcnDark },
+    },
+  });
+  const product = defineThemeExtension({
+    name: config.name,
+    extensionRoots: config.extensionRoots,
+    common,
+    modes: { light, dark },
+  });
+  const outputDirectory = path.resolve(configDirectory, config.outputDirectory);
+  const previousArtifacts = await readGeneratedManifest(outputDirectory);
+
+  const generatedFiles = await buildThemeArtifacts(
+    composeTheme(seeds, product),
+    {
+      outputDirectory,
+      ...(config.selectors === undefined
+        ? {}
+        : { selectors: config.selectors }),
+    }
+  );
+  await updateGeneratedManifest(
+    outputDirectory,
+    previousArtifacts,
+    generatedFiles
+  );
+
+  return outputDirectory;
+}

package/src/contract.js

@@ -0,0 +1,351 @@
+import { primitiveRoots } from "./primitives.js";
+const MODES = ["light", "dark"];
+const REFERENCE_PATTERN = /\{([^}]+)\}/g;
+
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+
+const isObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+const isToken = (value) => isObject(value) && hasOwn(value, "$value");
+
+const clone = (value) => structuredClone(value);
+
+function assertTokenTree(value, label) {
+  if (!isObject(value)) {
+    throw new TypeError(`${label} must be a DTCG token object.`);
+  }
+}
+
+function mergeTokenTrees(base, overlay) {
+  if (overlay === undefined) return clone(base);
+  if (base === undefined) return clone(overlay);
+
+  if (isToken(base) || isToken(overlay)) {
+    if (!isToken(overlay)) return clone(overlay);
+    return isToken(base)
+      ? { ...clone(base), ...clone(overlay) }
+      : clone(overlay);
+  }
+
+  if (!isObject(base) || !isObject(overlay)) return clone(overlay);
+
+  const result = clone(base);
+  for (const [key, value] of Object.entries(overlay)) {
+    result[key] = mergeTokenTrees(result[key], value);
+  }
+  return result;
+}
+
+function collectTokens(tree, { allowUntyped = false } = {}) {
+  const tokens = new Map();
+
+  function visit(node, path, inheritedType) {
+    if (!isObject(node)) {
+      throw new TypeError(
+        `Token group ${path.join(".") || "<root>"} must be an object.`
+      );
+    }
+
+    const type = node.$type ?? inheritedType;
+    if (isToken(node)) {
+      const tokenPath = path.join(".");
+      if (!tokenPath) throw new Error("A token cannot exist at the root.");
+      if (!type && !allowUntyped)
+        throw new Error(`Token ${tokenPath} has no $type.`);
+      tokens.set(tokenPath, { node, path, type });
+      return;
+    }
+
+    for (const [key, value] of Object.entries(node)) {
+      if (!key.startsWith("$")) visit(value, [...path, key], type);
+    }
+  }
+
+  visit(tree, [], undefined);
+  return tokens;
+}
+
+function assertSameTokenContract(leftTree, rightTree, labels) {
+  const left = collectTokens(leftTree);
+  const right = collectTokens(rightTree);
+  const paths = new Set([...left.keys(), ...right.keys()]);
+  const errors = [];
+
+  for (const path of [...paths].sort()) {
+    if (!left.has(path)) errors.push(`${labels[0]} is missing ${path}`);
+    else if (!right.has(path)) errors.push(`${labels[1]} is missing ${path}`);
+    else if (left.get(path).type !== right.get(path).type) {
+      errors.push(
+        `${path} changes type from ${left.get(path).type} to ${
+          right.get(path).type
+        }`
+      );
+    }
+  }
+
+  if (errors.length) {
+    throw new Error(`Theme mode contract mismatch:\n- ${errors.join("\n- ")}`);
+  }
+}
+
+function referencesIn(value) {
+  if (typeof value === "string") {
+    return [...value.matchAll(REFERENCE_PATTERN)].map((match) => match[1]);
+  }
+  if (Array.isArray(value)) return value.flatMap(referencesIn);
+  if (isObject(value)) return Object.values(value).flatMap(referencesIn);
+  return [];
+}
+
+function assertReferencesResolve(tree, label) {
+  const tokens = collectTokens(tree);
+  const graph = new Map();
+
+  for (const [path, token] of tokens) {
+    const references = referencesIn(token.node.$value);
+    for (const reference of references) {
+      if (!tokens.has(reference)) {
+        throw new Error(
+          `${label}: ${path} references missing token ${reference}.`
+        );
+      }
+    }
+    graph.set(path, references);
+  }
+
+  const visiting = new Set();
+  const visited = new Set();
+
+  function visit(path, stack) {
+    if (visiting.has(path)) {
+      const cycleStart = stack.indexOf(path);
+      const cycle = [...stack.slice(cycleStart), path];
+      throw new Error(
+        `${label}: token reference cycle: ${cycle.join(" -> ")}.`
+      );
+    }
+    if (visited.has(path)) return;
+
+    visiting.add(path);
+    for (const reference of graph.get(path) ?? []) {
+      visit(reference, [...stack, path]);
+    }
+    visiting.delete(path);
+    visited.add(path);
+  }
+
+  for (const path of graph.keys()) visit(path, []);
+}
+
+function normalizedModes(modes, label) {
+  if (!isObject(modes)) {
+    throw new TypeError(
+      `${label}.modes must contain light and dark token sets.`
+    );
+  }
+
+  for (const mode of MODES) {
+    assertTokenTree(modes[mode], `${label}.modes.${mode}`);
+  }
+
+  return Object.fromEntries(MODES.map((mode) => [mode, clone(modes[mode])]));
+}
+
+function assertName(name, label) {
+  if (typeof name !== "string" || !/^[a-z][a-z0-9-]*$/.test(name)) {
+    throw new TypeError(
+      `${label}.name must be a lowercase kebab-case theme identifier.`
+    );
+  }
+}
+
+export function defineTheme({ name, common = {}, modes }) {
+  assertName(name, "theme");
+  assertTokenTree(common, "theme.common");
+  const theme = {
+    kind: "theme",
+    name,
+    common: clone(common),
+    modes: normalizedModes(modes, "theme"),
+  };
+  const composedModes = Object.fromEntries(
+    MODES.map((mode) => [
+      mode,
+      mergeTokenTrees(theme.common, theme.modes[mode]),
+    ])
+  );
+
+  assertSameTokenContract(composedModes.light, composedModes.dark, MODES);
+  for (const mode of MODES) {
+    assertReferencesResolve(composedModes[mode], `${name}/${mode}`);
+  }
+
+  return theme;
+}
+
+export function defineThemeExtension({
+  name,
+  common = {},
+  modes,
+  extensionRoots = [],
+}) {
+  assertName(name, "extension");
+  assertTokenTree(common, "extension.common");
+  if (
+    !Array.isArray(extensionRoots) ||
+    extensionRoots.some((root) => typeof root !== "string" || !root)
+  ) {
+    throw new TypeError("extension.extensionRoots must be token path strings.");
+  }
+
+  return {
+    kind: "extension",
+    name,
+    common: clone(common),
+    modes: normalizedModes(modes, "extension"),
+    extensionRoots: [...new Set(extensionRoots)],
+  };
+}
+
+function belongsToExtension(path, extensionRoots) {
+  return extensionRoots.some(
+    (root) => path === root || path.startsWith(`${root}.`)
+  );
+}
+
+function validateOverlay(baseTree, overlayTree, extension) {
+  const baseTokens = collectTokens(baseTree);
+  const overlayTokens = collectTokens(overlayTree, { allowUntyped: true });
+
+  for (const [path, token] of overlayTokens) {
+    if (primitiveRoots.has(token.path[0])) {
+      throw new Error(
+        `${extension.name}: ${path} is an external design token; reference it instead of overriding it.`
+      );
+    }
+    const baseToken = baseTokens.get(path);
+    if (!baseToken) {
+      if (!belongsToExtension(path, extension.extensionRoots)) {
+        throw new Error(
+          `${extension.name}: ${path} is not a Seeds token or within a declared extension root.`
+        );
+      }
+      if (!token.type) throw new Error(`Token ${path} has no $type.`);
+      continue;
+    }
+
+    if (token.type && token.type !== baseToken.type) {
+      throw new Error(
+        `${extension.name}: ${path} must remain ${baseToken.type}, received ${token.type}.`
+      );
+    }
+  }
+}
+
+export function composeTheme(baseTheme, ...extensions) {
+  if (baseTheme?.kind !== "theme") {
+    throw new TypeError(
+      "composeTheme requires a theme created by defineTheme."
+    );
+  }
+
+  let name = baseTheme.name;
+  let modes = Object.fromEntries(
+    MODES.map((mode) => [
+      mode,
+      mergeTokenTrees(baseTheme.common, baseTheme.modes[mode]),
+    ])
+  );
+
+  for (const extension of extensions) {
+    if (extension?.kind !== "extension") {
+      throw new TypeError(
+        "composeTheme extensions must be created by defineThemeExtension."
+      );
+    }
+
+    for (const mode of MODES) {
+      validateOverlay(modes[mode], extension.common, extension);
+      const withCommon = mergeTokenTrees(modes[mode], extension.common);
+      validateOverlay(withCommon, extension.modes[mode], extension);
+      modes[mode] = mergeTokenTrees(withCommon, extension.modes[mode]);
+    }
+    name = extension.name;
+  }
+
+  assertSameTokenContract(modes.light, modes.dark, MODES);
+  for (const mode of MODES) {
+    assertReferencesResolve(modes[mode], `${name}/${mode}`);
+  }
+
+  return { name, modes };
+}
+
+const DEFAULT_THEME_NAME = "seeds";
+const DEFAULT_DARK_VARIANT = "&:where(.dark, .dark *)";
+const SELECTOR_KEYS = Object.freeze(["base", "dark", "darkVariant"]);
+
+export function assertThemeSelectors(selectors) {
+  for (const key of SELECTOR_KEYS) {
+    const value = selectors?.[key];
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new TypeError(
+        `Theme selectors must provide a non-empty ${key} string.`
+      );
+    }
+  }
+  if (
+    selectors.darkMedia !== undefined &&
+    (typeof selectors.darkMedia !== "string" || !selectors.darkMedia.trim())
+  ) {
+    throw new TypeError(
+      "Theme selectors darkMedia must be a non-empty media query."
+    );
+  }
+}
+
+export function selectorsForTheme(
+  name,
+  { defaultTheme = DEFAULT_THEME_NAME, mode = "class", darkVariant } = {}
+) {
+  assertName(name, "theme");
+  if (!["class", "attribute", "media"].includes(mode)) {
+    throw new TypeError(
+      'Theme selector mode must be "class", "attribute" or "media".'
+    );
+  }
+
+  // The default theme is the inherited baseline, including when a product is
+  // selected. Its base must keep matching in dark mode because dark is a delta.
+  // Product selectors outrank both baseline blocks regardless of import order.
+  const isDefault = name === defaultTheme;
+  const root = isDefault ? ":root" : `:root[data-theme="${name}"]`;
+
+  if (mode === "media") {
+    return {
+      base: root,
+      dark: root,
+      darkMedia: "(prefers-color-scheme: dark)",
+      darkVariant: darkVariant ?? "@media (prefers-color-scheme: dark)",
+    };
+  }
+
+  return {
+    base: root,
+    // Keep the baseline mode condition at zero specificity so a product's
+    // mode-invariant override also wins over Seeds dark defaults.
+    dark: `${root}${isDefault ? ":where(" : ""}${
+      mode === "class" ? ".dark" : '[data-color-mode="dark"]'
+    }${isDefault ? ")" : ""}`,
+    // Theme-agnostic on purpose: a `dark:` utility should fire for any theme
+    // in dark mode, so this must not be scoped to one `data-theme` value.
+    darkVariant:
+      darkVariant ??
+      (mode === "class"
+        ? DEFAULT_DARK_VARIANT
+        : '&:where([data-color-mode="dark"], [data-color-mode="dark"] *)'),
+  };
+}
+
+export const themeModes = Object.freeze([...MODES]);

package/src/extension-schema.js

@@ -0,0 +1,88 @@
+/** Sparse overrides inherit the Seeds contract; groups can declare types once. */
+export function extensionSchema(graph, primitives = {}) {
+  const references = new Map();
+  function collect(node, path = [], inheritedType) {
+    const type = node.$type ?? inheritedType;
+    if ("$value" in node) {
+      const values = references.get(type) ?? [];
+      values.push(`{${path.join(".")}}`);
+      references.set(type, values);
+      return;
+    }
+    for (const [key, child] of Object.entries(node))
+      if (!key.startsWith("$")) collect(child, [...path, key], type);
+  }
+  collect(primitives);
+  collect(graph);
+  function token(type, description, valueType = "string") {
+    return {
+      type: "object",
+      description,
+      required: ["$value"],
+      additionalProperties: false,
+      properties: {
+        $type: typeof type === "string" ? { const: type } : { enum: type },
+        $value: {
+          description:
+            "Reference existing design tokens or Seeds theme roles. The build validates references.",
+          anyOf: [
+            ...(references.has(type)
+              ? [{ $ref: `#/definitions/${type}References` }]
+              : []),
+            { type: valueType === "number" ? ["number", "string"] : "string" },
+          ],
+        },
+        $description: { type: "string" },
+      },
+    };
+  }
+  function tree(node, inheritedType) {
+    const type = node.$type ?? inheritedType;
+    if ("$value" in node)
+      return token(type, node.$description, typeof node.$value);
+    return {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        ...(type ? { $type: { const: type } } : {}),
+        $description: { type: "string" },
+        ...Object.fromEntries(
+          Object.entries(node)
+            .filter(([name]) => !name.startsWith("$"))
+            .map(([name, child]) => [name, tree(child, type)])
+        ),
+      },
+    };
+  }
+  const schema = tree(graph);
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    definitions: Object.fromEntries(
+      [...references].map(([type, values]) => [
+        `${type}References`,
+        { enum: values },
+      ])
+    ),
+    title: "Seeds theme extension tokens",
+    description:
+      "Override only the theme roles that differ from Seeds in this mode. Primitive packages are reference inputs, not override targets.",
+    ...schema,
+    properties: {
+      $schema: { type: "string" },
+      ...schema.properties,
+      product: {
+        type: "object",
+        description:
+          "Genuinely new product-owned tokens; reuse existing design tokens first.",
+        properties: { $type: { enum: ["color", "dimension", "string"] } },
+        patternProperties: {
+          "^[a-z][a-z0-9-]*$": token(
+            ["color", "dimension", "string"],
+            "Product-owned token"
+          ),
+        },
+        additionalProperties: false,
+      },
+    },
+  };
+}