@scattered-light/loomiere 0.0.0-stage → 0.1.0

package/lib/lab.mjs

@@ -0,0 +1,108 @@
+/**
+ * The pair lab: a local page for choosing brand pairs.
+ *
+ *   loomiere lab [--brand brand/name.json] [--port 4321]
+ *
+ * Serves tools/pair-lab/ with the brand's built palettes (the theme's generated
+ * primitive color.json, so run loomiere build after changing palettes). Save writes
+ * color.pairs into the brand file, then rebuilds the theme; if the build refuses a pair,
+ * the brand file is put back the way it was.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { engineRoot, readJson, saveAndRebuild, serveTool } from './tool-server.mjs';
+
+const labDir = path.join(engineRoot, 'tools', 'pair-lab');
+
+export function lab(config, { port = 4321 } = {}) {
+  const { brandFile } = config;
+  const brandName = path.basename(brandFile, '.json');
+  const colorFile = path.join(config.generatedDir, 'tokens', 'primitive', 'color.json');
+  if (!fs.existsSync(colorFile)) throw new Error('Build the theme first: loomiere build');
+
+  /** Palettes as the lab draws them: paper and ink first, then each role with its label. */
+  function labData() {
+    const brand = readJson(brandFile);
+    const { color } = readJson(colorFile);
+    const palettes = [
+      {
+        role: 'base',
+        label: 'paper & ink',
+        steps: [
+          { step: 'paper', hex: color.white.$value },
+          { step: 'ink', hex: color.black.$value },
+        ],
+      },
+    ];
+    for (const [role, p] of Object.entries(brand.color.palettes)) {
+      const steps = Object.entries(color[role] ?? {})
+        .filter(([, t]) => typeof t.$value === 'string' && t.$value.startsWith('#'))
+        .map(([step, t]) => ({ step, hex: t.$value }));
+      palettes.push({ role, label: p.label ?? role, steps });
+    }
+    return {
+      brand: brandName,
+      brandName: (brand.name ?? brandName).replace(/^./, (c) => c.toUpperCase()),
+      brandFile: path.relative(config.cwd, brandFile),
+      palettes,
+      pairs: brand.color.pairs ?? {},
+    };
+  }
+
+  const oneLine = (v) =>
+    typeof v === 'object'
+      ? `{ ${Object.entries(v)
+          .map(([k, x]) => `${JSON.stringify(k)}: ${oneLine(x)}`)
+          .join(', ')} }`
+      : JSON.stringify(v);
+
+  /** Index just past the brace that closes the one at `open`, skipping strings. */
+  function closingBrace(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+      const c = text[i];
+      if (c === '"') {
+        for (i++; text[i] !== '"'; i++) if (text[i] === '\\') i++;
+      } else if (c === '{') depth++;
+      else if (c === '}' && --depth === 0) return i + 1;
+    }
+    throw new Error('Unbalanced braces in the brand file');
+  }
+
+  /**
+   * Puts the pairs into the brand file's text, one pair per line, and leaves the rest of the
+   * file (its hand formatting included) alone.
+   */
+  function withPairs(text, pairs) {
+    const indent = text.match(/\n(\s*)"palettes"\s*:/)?.[1] ?? '    ';
+    const entries = Object.entries(pairs).map(([name, spec]) => `${indent}  ${JSON.stringify(name)}: ${oneLine(spec)}`);
+    const block = entries.length ? `"pairs": {\n${entries.join(',\n')}\n${indent}}` : '"pairs": {}';
+    const existing = text.match(/"pairs"\s*:\s*\{/);
+    if (existing) {
+      const open = existing.index + existing[0].length - 1;
+      return text.slice(0, existing.index) + block + text.slice(closingBrace(text, open));
+    }
+    const data = text.match(/\n(\s*)"data"\s*:/);
+    if (data) return `${text.slice(0, data.index)}\n${indent}${block},${text.slice(data.index)}`;
+    const brand = JSON.parse(text);
+    brand.color.pairs = pairs;
+    return `${JSON.stringify(brand, null, 2)}\n`;
+  }
+
+  async function savePairs({ pairs }) {
+    if (!pairs || typeof pairs !== 'object' || Array.isArray(pairs)) throw new Error('Expected { pairs: { name: { bg, fg } } }');
+    const output = await saveAndRebuild(brandFile, withPairs(fs.readFileSync(brandFile, 'utf8'), pairs), config);
+    return { ok: true, output };
+  }
+
+  serveTool({
+    dir: labDir,
+    port,
+    routes: { 'GET /data.json': labData, 'POST /pairs': savePairs },
+    onListen: () => {
+      console.log(`Pair lab for "${brandName}": http://localhost:${port}`);
+      console.log(`Save writes color.pairs to ${path.relative(config.cwd, brandFile)} and rebuilds the theme. Ctrl+C to stop.`);
+    },
+  });
+}

package/lib/studio.mjs

@@ -0,0 +1,127 @@
+/**
+ * The brand studio: a local page for writing a brand file with live previews.
+ *
+ *   loomiere studio [--brand brand/name.json] [--port 4322]
+ *   loomiere studio --export out.html   (one self-contained page, no server)
+ *
+ * The page runs generator/brand.mjs in the browser, so the ramps, type scale and other
+ * previews are exactly what the build makes. Save writes <brand folder>/<name>.json. Saving
+ * the brand the project builds also rebuilds its theme, and if the build refuses the file it
+ * is put back the way it was.
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { formatBrand } from '../generator/format-brand.mjs';
+import { brandFiles, schemaPathFor } from './config.mjs';
+import { engineRoot, readJson, saveAndRebuild, serveTool } from './tool-server.mjs';
+
+const toolDir = path.join(engineRoot, 'tools', 'brand-builder');
+const culoriDir = path.dirname(createRequire(import.meta.url).resolve('culori/package.json'));
+
+/**
+ * Which semantic tokens read each role concept ("chrome.fg" → ["text.primary", …]),
+ * directly or through another semantic token, for the Concepts rows.
+ */
+function conceptUses() {
+  const dir = path.join(engineRoot, 'tokens', 'semantic');
+  const refs = new Map();
+  const walk = (node, at) => {
+    if (node && typeof node === 'object' && '$value' in node) {
+      refs.set(at.join('.'), [...JSON.stringify([node.$value, node.$extensions?.['sl.modes']]).matchAll(/\{([^}]+)\}/g)].map((m) => m[1]));
+      return;
+    }
+    for (const [k, v] of Object.entries(node ?? {})) if (!k.startsWith('$') && typeof v === 'object') walk(v, [...at, k]);
+  };
+  for (const f of fs.readdirSync(dir)) if (!['scope.json', 'emphasis.json', 'pair.json'].includes(f)) walk(readJson(path.join(dir, f)), []);
+  const reaches = (p, seen = new Set()) =>
+    (refs.get(p) ?? []).flatMap((r) => (seen.has(r) ? [] : (seen.add(r), [r, ...reaches(r, seen)])));
+  const uses = {};
+  for (const p of refs.keys()) {
+    for (const r of reaches(p)) {
+      const m = /^scope\.(chrome|accent)\.(.+)$/.exec(r);
+      if (m) (uses[`${m[1]}.${m[2]}`] ??= []).push(p);
+    }
+  }
+  return uses;
+}
+
+export function studio(config, { port = 4322, exportFile } = {}) {
+  const brandDir = path.dirname(config.brandFile);
+  const brandName = path.basename(config.brandFile, '.json');
+  const brandPath = (name) => path.join(brandDir, `${name}.json`);
+  const brands = () => brandFiles(brandDir).map((f) => path.basename(f, '.json'));
+  const schema = schemaPathFor(brandDir, config.cwd);
+
+  function load(name) {
+    if (!brands().includes(name)) throw new Error(`No brand called "${name}"`);
+    const overridesFile = path.join(brandDir, `${name}.overrides.json`);
+    return {
+      name,
+      dir: path.relative(config.cwd, brandDir) || '.',
+      schema,
+      built: name === brandName,
+      brands: brands(),
+      brand: readJson(brandPath(name)),
+      overrides: fs.existsSync(overridesFile) ? readJson(overridesFile) : {},
+      uses: conceptUses(),
+    };
+  }
+
+  async function save({ name, brand }) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name ?? '')) throw new Error('Brand names use a-z, 0-9 and dashes, starting with a letter');
+    if (!brand?.color?.palettes) throw new Error('That does not look like a brand file');
+    const file = brandPath(name);
+    // Object.assign keeps the name second in the file even if the brand carries its own.
+    const text = formatBrand(Object.assign({ $schema: schema, name }, brand, { name }));
+    if (name === brandName) return { ok: true, output: await saveAndRebuild(file, text, config) };
+    fs.writeFileSync(file, text);
+    const rel = path.relative(config.cwd, file);
+    return { ok: true, output: `Saved ${rel}. Build it with loomiere build --brand ${rel}.` };
+  }
+
+  if (exportFile) return exportPage(path.resolve(config.cwd, exportFile), load(brandName));
+  serveTool({
+    dir: toolDir,
+    port,
+    mounts: {
+      '/generator/': path.join(engineRoot, 'generator'),
+      '/vendor/culori/': culoriDir,
+    },
+    routes: {
+      'GET /api/brand': (_, url) => load(url.searchParams.get('name') || brandName),
+      'POST /api/brand': save,
+    },
+    onListen: () => {
+      console.log(`Brand studio for "${brandName}": http://localhost:${port}`);
+      console.log(`Save writes ${path.relative(config.cwd, brandDir) || '.'}/<name>.json; saving "${brandName}" also rebuilds the theme. Ctrl+C to stop.`);
+    },
+  });
+}
+
+/** One HTML file with the script bundled and the brand inlined, for sharing or hosting. */
+async function exportPage(out, data) {
+  let build;
+  try {
+    ({ build } = await import('esbuild'));
+  } catch {
+    throw new Error('Exporting the studio needs esbuild: npm install --save-dev esbuild');
+  }
+  const bundle = await build({
+    entryPoints: [path.join(toolDir, 'builder.js')],
+    bundle: true,
+    format: 'iife',
+    minify: true,
+    write: false,
+    target: 'es2020',
+  });
+  const js = bundle.outputFiles[0].text.replace(/<\/script/gi, '<\\/script');
+  const inline = JSON.stringify({ ...data, built: false, brands: [data.name] }).replace(/</g, '\\u003c');
+  const html = fs
+    .readFileSync(path.join(toolDir, 'index.html'), 'utf8')
+    .replace(/<script type="importmap">[\s\S]*?<\/script>\n?/, '')
+    .replace('<script type="module" src="builder.js"></script>', () => `<script>window.BRAND_DATA = ${inline};</script>\n<script>${js}</script>`);
+  fs.writeFileSync(out, html);
+  console.log(`Wrote ${out} (${Math.round(html.length / 1024)} KB).`);
+}

package/lib/tool-server.mjs

@@ -0,0 +1,96 @@
+/**
+ * Shared plumbing for the local tools (the pair lab and the brand builder): argument
+ * parsing, a small static and JSON server bound to localhost, and saving a brand file
+ * with a rebuild that rolls the file back if the build refuses it.
+ */
+import { execFile } from 'node:child_process';
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** The engine's own folder (generator/, tools/, tokens/). */
+export const engineRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+
+const bin = path.join(engineRoot, 'bin', 'loomiere.mjs');
+
+/** Runs `loomiere build` for the project, as its own process so a failed build can't leave this one half-loaded. */
+const rebuild = (config) =>
+  new Promise((resolve) => {
+    execFile(process.execPath, [bin, 'build', '--brand', config.brandFile], { cwd: config.cwd }, (err, stdout, stderr) =>
+      resolve({ ok: !err, output: `${stdout}${stderr}`.trim() }),
+    );
+  });
+
+/**
+ * Writes a brand file and rebuilds the project's theme from it. If the build fails, the
+ * file goes back to what it was and the error names the build's reason.
+ */
+export async function saveAndRebuild(file, text, config) {
+  JSON.parse(text);
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+  fs.writeFileSync(file, text);
+  const build = await rebuild(config);
+  if (!build.ok) {
+    if (before === null) fs.rmSync(file);
+    else fs.writeFileSync(file, before);
+    const lines = build.output.split('\n').map((line) => line.trim());
+    const reason = lines.filter((line) => /needs|names use|not a palette|falls? short/.test(line)).join('; ');
+    throw new Error(reason || lines.slice(-5).join(' '));
+  }
+  return build.output.split('\n').filter(Boolean).at(-1);
+}
+
+const TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+};
+
+/**
+ * Serves `dir` at / plus any `mounts` ({ '/prefix/': directory }), and JSON `routes`
+ * ({ 'GET /data.json': () => data, 'POST /save': (body) => result }). A route that throws
+ * answers 400 with { ok: false, error }.
+ */
+export function serveTool({ dir, mounts = {}, routes, port, onListen }) {
+  const server = http.createServer(async (req, res) => {
+    const send = (status, body, type = TYPES['.json']) => {
+      res.writeHead(status, { 'content-type': type, 'cache-control': 'no-store' });
+      res.end(typeof body === 'string' ? body : JSON.stringify(body));
+    };
+    try {
+      const url = new URL(req.url, 'http://localhost');
+      const route = routes[`${req.method} ${url.pathname}`];
+      if (route) {
+        let body;
+        if (req.method === 'POST') {
+          let raw = '';
+          for await (const chunk of req) raw += chunk;
+          body = JSON.parse(raw || '{}');
+        }
+        try {
+          return send(200, await route(body, url));
+        } catch (err) {
+          return send(400, { ok: false, error: err.message });
+        }
+      }
+      if (req.method === 'GET') {
+        const prefix = Object.keys(mounts).find((p) => url.pathname.startsWith(p));
+        const base = prefix ? mounts[prefix] : dir;
+        const rel = prefix ? url.pathname.slice(prefix.length) : url.pathname === '/' ? 'index.html' : url.pathname;
+        const file = path.join(base, path.normalize(`/${rel}`));
+        if (file.startsWith(base) && fs.existsSync(file) && fs.statSync(file).isFile()) {
+          return send(200, fs.readFileSync(file, 'utf8'), TYPES[path.extname(file)] ?? 'text/plain; charset=utf-8');
+        }
+      }
+      send(404, { ok: false, error: 'Not found' });
+    } catch (err) {
+      send(500, { ok: false, error: err.message });
+    }
+  });
+  server.listen(port, '127.0.0.1', onListen);
+  return server;
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@scattered-light/loomiere",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Turns a small brand file into a full design token theme: OKLCH color ramps, a type scale, light, dark and high-contrast modes, plus Tailwind, MUI, Chakra, AG Grid and Figma exports.",
+  "keywords": ["design-tokens", "theme", "style-dictionary", "dtcg", "oklch", "base-ui", "ag-grid", "tailwind"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ScatteredLight/loomiere.git",
+    "directory": "packages/loomiere"
+  },
+  "type": "module",
+  "bin": {
+    "loomiere": "./bin/loomiere.mjs"
+  },
+  "exports": {
+    "./build": "./build/build-tokens.mjs",
+    "./config": "./lib/config.mjs",
+    "./contrast": "./lib/contrast.mjs",
+    "./generator/*": "./generator/*",
+    "./exporters/*": "./exporters/*",
+    "./brand.schema.json": "./generator/brand.schema.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "build",
+    "exporters",
+    "generator",
+    "lib",
+    "templates",
+    "tokens",
+    "tools"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "dependencies": {
+    "culori": "^4.0.2",
+    "style-dictionary": "^5.7.0"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.20.0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    }
+  }
+}

package/templates/brand.json

@@ -0,0 +1,104 @@
+{
+  "$schema": "../generator/brand.schema.json",
+  "name": "starter",
+  "description": "Starting point for a new brand, copied from the Mojave demo theme. Change the seed colors, fonts, base unit and type ratio; the generator does the rest.",
+
+  "space": {
+    "unit": 4,
+    "steps": [0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 52, 56, 60, 64, 72, 80, 96]
+  },
+
+  "color": {
+    "paper": "#ffffff",
+    "ink": "#000000",
+    "contrast": {
+      "spot": {
+        "targets": { "50": 1.03, "75": 1.09, "100": 1.18, "200": 1.51, "300": 2.02, "400": 3, "500": 4.5, "600": 6.1, "700": 7.91, "800": 10.87, "900": 14.38, "1000": 17.89 },
+        "locked": [500]
+      },
+      "neutral": {
+        "targets": { "50": 1.04, "100": 1.06, "200": 1.12, "300": 1.19, "400": 1.42, "500": 1.72, "600": 2.16, "700": 2.76, "800": 3.65, "900": 5.08, "1000": 7.31, "1100": 11.08, "1200": 16.83 }
+      }
+    },
+    "palettes": {
+      "neutral": {
+        "label": "stone",
+        "contrast": "neutral",
+        "keys": ["#e7ece4", "#bcccc1"],
+        "exact": true,
+        "tone": { "color": "#bbc9bf", "intensity": [0.1, 0.6] }
+      },
+      "primary": { "label": "mirage", "keys": ["#dbacff", "#973dda", "#402058"], "darkest": "#221928" },
+      "secondary": { "label": "ember", "keys": ["#ed6f52", "#57342b"] },
+      "tertiary": { "label": "dune", "keys": ["#c4b77a", "#7e7758"] },
+      "quaternary": { "label": "silhouette", "keys": ["#b58994", "#612c3d"] },
+      "success": { "keys": ["#22c55e"] },
+      "warning": { "keys": ["#f59e0b"] },
+      "error": { "keys": ["#ef4444"] },
+      "info": { "keys": ["#3b82f6"] }
+    },
+    "pairs": {
+      "ember-dune": { "bg": "secondary.600", "fg": "tertiary.50", "description": "Example pair: warm callouts and toasts." },
+      "mirage-deep": { "bg": "primary.900", "fg": "primary.75", "accent": "tertiary.200", "description": "Example pair: a dark brand band." },
+      "stone-soft": {
+        "bg": "neutral.100",
+        "fg": "neutral.1200",
+        "accent": "primary.600",
+        "dark": { "bg": "neutral.1100", "fg": "neutral.100", "accent": "primary.300" },
+        "description": "Example pair: a quiet inset panel that flips in dark mode."
+      }
+    },
+    "data": [
+      ["violet", "#a04fdf"], ["coral", "#ef7053"], ["gold", "#c4b679"], ["burgundy", "#612c3d"],
+      ["mint", "#86e6ca"], ["navy", "#154975"], ["periwinkle", "#bbc3fe"], ["forest", "#0b5313"],
+      ["lime", "#74ce4b"], ["yellow", "#dac925"], ["lavender", "#b4a1e2"], ["peach", "#ffc3b5"],
+      ["cream", "#f1e5af"], ["mauve", "#a6838e"], ["seafoam", "#bfecdf"], ["sky", "#7fa8cb"],
+      ["ice", "#e5e8ff"], ["sage", "#b1d0b5"], ["chartreuse", "#d0fabd"], ["ivory", "#fffce1"]
+    ]
+  },
+
+  "type": {
+    "families": {
+      "display": ["Funnel Display", "sans-serif"],
+      "body": ["Barlow Semi Condensed", "sans-serif"],
+      "mono": ["Roboto Mono", "monospace"]
+    },
+    "metrics": {
+      "display": { "ascent": 1, "descent": 0.25, "capHeight": 0.675, "xHeight": 0.5 },
+      "body": { "ascent": 1, "descent": 0.2, "capHeight": 0.7, "xHeight": 0.506 },
+      "mono": { "ascent": 1.048, "descent": 0.271, "capHeight": 0.711, "xHeight": 0.528 }
+    },
+    "base": { "min": 14, "max": 16 },
+    "ratio": { "min": 1.2, "max": 1.2 },
+    "viewport": { "min": 320, "max": 1280 },
+    "steps": ["xxs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl", "4xl", "5xl", "6xl", "7xl", "8xl", "9xl"],
+    "baseStep": "md",
+    "stepDown": true,
+    "displayFrom": "2xl",
+    "small": { "fixed": true, "floor": 9 },
+    "lineHeight": { "text": 0.228, "heading": -0.046, "textStep": "sm", "headingStep": "3xl", "solidFrom": "4xl" }
+  },
+
+  "radius": {
+    "base": 4,
+    "steps": { "none": 0, "sm": 0.5, "base": 1, "md": 1.5, "lg": 2, "xl": 3, "2xl": 4, "3xl": 6 }
+  },
+
+  "stroke": { "base": 1, "steps": { "thin": 1, "medium": 2, "thick": 3 } },
+
+  "elevation": { "shadowColor": "#000000", "strength": 1 },
+
+  "motion": { "speed": 1, "durations": { "fast": 100, "normal": 200, "slow": 300 } },
+
+  "roles": {
+    "chrome": "neutral",
+    "accent": "primary",
+    "emphasis": {
+      "bold": { "style": "solid", "color": "accent" },
+      "standard": { "style": "outline", "color": "accent" },
+      "subtle": { "style": "soft", "color": "chrome" },
+      "quiet": { "style": "outline", "color": "chrome" }
+    },
+    "concepts": { "chrome.fg": { "light": "primary.1000" } }
+  }
+}