@scattered-light/loomiere 0.0.0-stage → 0.1.0

package/exporters/component-styles.mjs

@@ -0,0 +1,207 @@
+/**
+ * The Base UI styles' shared patterns as style objects, for frameworks that style their own
+ * components (MUI, Chakra). Each piece reads the same concept variables the patterns in
+ * loomiere-base-ui/styles/patterns/shared.css read, so a MUI TextField, a Chakra Input and a
+ * Base UI Input are one control with three APIs. Values are var(--<prefix>-…) strings: the
+ * page must load the theme's tokens.css, and light, dark and data-color follow from there.
+ */
+import { LEVELS, STYLES } from '../generator/roles.mjs';
+
+const TEXT_PROPS = ['font-family', 'font-size', 'font-weight', 'line-height', 'letter-spacing'];
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+export function styleKit(prefix, roles) {
+  const v = (name) => `var(--${prefix}-${name})`;
+
+  /** One whole text style, as longhands (the shorthand would reset kerning). */
+  const text = (style) => ({
+    ...Object.fromEntries(TEXT_PROPS.map((p) => [camel(p), v(`font-${style}-${p}`)])),
+    ...(style.endsWith('subtitle-label') && { textTransform: v(`font-${style}-text-transform`) }),
+  });
+
+  /** A palette's slot, through the scope variables: `scope('error', 'solid')`. */
+  const scope = (palette, slot) => (slot === 'transparent' ? 'transparent' : v(`scope-${palette}-${slot}`));
+
+  /**
+   * An emphasis level's colors. Without `palette` the level uses its own color from the
+   * brand's roles (bold is the accent, quiet is chrome in Mojave); with one, the level's
+   * style in that palette, the way data-color re-colors a Base UI Button.
+   */
+  const emphasis = (level, palette) => {
+    const { style, color } = roles.emphasis[level];
+    const p = palette ?? color;
+    const parts = Object.fromEntries(Object.entries(STYLES[style]).map(([part, slot]) => [part, scope(p, slot)]));
+    return { ...parts, focus: scope(p, 'focus'), halo: scope(p, 'soft-hover'), palette: p };
+  };
+
+  const focusRing = {
+    outline: v('focus-outline'),
+    outlineOffset: v('focus-outline-offset'),
+    boxShadow: `0 0 0 ${v('focus-halo-spread')} ${v('focus-halo-color')}`,
+  };
+  const focusRingInset = { outline: v('focus-outline'), outlineOffset: v('focus-outline-offset-inset') };
+
+  const field = {
+    boxSizing: 'border-box',
+    color: v('field-color'),
+    background: v('field-background'),
+    border: `${v('field-border-width')} solid ${v('field-border-color')}`,
+    borderRadius: v('field-radius'),
+    transition: v('field-transition'),
+    outline: 'none',
+  };
+  const fieldStates = {
+    hover: { borderColor: v('field-border-color-hover') },
+    focus: { borderColor: v('field-border-color-focus'), boxShadow: v('field-shadow-focus') },
+    error: { borderColor: v('field-border-color-error') },
+    errorFocus: { borderColor: v('field-border-color-error'), boxShadow: v('field-shadow-focus-error') },
+    disabled: { background: v('field-background-disabled'), color: v('field-color-disabled'), cursor: 'not-allowed' },
+    placeholder: { color: v('field-placeholder-color'), opacity: 1 },
+  };
+
+  /** Control sizes: height, padding and the text style of each tier. */
+  const SIZES = {
+    xs: { suffix: '-xs', text: 'minimize', icon: 'condense' },
+    sm: { suffix: '-sm', text: 'condense', icon: 'base' },
+    md: { suffix: '', text: 'base', icon: 'magnify' },
+    lg: { suffix: '-lg', text: 'magnify', icon: 'maximize' },
+  };
+  const control = (size, { trigger = false } = {}) => {
+    const s = SIZES[size];
+    return {
+      ...text(trigger ? `${s.text}-trigger` : s.text),
+      height: v(`control-height${s.suffix || '-md'}`),
+      paddingInline: v(`control-padding-inline${s.suffix}`),
+      gap: v(size === 'xs' ? 'gap-control-xs' : size === 'sm' ? 'gap-control-sm' : 'gap-control'),
+    };
+  };
+  const iconSize = (size) => v(`icon-size-${SIZES[size].icon}`);
+
+  const popupSurface = {
+    boxSizing: 'border-box',
+    background: v('popup-background'),
+    border: `${v('popup-border-width')} solid ${v('popup-border-color')}`,
+    borderRadius: v('popup-radius'),
+    boxShadow: v('popup-shadow'),
+    backgroundImage: 'none',
+    color: v('text-primary'),
+  };
+  const modalSurface = {
+    boxSizing: 'border-box',
+    gap: v('modal-gap'),
+    padding: v('modal-padding'),
+    background: v('modal-background'),
+    border: `${v('modal-border-width')} solid ${v('modal-border-color')}`,
+    borderRadius: v('modal-radius'),
+    boxShadow: v('modal-shadow'),
+    backgroundImage: 'none',
+    color: v('text-primary'),
+  };
+  const barSurface = {
+    boxSizing: 'border-box',
+    padding: v('bar-padding'),
+    gap: v('bar-gap'),
+    background: v('bar-background'),
+    border: `${v('bar-border-width')} solid ${v('bar-border-color')}`,
+    borderRadius: v('bar-radius'),
+  };
+
+  const itemRow = {
+    ...text('base'),
+    display: 'flex',
+    alignItems: 'center',
+    gap: v('item-gap'),
+    minHeight: 0,
+    paddingBlock: v('item-padding-block'),
+    paddingInline: v('item-padding-inline'),
+    borderRadius: v('item-radius'),
+    color: v('item-color'),
+    transition: v('item-transition'),
+  };
+  const itemStates = {
+    hover: { background: v('item-background-hover'), color: v('item-color-hover') },
+    selected: { ...text('base-selected'), background: v('item-background-selected'), color: v('item-color-selected') },
+    disabled: { color: v('item-color-disabled'), opacity: v('item-opacity-disabled') },
+  };
+  const groupLabel = {
+    ...text('condense-subtitle-label'),
+    paddingBlock: `${v('popup-group-label-padding-top')} ${v('popup-group-label-padding-bottom')}`,
+    paddingInline: v('item-padding-inline'),
+    color: v('text-secondary'),
+    background: 'transparent',
+  };
+  const separator = { height: v('stroke-default'), marginBlock: v('popup-separator-spacing'), border: 'none', background: v('popup-separator-color') };
+
+  const checkBox = {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: 0,
+    border: `${v('check-border-width')} solid ${v('check-border-color')}`,
+    background: v('check-background'),
+    color: v('check-mark-color'),
+    transition: v('check-transition'),
+  };
+  const checkStates = {
+    hover: { borderColor: v('check-border-color-hover') },
+    checked: { background: v('check-background-checked'), borderColor: v('check-border-color-checked') },
+    disabled: { opacity: v('check-opacity-disabled') },
+  };
+
+  const iconButton = {
+    width: v('icon-button-size'),
+    height: v('icon-button-size'),
+    padding: 0,
+    borderRadius: v('icon-button-radius'),
+    color: v('icon-button-color'),
+    transition: v('icon-button-transition'),
+  };
+  const iconButtonHover = { background: v('icon-button-background-hover'), color: v('icon-button-color-hover') };
+
+  return {
+    v,
+    text,
+    scope,
+    emphasis,
+    levels: LEVELS,
+    focusRing,
+    focusRingInset,
+    field,
+    fieldStates,
+    control,
+    iconSize,
+    sizes: Object.keys(SIZES),
+    popupSurface,
+    modalSurface,
+    barSurface,
+    itemRow,
+    itemStates,
+    groupLabel,
+    separator,
+    checkBox,
+    checkStates,
+    iconButton,
+    iconButtonHover,
+  };
+}
+
+/** Marks a piece of JavaScript source to paste into a generated file as is. */
+export const raw = (code) => ({ __raw: code });
+
+/** A value as JavaScript source: JSON, except raw() pieces are pasted in. */
+export function toSource(value, indent = '') {
+  if (value && typeof value === 'object' && '__raw' in value) return value.__raw;
+  const inner = `${indent}  `;
+  if (Array.isArray(value)) {
+    if (!value.length) return '[]';
+    return `[\n${value.map((x) => inner + toSource(x, inner)).join(',\n')}\n${indent}]`;
+  }
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, x]) => x !== undefined);
+    if (!entries.length) return '{}';
+    const key = (k) => (/^[A-Za-z_$][\w$]*$/.test(k) ? k : JSON.stringify(k));
+    return `{\n${entries.map(([k, x]) => `${inner}${key(k)}: ${toSource(x, inner)}`).join(',\n')}\n${indent}}`;
+  }
+  return JSON.stringify(value);
+}

package/exporters/dtcg.mjs

@@ -0,0 +1,31 @@
+/**
+ * DTCG (Design Tokens Community Group) JSON: every token, nested by path, keeping its
+ * references, with dark and other modes under $extensions. Tokens Studio, Figma variable
+ * importers, Style Dictionary and Terrazzo all read it, so it's the universal export.
+ */
+export default {
+  id: 'dtcg',
+  name: 'Design tokens (DTCG)',
+  file: 'tokens.dtcg.json',
+  for: 'Any tool that reads the W3C design tokens format: Figma (Tokens Studio, variable importers), Style Dictionary, Terrazzo, Penpot.',
+  build(theme) {
+    const root = {};
+    for (const t of theme.tokens) {
+      const keys = t.path.split('.');
+      let node = root;
+      for (const k of keys.slice(0, -1)) {
+        // A path that is both a token and a group (rare) keeps the token under "DEFAULT".
+        if (node[k]?.$value !== undefined) node[k] = { DEFAULT: node[k] };
+        node = node[k] ??= {};
+      }
+      const modes = t.modeReferences ?? t.modes;
+      node[keys.at(-1)] = {
+        ...(t.type && { $type: t.type }),
+        $value: t.references ?? t.value,
+        ...(t.description && { $description: t.description }),
+        ...(modes && { $extensions: { 'sl.modes': modes } }),
+      };
+    }
+    return `${JSON.stringify({ $description: `${theme.brand} theme, prefix --${theme.prefix}-`, ...root }, null, 2)}\n`;
+  },
+};

package/exporters/figma.mjs

@@ -0,0 +1,100 @@
+/**
+ * Figma variables, one collection per builder step so each step can sync on its own:
+ *   Brand   palettes, data colors, space, radius, stroke, type   (step 1)
+ *   Pairs   each pair's colors, light and dark                   (step 2)
+ *   Theme   surfaces, text, borders, scopes and emphasis levels  (step 3)
+ * Pairs and Theme alias Brand, and Theme aliases itself the way the tokens do
+ * (emphasis → scope → palette step), so changing a role in Figma moves everything that uses it.
+ * Values that are math in CSS (color-mix) are resolved to colors. Every variable carries its
+ * CSS variable as WEB code syntax. The file is data for a sync script that writes the
+ * variables with the Figma plugin API; it isn't a Figma import format.
+ */
+import { formatHex, formatHex8, interpolate, parse } from 'culori';
+
+/** #rrggbb, or #rrggbbaa when the color is see-through. */
+const hex = (c) => ((c.alpha ?? 1) < 1 ? formatHex8(c) : formatHex(c));
+
+import { px, valueIn } from './theme.mjs';
+
+/** color-mix(in oklab|srgb, A p%, B) → a hex; anything else parse() understands → a hex. */
+function solve(value) {
+  const mix = String(value).match(/^color-mix\(in (\w+),\s*(.+?)\s+([\d.]+)%,\s*(.+)\)$/);
+  if (mix) return hex(interpolate([solve(mix[4]), solve(mix[2])], mix[1] === 'srgb' ? 'rgb' : mix[1])(Number(mix[3]) / 100));
+  if (value === 'transparent') return '#00000000';
+  const c = parse(value);
+  return c ? hex(c) : null;
+}
+
+const COLLECTION_OF = (t) => {
+  if (t.layer === 'primitive' && !t.path.startsWith('vision.') && !/^color\.(accent|chrome)\./.test(t.path)) return 'Brand';
+  if (t.layer === 'semantic' && t.type === 'color') return t.path.startsWith('pair.') ? 'Pairs' : 'Theme';
+  return null;
+};
+
+const SCOPES = {
+  surface: ['FRAME_FILL', 'SHAPE_FILL'],
+  text: ['TEXT_FILL'],
+  border: ['STROKE_COLOR'],
+  color: ['ALL_FILLS', 'STROKE_COLOR'],
+  space: ['GAP', 'WIDTH_HEIGHT'],
+  radius: ['CORNER_RADIUS'],
+  stroke: ['STROKE_FLOAT'],
+  'font-size': ['FONT_SIZE'],
+  'font-family': ['FONT_FAMILY'],
+};
+const scopesOf = (path) => SCOPES[path.split('.')[0]] ?? ['ALL_FILLS', 'STROKE_COLOR', 'EFFECT_COLOR'];
+
+export default {
+  id: 'figma',
+  name: 'Figma variables',
+  file: 'figma.json',
+  for: 'Syncing to Figma variables: Brand, Pairs and Theme collections with light and dark modes. Ask Claude to sync a step.',
+  build(theme) {
+    const byPath = new Map(theme.tokens.map((t) => [t.path, t]));
+    const figmaName = (path) => path.replace(/\./g, '/');
+    const refOf = (r) => r?.match(/^\{([^}]+)\}$/)?.[1];
+    // Follow accent/chrome aliases (they aren't variables in Figma) to the palette step.
+    const target = (path) => {
+      let t = byPath.get(path);
+      while (t && /^color\.(accent|chrome)\./.test(t.path)) t = byPath.get(refOf(t.references));
+      return t && COLLECTION_OF(t) ? `${COLLECTION_OF(t)}:${figmaName(t.path)}` : null;
+    };
+    const valueFor = (t, mode) => {
+      const ref = mode === 'Dark' ? refOf(t.modeReferences?.dark) ?? (t.modes?.dark === undefined ? refOf(t.references) : null) : refOf(t.references);
+      const alias = ref && target(ref);
+      if (alias) return { alias };
+      const raw = mode === 'Dark' ? valueIn(byPath, t.path, 'dark') : t.value;
+      return t.type === 'color' ? solve(raw) : raw;
+    };
+
+    const collections = { Brand: [], Pairs: [], Theme: [] };
+    for (const t of theme.tokens) {
+      const c = COLLECTION_OF(t);
+      if (!c) continue;
+      const top = t.path.split('.')[0];
+      let type, value;
+      if (t.type === 'color' || top === 'color') type = 'COLOR';
+      else if (['space', 'radius', 'stroke', 'font-size'].includes(top)) {
+        // Fluid sizes go in at their large-screen size; Figma variables hold one number.
+        const m = String(t.value).match(/,\s*([\d.]+rem)\)$/);
+        value = px(m ? m[1] : t.value);
+        if (value === undefined) continue;
+        type = 'FLOAT';
+      } else if (top === 'font-family') {
+        type = 'STRING';
+        value = String(t.value).split(',')[0].replace(/['"]/g, '').trim();
+      } else continue;
+      const modes = c === 'Brand' ? { Value: value ?? valueFor(t, 'Light') } : { Light: valueFor(t, 'Light'), Dark: valueFor(t, 'Dark') };
+      collections[c].push({ name: figmaName(t.path), type, modes, scopes: scopesOf(t.path), code: `var(${t.name})`, ...(t.description && { description: t.description }) });
+    }
+    const out = {
+      brand: theme.brand,
+      collections: [
+        { name: 'Brand', step: 'brand', modes: ['Value'], variables: collections.Brand },
+        { name: 'Pairs', step: 'pairs', modes: ['Light', 'Dark'], variables: collections.Pairs },
+        { name: 'Theme', step: 'roles', modes: ['Light', 'Dark'], variables: collections.Theme },
+      ],
+    };
+    return `${JSON.stringify(out)}\n`;
+  },
+};

package/exporters/index.mjs

@@ -0,0 +1,38 @@
+/**
+ * The export catalog. The universal outputs are the CSS variables (dist/tokens/tokens.css)
+ * and DTCG JSON; every framework adapter reads the same neutral theme (theme.mjs) and only
+ * renames. To add a framework, add a file like mui.mjs and list it here.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+import chakra from './chakra.mjs';
+import dtcg from './dtcg.mjs';
+import figma from './figma.mjs';
+import mui from './mui.mjs';
+import tailwind from './tailwind.mjs';
+import { agGridV32, agGridV33, agGridV36 } from './ag-grid.mjs';
+import { readTheme } from './theme.mjs';
+
+export const EXPORTERS = [dtcg, figma, tailwind, mui, chakra, agGridV36, agGridV33, agGridV32];
+
+/**
+ * Whether an exporter is wanted: `only` is "all" or a list of ids, where an id may name a
+ * family by its start ("ag-grid" picks ag-grid-v36, ag-grid-v33 and ag-grid-v32).
+ */
+const wanted = (id, only) => only === 'all' || only.some((pick) => id === pick || id.startsWith(`${pick}-`));
+
+/** Writes the chosen exports into outDir and a catalog.json that lists them. */
+export function exportAll(catalog, roles, outDir, only = 'all') {
+  const theme = readTheme(catalog, roles);
+  fs.mkdirSync(outDir, { recursive: true });
+  const written = EXPORTERS.filter((exporter) => wanted(exporter.id, only)).map((exporter) => {
+    // An exporter returns one file's text, or { fileName: text } when it writes several.
+    const out = exporter.build(theme);
+    const files = typeof out === 'string' ? { [exporter.file]: out } : out;
+    for (const [file, text] of Object.entries(files)) fs.writeFileSync(path.join(outDir, file), text);
+    return { id: exporter.id, name: exporter.name, file: exporter.file, files: Object.keys(files), for: exporter.for };
+  });
+  fs.writeFileSync(path.join(outDir, 'catalog.json'), `${JSON.stringify({ brand: theme.brand, exports: written }, null, 2)}\n`);
+  return written;
+}