@geonosis/themekit 1.0.0

package/dist/index.js

@@ -0,0 +1,541 @@
+// src/emit.ts
+var isEach = (emission) => "each" in emission;
+var isMix = (emission) => "mix" in emission;
+var valueAt = (theme, path) => {
+  let current = theme;
+  for (const segment of path.split(".")) {
+    if (typeof current !== "object" || current === null) return void 0;
+    current = current[segment];
+  }
+  return typeof current === "string" && current !== "" ? current : void 0;
+};
+var mapOf = (theme, which) => which === "extra" ? theme.extra ?? {} : theme[which];
+var emitVariables = (theme, emit) => {
+  const variables = {};
+  for (const emission of emit) {
+    if (isEach(emission)) {
+      for (const [key, value2] of Object.entries(mapOf(theme, emission.each))) {
+        variables[`${emission.prefix}${key}`] = value2;
+      }
+      continue;
+    }
+    if (isMix(emission)) {
+      const { amount, role, space = "srgb", with: into } = emission.mix;
+      const from = valueAt(theme, role);
+      if (from === void 0) continue;
+      variables[emission.variable] = `color-mix(in ${space}, ${from} ${amount}, ${into})`;
+      continue;
+    }
+    const value = valueAt(theme, emission.role);
+    if (value !== void 0) variables[emission.variable] = value;
+  }
+  return variables;
+};
+var kebab = (name) => name.replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+var COLOR_ROLES = [
+  "primary",
+  "onPrimary",
+  "secondary",
+  "onSecondary",
+  "accent",
+  "onAccent",
+  "background",
+  "foreground",
+  "surface",
+  "onSurface",
+  "surfaceInverse",
+  "onSurfaceInverse",
+  "muted",
+  "border",
+  "focusRing",
+  "link",
+  "success",
+  "warning",
+  "danger"
+];
+var STATUSES = ["info", "success", "warning", "danger"];
+var defaultEmission = (prefix = "--theme-") => [
+  ...COLOR_ROLES.map((role) => ({ role: `colors.${role}`, variable: `${prefix}${kebab(role)}` })),
+  ...STATUSES.flatMap((status) => [
+    { role: `status.${status}.surface`, variable: `${prefix}${status}-surface` },
+    { role: `status.${status}.onSurface`, variable: `${prefix}on-${status}-surface` }
+  ]),
+  { each: "fonts", prefix: `${prefix}font-` },
+  { each: "radii", prefix: `${prefix}radius-` },
+  { each: "shadows", prefix: `${prefix}shadow-` },
+  { each: "extra", prefix }
+];
+
+// src/compile.ts
+var flatten = (value, path, into) => {
+  if (typeof value === "string") {
+    if (value !== "") into[path] = value;
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, child] of Object.entries(value)) {
+    flatten(child, path === "" ? key : `${path}.${key}`, into);
+  }
+};
+var TOKEN_GROUPS = ["colors", "status", "fonts", "radii", "shadows", "extra"];
+var plainOf = (theme) => {
+  const plain = {};
+  for (const group of TOKEN_GROUPS) flatten(theme[group], group, plain);
+  return plain;
+};
+var block = (selector, entries) => entries.length === 0 ? "" : `${selector} {
+${entries.map(([name, value]) => `  ${name}: ${value};`).join("\n")}
+}
+`;
+var compile = (theme, options = {}) => {
+  const { emit = defaultEmission(), selector = ":root", themeBlock } = options;
+  const cssVariables = emitVariables(theme, emit);
+  const mapped = themeBlock === void 0 ? [] : Object.keys(cssVariables).flatMap((variable) => {
+    const name = themeBlock(variable);
+    return name === void 0 ? [] : [[name, `var(${variable})`]];
+  });
+  return {
+    css: block(selector, Object.entries(cssVariables)),
+    cssVariables,
+    object: theme,
+    plain: plainOf(theme),
+    themeBlock: block("@theme inline", mapped)
+  };
+};
+
+// src/contract.ts
+var defineTheme = (theme) => theme;
+
+// src/dtcg.ts
+var GEONOSIS_EXTENSION = "com.microcompanies.geonosis";
+var PROFILE = "css-values";
+var GROUP_TYPE = {
+  colors: "color",
+  fonts: "fontFamily",
+  radii: "dimension",
+  shadows: "shadow",
+  status: "color"
+};
+var GRADIENT = /^(?:repeating-)?(?:linear|radial|conic)-gradient\(/;
+var extraType = (value) => GRADIENT.test(value) ? "gradient" : "color";
+var typeFor = (path, value) => {
+  const [group = ""] = path.split(".");
+  return group === "extra" ? extraType(value) : GROUP_TYPE[group];
+};
+var tokensOf = (values, path) => {
+  const group = {};
+  for (const [key, value] of Object.entries(values)) {
+    if (value === void 0) continue;
+    group[key] = { $type: typeFor(path, value), $value: value };
+  }
+  return group;
+};
+var statusOf = (theme) => {
+  if (theme.status === void 0) return void 0;
+  const group = {};
+  for (const [status, pair] of Object.entries(theme.status)) {
+    if (pair === void 0) continue;
+    group[status] = tokensOf(pair, "status");
+  }
+  return Object.keys(group).length === 0 ? void 0 : group;
+};
+var toDtcg = (theme) => {
+  const identity = { id: theme.id, name: theme.name, profile: PROFILE };
+  const document = { $extensions: { [GEONOSIS_EXTENSION]: identity } };
+  const groups = [
+    ["colors", theme.colors],
+    ["fonts", theme.fonts],
+    ["radii", theme.radii],
+    ["shadows", theme.shadows],
+    ["extra", theme.extra]
+  ];
+  for (const [name, values] of groups) {
+    if (values === void 0) continue;
+    const tokens = tokensOf(values, name);
+    if (Object.keys(tokens).length > 0) document[name] = tokens;
+  }
+  const status = statusOf(theme);
+  if (status !== void 0) document["status"] = status;
+  return document;
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var valuesOf = (node) => {
+  const values = {};
+  if (!isRecord(node)) return values;
+  for (const [key, token] of Object.entries(node)) {
+    if (key.startsWith("$")) continue;
+    if (isRecord(token) && typeof token["$value"] === "string") values[key] = token["$value"];
+  }
+  return values;
+};
+var fromDtcg = (document) => {
+  const extensions = isRecord(document["$extensions"]) ? document["$extensions"] : {};
+  const identity = isRecord(extensions[GEONOSIS_EXTENSION]) ? extensions[GEONOSIS_EXTENSION] : {};
+  const status = {};
+  if (isRecord(document["status"])) {
+    for (const [name, pair] of Object.entries(document["status"])) {
+      const values = valuesOf(pair);
+      if (values["surface"] !== void 0 && values["onSurface"] !== void 0) {
+        status[name] = { onSurface: values["onSurface"], surface: values["surface"] };
+      }
+    }
+  }
+  const extra = valuesOf(document["extra"]);
+  const theme = {
+    colors: valuesOf(document["colors"]),
+    fonts: valuesOf(document["fonts"]),
+    id: typeof identity["id"] === "string" ? identity["id"] : "",
+    name: typeof identity["name"] === "string" ? identity["name"] : "",
+    radii: valuesOf(document["radii"]),
+    shadows: valuesOf(document["shadows"])
+  };
+  if (document["extra"] !== void 0 && Object.keys(extra).length > 0) theme.extra = extra;
+  if (Object.keys(status).length > 0) theme.status = status;
+  return theme;
+};
+var STRICT_UNHOLDABLE = {
+  // A colour the draft can place needs a colour space and components. `var()` has neither and
+  // `color-mix()` is a computation the file cannot resolve.
+  color: /^(?:var|color-mix|env)\(/,
+  // `{ value, unit }` takes a number and px or rem, so a calc or a var is out.
+  dimension: /^(?:var|calc|clamp|min|max|env)\(|[a-z%]{1,4}$(?<!px|rem)/,
+  fontFamily: null,
+  // Both are composite types with named sub-fields in the draft, and both are stored here as one
+  // whole CSS function or declaration.
+  gradient: /.*/,
+  shadow: /.*/
+};
+var isBrokenToken = (node) => {
+  const keys = Object.keys(node);
+  return keys.length > 0 && keys.every((key) => key.startsWith("$"));
+};
+var walkTokens = (node, path, visit) => {
+  if (!isRecord(node)) return;
+  for (const [key, child] of Object.entries(node)) {
+    if (key.startsWith("$")) continue;
+    const here = path === "" ? key : `${path}.${key}`;
+    if (!isRecord(child)) continue;
+    if ("$value" in child || isBrokenToken(child)) visit(here, child);
+    else walkTokens(child, here, visit);
+  }
+};
+var expectedType = (path, token) => {
+  const [group = ""] = path.split(".");
+  if (group === "extra") {
+    return typeof token["$value"] === "string" ? extraType(token["$value"]) : void 0;
+  }
+  return GROUP_TYPE[group];
+};
+var validateDtcg = (document, options = {}) => {
+  const errors = [];
+  const lossy = [];
+  const extensions = isRecord(document["$extensions"]) ? document["$extensions"] : void 0;
+  const identity = extensions !== void 0 && isRecord(extensions[GEONOSIS_EXTENSION]) ? extensions[GEONOSIS_EXTENSION] : void 0;
+  if (identity === void 0 || typeof identity["id"] !== "string" || identity["id"] === "") {
+    errors.push(
+      `the document carries no brand identity: $extensions["${GEONOSIS_EXTENSION}"].id must be a non-empty string`
+    );
+  }
+  walkTokens(document, "", (path, token) => {
+    if (typeof token["$value"] !== "string" || token["$value"] === "") {
+      errors.push(`${path}: $value must be a non-empty CSS string in the "${PROFILE}" profile`);
+      return;
+    }
+    const expected = expectedType(path, token);
+    if (expected === void 0) {
+      errors.push(`${path}: is in no group this profile knows`);
+      return;
+    }
+    if (token["$type"] !== expected) {
+      errors.push(`${path}: $type is ${String(token["$type"])}, but this group holds ${expected}`);
+    }
+    if (token["$description"] !== void 0) {
+      lossy.push(`${path}: $description is not carried by the tokens contract and will be dropped`);
+    }
+    if (options.strict === true) {
+      const unholdable = STRICT_UNHOLDABLE[expected];
+      if (unholdable !== null && unholdable.test(token["$value"])) {
+        errors.push(
+          `${path}: the DTCG draft's ${expected} $value cannot hold "${token["$value"]}" \u2014 it needs the "${PROFILE}" extension (a CSS string $value)`
+        );
+      }
+    }
+  });
+  return { errors, lossy, valid: errors.length === 0 };
+};
+
+// src/figma.ts
+var KNOWN_GROUPS = /* @__PURE__ */ new Set(["colors", "extra", "fonts", "radii", "shadows", "status"]);
+var isRecord2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isAlias = (value) => isRecord2(value) && value["type"] === "VARIABLE_ALIAS" && typeof value["id"] === "string";
+var isColor = (value) => isRecord2(value) && typeof value["r"] === "number" && typeof value["g"] === "number" && typeof value["b"] === "number";
+var channel = (value) => Math.max(0, Math.min(255, Math.round(value * 255)));
+var hex = (value) => channel(value).toString(16).padStart(2, "0");
+var cssColor = (color) => {
+  const alpha = color.a ?? 1;
+  if (alpha >= 1) return `#${hex(color.r)}${hex(color.g)}${hex(color.b)}`;
+  const rounded = Number(alpha.toFixed(4));
+  return `rgb(${channel(color.r)} ${channel(color.g)} ${channel(color.b)} / ${rounded})`;
+};
+var slug = (name) => name.trim().toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+var extraKey = (name) => slug(name);
+var resolveValue = (variable, modeId, variables, collections) => {
+  const seen = /* @__PURE__ */ new Set();
+  let current = variable;
+  let currentMode = modeId;
+  for (; ; ) {
+    const collection = collections[current.variableCollectionId];
+    const inMode = Object.hasOwn(current.valuesByMode, currentMode) ? currentMode : collection?.defaultModeId ?? "";
+    const value = current.valuesByMode[inMode];
+    if (value === void 0) return { reason: "has no value in this mode or its default" };
+    if (!isAlias(value)) return { value };
+    if (seen.has(value.id)) return { reason: "alias cycle \u2014 it points back at itself" };
+    seen.add(value.id);
+    const next = variables[value.id];
+    if (next === void 0) return { reason: `aliases ${value.id}, which is not in this payload` };
+    current = next;
+    currentMode = inMode;
+  }
+};
+var tokenOf = (variable, value, floatUnit) => {
+  if (variable.resolvedType === "COLOR") {
+    if (!isColor(value)) return { reason: "is a COLOR with a value that is not one" };
+    return { token: { $type: "color", $value: cssColor(value) }, type: "color" };
+  }
+  if (variable.resolvedType === "FLOAT") {
+    if (typeof value !== "number") return { reason: "is a FLOAT with a value that is not a number" };
+    if (floatUnit === void 0) {
+      return {
+        reason: "FLOAT carries no unit in the Figma payload \u2014 set `floatUnit` to say px or rem, because this importer will not guess one"
+      };
+    }
+    return { token: { $type: "dimension", $value: `${value}${floatUnit}` }, type: "dimension" };
+  }
+  if (variable.resolvedType === "STRING") {
+    if (typeof value !== "string") return { reason: "is a STRING with a value that is not one" };
+    return { token: { $type: "fontFamily", $value: value }, type: "fontFamily" };
+  }
+  return {
+    reason: `${variable.resolvedType} has no token type \u2014 it is not a design token this contract models`
+  };
+};
+var place = (document, path, token) => {
+  const segments = path.split(".");
+  let node = document;
+  for (const segment of segments.slice(0, -1)) {
+    if (!isRecord2(node[segment])) node[segment] = {};
+    node = node[segment];
+  }
+  node[segments.at(-1) ?? path] = token;
+};
+var GROUP_TYPE2 = {
+  colors: "color",
+  fonts: "fontFamily",
+  radii: "dimension",
+  shadows: "shadow",
+  status: "color"
+};
+var fromFigmaVariables = (payload, options = {}) => {
+  const { collection: wanted, floatUnit, map = {} } = options;
+  for (const [name, path] of Object.entries(map)) {
+    const [group = ""] = path.split(".");
+    if (!KNOWN_GROUPS.has(group)) {
+      throw new Error(
+        `the map sends "${name}" to "${path}", and "${group}" is not a group this profile knows (${[...KNOWN_GROUPS].toSorted().join(", ")})`
+      );
+    }
+  }
+  const meta = isRecord2(payload["meta"]) ? payload["meta"] : void 0;
+  const variables = isRecord2(meta?.["variables"]) ? meta["variables"] : void 0;
+  const collections = isRecord2(meta?.["variableCollections"]) ? meta["variableCollections"] : void 0;
+  if (variables === void 0 || collections === void 0) {
+    throw new Error(
+      "this is not a Figma variables payload: expected meta.variables and meta.variableCollections, as GET /v1/files/:key/variables/local returns them"
+    );
+  }
+  const candidates = Object.values(collections).filter((one) => (one.modes?.length ?? 0) > 0);
+  const themed = wanted === void 0 ? candidates.toSorted((a, b) => b.modes.length - a.modes.length)[0] : candidates.find((one) => one.name === wanted);
+  if (themed === void 0) {
+    throw new Error(
+      wanted === void 0 ? "no variable collection in this payload has any modes, so there is nothing to make a theme from" : `no variable collection is named "${wanted}"`
+    );
+  }
+  const unsupported = [];
+  const unmapped = /* @__PURE__ */ new Set();
+  const themes = [];
+  const reported = /* @__PURE__ */ new Set();
+  const note = (name, reason) => {
+    if (reported.has(name)) return;
+    reported.add(name);
+    unsupported.push(`${name}: ${reason}`);
+  };
+  for (const mode of themed.modes) {
+    const tokens = {
+      $extensions: {
+        [GEONOSIS_EXTENSION]: { id: slug(mode.name), name: mode.name, profile: PROFILE }
+      }
+    };
+    for (const variable of Object.values(variables)) {
+      const resolved = resolveValue(variable, mode.modeId, variables, collections);
+      if (resolved.value === void 0) {
+        note(variable.name, resolved.reason ?? "could not be resolved");
+        continue;
+      }
+      const built = tokenOf(variable, resolved.value, floatUnit);
+      if ("reason" in built) {
+        note(variable.name, built.reason);
+        continue;
+      }
+      const path = map[variable.name];
+      if (path === void 0) {
+        unmapped.add(variable.name);
+        place(tokens, `extra.${extraKey(variable.name)}`, built.token);
+        continue;
+      }
+      const [group = ""] = path.split(".");
+      const expected = GROUP_TYPE2[group];
+      if (expected !== void 0 && expected !== built.type) {
+        note(
+          variable.name,
+          `is a ${variable.resolvedType} mapped to "${path}", where a ${expected} goes`
+        );
+        continue;
+      }
+      place(tokens, path, built.token);
+    }
+    themes.push({ id: slug(mode.name), name: mode.name, tokens });
+  }
+  return { themes, unmapped: [...unmapped].toSorted(), unsupported };
+};
+
+// src/load.ts
+import { existsSync, readFileSync } from "fs";
+import { basename, dirname, join, resolve } from "path";
+var REQUIRED_COLOR_ROLES = [
+  "background",
+  "border",
+  "danger",
+  "focusRing",
+  "foreground",
+  "muted",
+  "onPrimary",
+  "onSecondary",
+  "onSurface",
+  "primary",
+  "secondary",
+  "success",
+  "surface",
+  "warning"
+];
+var MISSING_ROLES = (theme) => {
+  const colors = theme.colors;
+  return REQUIRED_COLOR_ROLES.filter((role) => {
+    const value = colors[role];
+    return typeof value !== "string" || value === "";
+  }).map((role) => `colors.${role}`);
+};
+var readJson = (dir, file) => {
+  const path = join(dir, file);
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    throw new Error(`${path} could not be read`, { cause: error });
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${path} is not valid JSON: ${error.message}`, { cause: error });
+  }
+};
+var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var manifestOf = (dir) => {
+  if (!existsSync(join(dir, "themekit.json"))) {
+    throw new Error(`${dir} is not a themekit: it has no themekit.json`);
+  }
+  const raw = readJson(dir, "themekit.json");
+  if (!isRecord3(raw)) throw new Error(`${join(dir, "themekit.json")} is not an object`);
+  if (typeof raw["name"] !== "string" || raw["name"] === "") {
+    throw new Error(`${join(dir, "themekit.json")} has no name`);
+  }
+  if (typeof raw["version"] !== "string" || raw["version"] === "") {
+    throw new Error(`${join(dir, "themekit.json")} has no version \u2014 a themekit is consumed by one`);
+  }
+  return {
+    complete: raw["complete"] === true,
+    ...typeof raw["description"] === "string" ? { description: raw["description"] } : {},
+    ...typeof raw["emit"] === "string" ? { emit: raw["emit"] } : {},
+    name: raw["name"],
+    version: raw["version"]
+  };
+};
+var emitOf = (dir, pointer) => {
+  const path = pointer === void 0 ? join(dir, "emit.json") : resolve(dir, pointer);
+  if (!existsSync(path)) {
+    if (pointer === void 0) return defaultEmission();
+    throw new Error(
+      `${join(dir, "themekit.json")} points its emission map at ${path}, which is not there`
+    );
+  }
+  const raw = readJson(dirname(path), basename(path));
+  if (!Array.isArray(raw)) throw new Error(`${path} must be an array of emissions`);
+  return raw;
+};
+var brandOf = (dir, fallback) => {
+  if (!existsSync(join(dir, "brand.json"))) return { id: fallback, name: fallback };
+  const raw = readJson(dir, "brand.json");
+  if (!isRecord3(raw)) throw new Error(`${join(dir, "brand.json")} is not an object`);
+  return {
+    ...raw,
+    id: typeof raw["id"] === "string" ? raw["id"] : fallback,
+    name: typeof raw["name"] === "string" ? raw["name"] : fallback
+  };
+};
+var loadThemekit = (dir, options = {}) => {
+  const manifest = manifestOf(dir);
+  if (options.pinned !== void 0 && options.pinned !== manifest.version) {
+    throw new Error(
+      `${dir} is version ${manifest.version}, but ${options.pinned} was pinned. A themekit is consumed by version: move the pin deliberately, or check out the version you asked for.`
+    );
+  }
+  const tokens = readJson(dir, "theme.tokens.json");
+  if (!isRecord3(tokens)) throw new Error(`${join(dir, "theme.tokens.json")} is not an object`);
+  const report = validateDtcg(tokens);
+  if (!report.valid) {
+    throw new Error(
+      `${join(dir, "theme.tokens.json")} is not this profile:
+  ${report.errors.join("\n  ")}`
+    );
+  }
+  const theme = fromDtcg(tokens);
+  const missingRoles = MISSING_ROLES(theme);
+  if (manifest.complete && missingRoles.length > 0) {
+    throw new Error(
+      `${join(dir, "themekit.json")} says complete, but the theme fills no ${missingRoles.join(", ")}. Set complete to false, or fill the roles.`
+    );
+  }
+  return {
+    brand: brandOf(dir, manifest.name),
+    emit: emitOf(dir, manifest.emit),
+    manifest,
+    missingRoles,
+    theme,
+    tokens
+  };
+};
+export {
+  GEONOSIS_EXTENSION,
+  MISSING_ROLES,
+  PROFILE,
+  REQUIRED_COLOR_ROLES,
+  compile,
+  defaultEmission,
+  defineTheme,
+  emitVariables,
+  fromDtcg,
+  fromFigmaVariables,
+  loadThemekit,
+  toDtcg,
+  validateDtcg,
+  valueAt
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@geonosis/themekit",
+  "version": "1.0.0",
+  "description": "The tokens contract, a variable map that is data, and DTCG in and out — themes as files, never components.",
+  "keywords": [
+    "design-tokens",
+    "dtcg",
+    "theme",
+    "css-variables",
+    "tailwind",
+    "figma",
+    "monorepo"
+  ],
+  "homepage": "https://github.com/microcompanies/geonosis/tree/main/packages/themekit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microcompanies/geonosis.git",
+    "directory": "packages/themekit"
+  },
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  }
+}