okchroma 0.7.0 → 0.8.0

package/README.md

@@ -63,7 +63,9 @@ example: [Install and API](https://egerrity.github.io/okchroma/#/docs/install).
 Every token has one path, and every output spells it: `brand/stamp/fill`,
 `neutral/paper-0`, `link/default/enabled`, `absolute/brand`. Joined with hyphens it is the
 CSS custom property (`--brand-stamp-fill`); joined with slashes it is the Figma variable
-and the DTCG token path.
+and the DTCG token path. A consumer whose paths start with the category puts a `color`
+group in front: the extended plugin writes `color/brand/stamp/fill`, and the DTCG
+documents nest under the same word when asked. The CSS names never carry it.
 
 | Group | Tokens |
 |---|---|
@@ -101,7 +103,8 @@ component renders the border unconditionally and layout never shifts.
   every token with `$type`, an sRGB `$value` whose components and hex are the same 8-bit
   color (or an alias where the CSS writes a reference), and a `$description`. The two join
   through a resolver document. The format: [docs/schema.md](docs/schema.md). The repo's
-  `npm run tokens:emit -- '#E93D82' acme` writes both files.
+  `npm run tokens:emit -- '#E93D82' acme` writes both files. Pass `{ rootGroup: 'color' }`,
+  or `--root color` to the script, to nest every path and alias under that group.
 - Figma: `themeToFigma` returns a light and a dark group tree on the same paths; the
   extended plugin writes it into a file.
 

package/dist-lib/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   ABSOLUTE_GROUP: () => ABSOLUTE_GROUP,
   BAND_STOPS: () => BAND_STOPS,
+  COLOR_GROUP: () => COLOR_GROUP,
   CSS_FAMILY: () => CSS_FAMILY,
   DEFAULT_LINK_HEX: () => DEFAULT_LINK_HEX,
   GUARANTEE_SCOPE: () => GUARANTEE_SCOPE,
@@ -865,6 +866,7 @@ var LINK_STATES = ["enabled", "hover", "pressed"];
 var linkPath = (posture, state) => [LINK_GROUP, posture, state];
 var ABSOLUTE_GROUP = "absolute";
 var absolutePath = (family) => [ABSOLUTE_GROUP, family];
+var COLOR_GROUP = "color";
 var TOKEN_ORDER = [
   ...Object.values(SHARED_NAMES),
   STAMP_FILL,
@@ -2911,6 +2913,7 @@ var ZONE_MAP = [
   ["system/abs-alt", "absolute/brand-alt"],
   ["system/abs-primary", "absolute/brand"],
   ["system/link/", "link/"],
+  ["color/", ""],
   ["base/", ""],
   ["primitive/", ""]
 ];
@@ -4050,7 +4053,11 @@ function dtcgColor(value) {
   throw new Error(`dtcgColor: not a color the emitters write: ${value}`);
 }
 var ALIAS = /^var\(--([a-z0-9-]+)\)$/;
-function tokensToDtcg(tokens) {
+var SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function tokensToDtcg(tokens, options = {}) {
+  const { rootGroup } = options;
+  if (rootGroup !== void 0 && !SEGMENT.test(rootGroup)) throw new Error(`tokensToDtcg: rootGroup must be lower-case words and digits joined by hyphens: ${JSON.stringify(rootGroup)}`);
+  const rooted = (path) => rootGroup === void 0 ? path : [rootGroup, ...path];
   const paths = byName();
   const roster = new Set(paths.keys());
   for (const name of tokens.names) if (!roster.has(name)) throw new Error(`tokensToDtcg: the emit carries a name the roster does not know: ${name}`);
@@ -4064,14 +4071,14 @@ function tokensToDtcg(tokens) {
       if (alias) {
         const target = paths.get(alias[1]);
         if (!target) throw new Error(`tokensToDtcg: ${name} references a name outside the roster: ${alias[1]}`);
-        token = { $type: "color", $value: `{${target.join(".")}}` };
+        token = { $type: "color", $value: `{${rooted(target).join(".")}}` };
       } else {
         token = { $type: "color", $value: dtcgColor(tokens[mode][name]) };
       }
       const body = describeDocument(figmaPathOf(path));
       if (body) token.$description = body;
       let cur = doc;
-      for (const seg of path.slice(0, -1)) {
+      for (const seg of rooted(path).slice(0, -1)) {
         const next = cur[seg];
         if (next && "$type" in next) throw new Error(`tokensToDtcg: ${seg} is both a token and a group on the way to ${path.join("/")}`);
         cur = cur[seg] ?? (cur[seg] = {});

package/dist-lib/index.mjs

@@ -773,6 +773,7 @@ var LINK_STATES = ["enabled", "hover", "pressed"];
 var linkPath = (posture, state) => [LINK_GROUP, posture, state];
 var ABSOLUTE_GROUP = "absolute";
 var absolutePath = (family) => [ABSOLUTE_GROUP, family];
+var COLOR_GROUP = "color";
 var TOKEN_ORDER = [
   ...Object.values(SHARED_NAMES),
   STAMP_FILL,
@@ -2819,6 +2820,7 @@ var ZONE_MAP = [
   ["system/abs-alt", "absolute/brand-alt"],
   ["system/abs-primary", "absolute/brand"],
   ["system/link/", "link/"],
+  ["color/", ""],
   ["base/", ""],
   ["primitive/", ""]
 ];
@@ -3958,7 +3960,11 @@ function dtcgColor(value) {
   throw new Error(`dtcgColor: not a color the emitters write: ${value}`);
 }
 var ALIAS = /^var\(--([a-z0-9-]+)\)$/;
-function tokensToDtcg(tokens) {
+var SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function tokensToDtcg(tokens, options = {}) {
+  const { rootGroup } = options;
+  if (rootGroup !== void 0 && !SEGMENT.test(rootGroup)) throw new Error(`tokensToDtcg: rootGroup must be lower-case words and digits joined by hyphens: ${JSON.stringify(rootGroup)}`);
+  const rooted = (path) => rootGroup === void 0 ? path : [rootGroup, ...path];
   const paths = byName();
   const roster = new Set(paths.keys());
   for (const name of tokens.names) if (!roster.has(name)) throw new Error(`tokensToDtcg: the emit carries a name the roster does not know: ${name}`);
@@ -3972,14 +3978,14 @@ function tokensToDtcg(tokens) {
       if (alias) {
         const target = paths.get(alias[1]);
         if (!target) throw new Error(`tokensToDtcg: ${name} references a name outside the roster: ${alias[1]}`);
-        token = { $type: "color", $value: `{${target.join(".")}}` };
+        token = { $type: "color", $value: `{${rooted(target).join(".")}}` };
       } else {
         token = { $type: "color", $value: dtcgColor(tokens[mode][name]) };
       }
       const body = describeDocument(figmaPathOf(path));
       if (body) token.$description = body;
       let cur = doc;
-      for (const seg of path.slice(0, -1)) {
+      for (const seg of rooted(path).slice(0, -1)) {
         const next = cur[seg];
         if (next && "$type" in next) throw new Error(`tokensToDtcg: ${seg} is both a token and a group on the way to ${path.join("/")}`);
         cur = cur[seg] ?? (cur[seg] = {});
@@ -3995,6 +4001,7 @@ function tokensToDtcg(tokens) {
 export {
   ABSOLUTE_GROUP,
   BAND_STOPS,
+  COLOR_GROUP,
   CSS_FAMILY,
   DEFAULT_LINK_HEX,
   GUARANTEE_SCOPE,

package/dist-lib/types/engine/dtcgRender.d.ts

@@ -28,12 +28,20 @@ export declare function tokenPathOf(name: string): TokenPath | undefined;
 export declare function descriptionPathOf(name: string): string | undefined;
 /** a resolved CSS value (hex, rgba(), transparent) as a DTCG color value */
 export declare function dtcgColor(value: string): DtcgColorValue;
+export type DtcgOptions = {
+    /**
+     * A group to nest every path under, for a consumer whose grammar starts a path with its
+     * category (`color`, the word `COLOR_GROUP` holds). Aliases are written with it
+     * (`{color.brand.pencil-47}`). Omitted, the grammar's groups sit at the document root.
+     */
+    rootGroup?: string;
+};
 /**
  * The two DTCG documents for a structured emit. Every primitive in the roster must be
  * present in the emit and nothing else may be; a missing or foreign name throws, so the
  * emit and the roster cannot drift apart silently.
  */
-export declare function tokensToDtcg(tokens: ThemeTokens): {
+export declare function tokensToDtcg(tokens: ThemeTokens, options?: DtcgOptions): {
     light: DtcgDocument;
     dark: DtcgDocument;
 };

package/dist-lib/types/engine/tokenNames.d.ts

@@ -28,5 +28,6 @@ export type LinkState = (typeof LINK_STATES)[number];
 export declare const linkPath: (posture: LinkPosture, state: LinkState) => string[];
 export declare const ABSOLUTE_GROUP = "absolute";
 export declare const absolutePath: (family: string) => string[];
+export declare const COLOR_GROUP = "color";
 export declare const EXT_OVERRIDABLE_SYSTEM: (p: string) => boolean;
 export declare function tokenOrder(name: string): number;

package/dist-lib/types/index.d.ts

@@ -4,9 +4,9 @@ export { brandCss, neutralCss, signalsCss, stopsToVars, toHex, stopHex, OFFSET_A
 export { CSS_FAMILY, describeToken, describeDocument, GUARANTEE_SCOPE, BAND_STOPS } from './engine/tokenDescriptions';
 export { themeTokens, tokensFromEmission, readEmission, resolveReferences, type ThemeTokens, type ThemeTokensInput, type TokenMode, } from './engine/tokensRender';
 export { themeToFigma, groupEntries, type FigmaGroup, type FigmaColorToken, type FigmaLeaf, type ThemeInput, } from './engine/figmaRender';
-export { tokensToDtcg, tokenPathOf, descriptionPathOf, type DtcgDocument, type DtcgGroup, type DtcgToken, type DtcgColorValue, } from './engine/dtcgRender';
+export { tokensToDtcg, tokenPathOf, descriptionPathOf, type DtcgDocument, type DtcgGroup, type DtcgToken, type DtcgColorValue, type DtcgOptions, } from './engine/dtcgRender';
 export { MODE_SPECS, type ModeSpec } from './engine/requirements/spec';
-export { stopTokenName, tokenOrder, SCALE_STOP_COUNT, PAPER_0, PEN_100, STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED, STAMP_EDGE, STAMP_ON, STAMP_STATE_LEAVES, STAMP_LEAF, cssVarName, figmaPathOf, familyPath, linkPath, absolutePath, LINK_GROUP, LINK_POSTURES, LINK_STATES, ABSOLUTE_GROUP, type TokenPath, type LinkPosture, type LinkState, } from './engine/tokenNames';
+export { stopTokenName, tokenOrder, SCALE_STOP_COUNT, PAPER_0, PEN_100, STAMP_FILL, STAMP_FILL_HOVER, STAMP_FILL_PRESSED, STAMP_EDGE, STAMP_ON, STAMP_STATE_LEAVES, STAMP_LEAF, cssVarName, figmaPathOf, familyPath, linkPath, absolutePath, LINK_GROUP, LINK_POSTURES, LINK_STATES, ABSOLUTE_GROUP, COLOR_GROUP, type TokenPath, type LinkPosture, type LinkState, } from './engine/tokenNames';
 export { SIGNAL_EMIT_NAME } from './engine/signals';
 export { classifyArchetype, type Archetype } from './engine/archetypes';
 export { SIGNALS, type SignalDef } from './engine/signals';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okchroma",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "description": "Color-system engine: one brand hex in, a light and dark set of color primitives out, with the contrast requirements solved during generation; emitted as CSS custom properties, DTCG documents, and Figma variables",
   "repository": {