@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/figma/style-map.ts

@@ -0,0 +1,352 @@
+/**
+ * @file       figma/style-map.ts — Figma paint/effect/typeStyle → CSS.
+ * @scope      apps/studio/figma/style-map.ts
+ * @purpose    Turn a node's visual properties into CSS declarations, resolving
+ *             every colour to the NEAREST active-DS token rather than baking a
+ *             hex into an imported canvas.
+ *
+ * @invariant  IMPORTED FRAMES MUST NOT HARDCODE HEX. A canvas whose colours are
+ *             literals is off-brand the moment the DS moves, and it defeats the
+ *             point of importing INTO a design system. Every paint resolves to
+ *             `var(--token)` inside a configurable ΔE threshold; outside it, the
+ *             literal ships WITH a `/* figma: no near token *​/` marker so the
+ *             drift is auditable rather than silent. Threshold and fallback are
+ *             per-import flags, never hidden constants.
+ *
+ * @invariant  EVERY EMITTED VALUE IS GRAMMAR-VALIDATED FIRST (DDR-216 D6, which
+ *             reuses DDR-172 Decision 4 verbatim): printable-ASCII pre-filter,
+ *             no `m`/`s` regex flags, shape AND magnitude bounds, no unbounded
+ *             free-text capture. A value that fails is DROPPED and reported —
+ *             never "cleaned up" and never partially applied. This matters more
+ *             here than in `import-tokens`: a canvas stylesheet is rendered live
+ *             in the canvas iframe.
+ *
+ * @invariant  DEPENDENCY-FREE beyond `draw/palette.ts` (the colorspace helpers
+ *             `import-tokens` already reuses). No fs, no network.
+ */
+
+import { parseColor, rgbToOklch } from '../draw/palette.ts';
+import type { FigmaColor, FigmaEffect, FigmaNode, FigmaPaint, FigmaTypeStyle } from './types.ts';
+
+/** Default perceptual distance under which a paint snaps to a DS token. */
+export const DEFAULT_TOKEN_THRESHOLD = 0.08;
+
+/** The marker that makes an un-snapped literal auditable rather than silent. */
+export const NO_TOKEN_MARKER = '/* figma: no near token */';
+
+export interface DsToken {
+  /** e.g. `--accent` — the name only, never a value the caller invented. */
+  name: string;
+  /** Resolved hex for distance comparison. */
+  hex: string;
+}
+
+// ── Value grammars (DDR-172 Decision 4, reused verbatim per DDR-216 D6) ─────
+//
+// Deliberately NO unbounded free-text capture anywhere, and every numeric
+// grammar is paired with a magnitude bound: a grammar-valid `99999999px` is a
+// live-render hang vector even though its SHAPE is fine.
+
+const PRINTABLE_ASCII_RE = /^[\x20-\x7E]*$/;
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const RGBA_RE = /^rgba?\( ?[\d.]+[ ,]+[\d.]+[ ,]+[\d.]+(?: ?[,/] ?[\d.]+%?)? ?\)$/;
+const VAR_RE = /^var\(--[a-z0-9-]{1,64}\)$/;
+const DIM_MAX = 4096;
+const FONT_SIZE_MAX = 512;
+
+/** True when a string is safe to place in a CSS value position at all. */
+function printableAscii(v: string): boolean {
+  // Checked BEFORE any grammar regex, and no grammar here uses `m`/`s` — an
+  // anchor is only as strong as the flags it runs under, and a multiline value
+  // would otherwise match just its first line.
+  return PRINTABLE_ASCII_RE.test(v);
+}
+
+export function isValidColorValue(v: string): boolean {
+  if (!printableAscii(v)) return false;
+  return HEX_RE.test(v) || RGBA_RE.test(v) || VAR_RE.test(v);
+}
+
+export function isValidDimension(v: string, max = DIM_MAX): boolean {
+  if (!printableAscii(v)) return false;
+  if (v === '0') return true;
+  const m = /^(-?[\d.]{1,7})(px|rem|em|%)$/.exec(v);
+  if (!m) return false;
+  const n = Number.parseFloat(m[1]);
+  return Number.isFinite(n) && Math.abs(n) <= max;
+}
+
+// ── Colour ──────────────────────────────────────────────────────────────────
+
+function figmaColorToHex(c: FigmaColor): string {
+  const to = (v: number) =>
+    Math.max(0, Math.min(255, Math.round(v * 255)))
+      .toString(16)
+      .padStart(2, '0');
+  return `#${to(c.r)}${to(c.g)}${to(c.b)}`;
+}
+
+/** Perceptual distance in OKLCH — the same space `import-tokens` compares in. */
+export function perceptualDistance(aHex: string, bHex: string): number {
+  try {
+    const a = rgbToOklch(parseColor(aHex));
+    const b = rgbToOklch(parseColor(bHex));
+    // Chroma/hue folded into a Cartesian pair so a hue difference at low chroma
+    // (where hue is perceptually meaningless) doesn't dominate the distance.
+    const aa = a.c * Math.cos((a.h * Math.PI) / 180);
+    const ab = a.c * Math.sin((a.h * Math.PI) / 180);
+    const ba = b.c * Math.cos((b.h * Math.PI) / 180);
+    const bb = b.c * Math.sin((b.h * Math.PI) / 180);
+    return Math.hypot(a.l - b.l, aa - ba, ab - bb);
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+export interface ResolvedColor {
+  /** The CSS value to emit — `var(--token)` or a literal hex. */
+  value: string;
+  /** Set when no token was near enough; the caller emits it as a comment. */
+  marker?: string;
+  /** Which token matched, for the report. */
+  token?: string;
+}
+
+/**
+ * Resolve a hex to the nearest DS token, or fall back to the literal WITH a
+ * marker. Never invents a token name and never silently ships a hex.
+ */
+export function resolveColor(
+  hex: string,
+  tokens: readonly DsToken[],
+  threshold = DEFAULT_TOKEN_THRESHOLD
+): ResolvedColor {
+  let best: DsToken | null = null;
+  let bestDist = Number.POSITIVE_INFINITY;
+  for (const t of tokens) {
+    const d = perceptualDistance(hex, t.hex);
+    if (d < bestDist) {
+      bestDist = d;
+      best = t;
+    }
+  }
+  if (best && bestDist <= threshold) {
+    return { value: `var(${best.name})`, token: best.name };
+  }
+  return { value: hex, marker: NO_TOKEN_MARKER };
+}
+
+// ── Paints / effects / type ─────────────────────────────────────────────────
+
+export interface StyleMapOptions {
+  tokens: readonly DsToken[];
+  threshold?: number;
+}
+
+export interface MappedStyle {
+  /** CSS property → value. Every value has already passed its grammar. */
+  declarations: Record<string, string>;
+  /** Properties dropped because a value failed its grammar (reported). */
+  rejected: string[];
+  /** Properties that shipped a literal because no token was near (reported). */
+  unTokenized: string[];
+}
+
+function emptyStyle(): MappedStyle {
+  return { declarations: {}, rejected: [], unTokenized: [] };
+}
+
+function firstVisible<T extends { visible: boolean }>(list: readonly T[] | undefined): T | null {
+  for (const p of list ?? []) if (p.visible) return p;
+  return null;
+}
+
+/** A linear gradient → the CSS equivalent. Angle is derived from the handles. */
+function gradientCss(paint: FigmaPaint, opts: StyleMapOptions, out: MappedStyle): string | null {
+  const stops = paint.gradientStops;
+  if (!stops || stops.length < 2) return null;
+  const parts: string[] = [];
+  for (const s of stops) {
+    const resolved = resolveColor(figmaColorToHex(s.color), opts.tokens, opts.threshold);
+    if (!isValidColorValue(resolved.value)) return null;
+    if (resolved.marker) out.unTokenized.push('background-image');
+    const pct = Math.max(0, Math.min(100, Math.round(s.position * 100)));
+    parts.push(`${resolved.value} ${pct}%`);
+  }
+  const handles = paint.gradientHandlePositions;
+  let angle = 180;
+  if (handles && handles.length >= 2) {
+    const dx = handles[1].x - handles[0].x;
+    const dy = handles[1].y - handles[0].y;
+    angle = Math.round((Math.atan2(dy, dx) * 180) / Math.PI + 90);
+  }
+  return `linear-gradient(${angle}deg, ${parts.join(', ')})`;
+}
+
+/** Effects → `box-shadow`. Every layer is strict-numeric; no free-text capture. */
+function shadowCss(effects: readonly FigmaEffect[], opts: StyleMapOptions): string | null {
+  const layers: string[] = [];
+  for (const e of effects) {
+    if (!e.visible) continue;
+    if (e.type !== 'DROP_SHADOW' && e.type !== 'INNER_SHADOW') continue;
+    const c = e.color ? figmaColorToHex(e.color) : '#000000';
+    const resolved = resolveColor(c, opts.tokens, opts.threshold);
+    if (!isValidColorValue(resolved.value)) continue;
+    const x = Math.round(e.offset?.x ?? 0);
+    const y = Math.round(e.offset?.y ?? 0);
+    const blur = Math.round(e.radius ?? 0);
+    const spread = Math.round(e.spread ?? 0);
+    if ([x, y, blur, spread].some((n) => !Number.isFinite(n) || Math.abs(n) > 512)) continue;
+    const inset = e.type === 'INNER_SHADOW' ? 'inset ' : '';
+    layers.push(`${inset}${x}px ${y}px ${blur}px ${spread}px ${resolved.value}`);
+  }
+  return layers.length ? layers.join(', ') : null;
+}
+
+/** A node's fills/strokes/effects/corner radius → CSS declarations. */
+export function mapNodeStyle(node: FigmaNode, opts: StyleMapOptions): MappedStyle {
+  const out = emptyStyle();
+  const set = (prop: string, value: string, validator: (v: string) => boolean) => {
+    if (!validator(value)) {
+      out.rejected.push(prop);
+      return;
+    }
+    out.declarations[prop] = value;
+  };
+
+  const fill = firstVisible(node.fills);
+  if (fill) {
+    if (fill.type === 'SOLID' && fill.color) {
+      const resolved = resolveColor(figmaColorToHex(fill.color), opts.tokens, opts.threshold);
+      if (resolved.marker) out.unTokenized.push('background');
+      set('background', resolved.value, isValidColorValue);
+    } else if (fill.type.startsWith('GRADIENT')) {
+      const css = gradientCss(fill, opts, out);
+      // A gradient is not a colour value — it has its own (bounded) shape,
+      // built entirely from already-validated colour values plus integers.
+      // camelCase, NOT `background-image`: these declarations are emitted into
+      // a JSX style OBJECT, where a hyphenated key is a syntax error that takes
+      // the whole canvas down. One gradient anywhere on a page was enough to
+      // make the file unparseable.
+      if (css) out.declarations.backgroundImage = css;
+      else out.rejected.push('background-image');
+    }
+  }
+
+  const stroke = firstVisible(node.strokes);
+  if (stroke?.type === 'SOLID' && stroke.color) {
+    const resolved = resolveColor(figmaColorToHex(stroke.color), opts.tokens, opts.threshold);
+    if (resolved.marker) out.unTokenized.push('border-color');
+    const w = Math.round(node.strokeWeight ?? 1);
+    if (Number.isFinite(w) && w > 0 && w <= 64 && isValidColorValue(resolved.value)) {
+      out.declarations.border = `${w}px solid ${resolved.value}`;
+    } else {
+      out.rejected.push('border');
+    }
+  }
+
+  if (node.cornerRadius !== undefined) {
+    set('borderRadius', `${Math.round(node.cornerRadius)}px`, (v) => isValidDimension(v, 512));
+  }
+
+  if (node.effects?.length) {
+    const css = shadowCss(node.effects, opts);
+    if (css) out.declarations.boxShadow = css;
+  }
+
+  // Node opacity is carried ONLY when it is not a hiding mechanism. D6b makes
+  // the translator guarantee visibility, so an opacity that would render the
+  // subtree effectively invisible is dropped rather than reproduced.
+  if (node.opacity !== undefined && node.opacity < 1) {
+    if (node.opacity >= 0.15) out.declarations.opacity = String(Number(node.opacity.toFixed(3)));
+    else out.rejected.push('opacity');
+  }
+
+  return out;
+}
+
+/** A TEXT node's `style` block → CSS declarations. */
+export function mapTypeStyle(
+  style: FigmaTypeStyle | undefined,
+  opts: StyleMapOptions
+): MappedStyle {
+  const out = emptyStyle();
+  if (!style) return out;
+
+  if (style.fontSize !== undefined) {
+    const v = `${Math.round(style.fontSize)}px`;
+    if (isValidDimension(v, FONT_SIZE_MAX)) out.declarations.fontSize = v;
+    else out.rejected.push('fontSize');
+  }
+  if (style.fontWeight !== undefined) {
+    const w = Math.round(style.fontWeight);
+    if (w >= 100 && w <= 1000) out.declarations.fontWeight = String(w);
+    else out.rejected.push('fontWeight');
+  }
+  if (style.lineHeightPx !== undefined) {
+    const v = `${Math.round(style.lineHeightPx)}px`;
+    if (isValidDimension(v, FONT_SIZE_MAX)) out.declarations.lineHeight = v;
+    else out.rejected.push('lineHeight');
+  }
+  if (style.letterSpacing !== undefined && style.letterSpacing !== 0) {
+    const v = `${style.letterSpacing.toFixed(2)}px`;
+    if (isValidDimension(v, 64)) out.declarations.letterSpacing = v;
+    else out.rejected.push('letterSpacing');
+  }
+  if (style.textAlignHorizontal) {
+    const align = style.textAlignHorizontal.toLowerCase();
+    if (['left', 'center', 'right', 'justified'].includes(align)) {
+      out.declarations.textAlign = align === 'justified' ? 'justify' : align;
+    }
+  }
+  if (style.textCase === 'UPPER') out.declarations.textTransform = 'uppercase';
+  if (style.textCase === 'LOWER') out.declarations.textTransform = 'lowercase';
+  if (style.textDecoration === 'UNDERLINE') out.declarations.textDecoration = 'underline';
+  if (style.textDecoration === 'STRIKETHROUGH') out.declarations.textDecoration = 'line-through';
+
+  // FONT FAMILY IS DELIBERATELY NOT CARRIED. A Figma font name is free text
+  // from the document, and DDR-172 Decision 4's font grammar exists precisely
+  // because a family value reaches a live stylesheet. An imported canvas
+  // inherits the DS's own type stack instead — which is also the editability
+  // choice: an imported frame should look like it belongs to the project.
+
+  return out;
+}
+
+/** Auto-layout → flex. The thing that makes the handle surfaces work at all. */
+export function mapAutoLayout(node: FigmaNode): Record<string, string> {
+  if (node.layoutMode !== 'HORIZONTAL' && node.layoutMode !== 'VERTICAL') return {};
+  const out: Record<string, string> = {
+    display: 'flex',
+    flexDirection: node.layoutMode === 'HORIZONTAL' ? 'row' : 'column',
+  };
+  if (node.itemSpacing) out.gap = `${Math.round(node.itemSpacing)}px`;
+  const pad = [node.paddingTop, node.paddingRight, node.paddingBottom, node.paddingLeft];
+  if (pad.some((p) => p !== undefined && p !== 0)) {
+    out.padding = pad.map((p) => `${Math.round(p ?? 0)}px`).join(' ');
+  }
+  // `Object.create(null)`: these are indexed by DOCUMENT-CONTROLLED strings, so a
+  // plain literal returns `Object.prototype.constructor` (a FUNCTION) for
+  // `primaryAxisAlignItems: "constructor"`, which then stringifies into an
+  // emitted style value (review F11). D5 mandates this shape for exactly this.
+  const MAIN: Record<string, string> = Object.assign(Object.create(null), {
+    MIN: 'flex-start',
+    CENTER: 'center',
+    MAX: 'flex-end',
+    SPACE_BETWEEN: 'space-between',
+  });
+  const CROSS: Record<string, string> = Object.assign(Object.create(null), {
+    MIN: 'flex-start',
+    CENTER: 'center',
+    MAX: 'flex-end',
+    BASELINE: 'baseline',
+  });
+  if (node.primaryAxisAlignItems && MAIN[node.primaryAxisAlignItems]) {
+    out.justifyContent = MAIN[node.primaryAxisAlignItems];
+  }
+  if (node.counterAxisAlignItems && CROSS[node.counterAxisAlignItems]) {
+    out.alignItems = CROSS[node.counterAxisAlignItems];
+  }
+  if (node.layoutWrap === 'WRAP') out.flexWrap = 'wrap';
+  return out;
+}

package/apps/studio/figma/tailwind-map.test.ts

@@ -0,0 +1,142 @@
+// figma/tailwind-map.ts — Tailwind utility → JSX style object.
+//
+// The coverage claim is a MEASUREMENT, not an aspiration: 129 distinct classes
+// across 64 families were counted on a real 375×812 screen (DDR-219 § Spike),
+// and the census below is that exact list. If a future Figma release emits
+// something new, this test is where it shows up — as an `unmapped` entry, which
+// is the reportable outcome the acceptance criteria demand, not a silent drop.
+
+import { describe, expect, test } from 'bun:test';
+
+import { MAX_CLASSES_PER_ELEMENT, mapClassName } from './tailwind-map.ts';
+
+const DS_FONTS = [{ name: '--font-body', value: "'hanken grotesk','inter',sans-serif" }];
+
+/** Every distinct class observed on `425:2939`. */
+const MEASURED_CLASSES = `relative shrink-0 flex content-stretch items-center flex-col absolute
+justify-center size-full max-w-none block inset-0 [word-break:break-word] not-italic leading-[0]
+whitespace-nowrap size-[24px] w-full text-black items-start border-solid leading-[normal] gap-[8px]
+text-[12px] font-normal border bg-[var(--black-10,rgba(15,22,30,0.1))] py-[8px] px-[12px]
+rounded-[8px] overflow-clip leading-[20px] font-bold tracking-[0.288px] text-[14px] justify-between
+font-[family-name:var(--font,'Inter:Regular')] font-[family-name:var(--font,'Inter:Bold')] p-[10px]
+border-black w-[185px] rounded-[9px] min-w-px flex-[1_0_0] text-center self-stretch rounded-[999px]
+w-[40px] text-[color:var(--black,#0f161e)] size-[21.5px] rounded-[99px] p-px h-[32px] gap-px
+font-['Inter:Regular'] border-[var(--black,#0f161e)] row-1 py-[16px] px-[24px] col-1 w-[34.018px]
+w-[16px] text-[10px] text-[#0f161e] size-[32px] px-[10px] mt-0 h-[12px] border-b
+border-[var(--black-10,rgba(15,22,30,0.1))] -translate-y-1/2 -translate-x-1/2 w-[54px] w-[375px]
+w-[364px] w-[358px] w-[341.871px] w-[327px] w-[25px] w-[18px] w-0 tracking-[0.24px] tracking-[-0.3px]
+top-[695.49px] top-[25.01px] top-[191px] top-1/2 text-[16px] size-[16px] size-[14.018px]
+rounded-[16px] py-[12px] px-[20px] place-items-start pb-[8px] mt-px ml-[50px] ml-[26px] ml-0
+left-[calc(50%-32.5px)] left-[calc(50%-0.02px)] left-[6.35px] left-1/2 leading-[12px] justify-end
+inset-[37.5%_18.75%_26.56%_18.75%] inset-[10.42%_16.67%_8.33%_16.67%] inset-[0_4.17%] inset-[0_-0.5px]
+inset-[0.49%_0.06%_-0.36%_0.07%] inset-[-6.64%_-7.07%_-7.49%_-7.07%] inline-grid h-full h-[768px]
+h-[58.766px] h-[480px] h-[296px] h-[14.454px] h-[14.018px] h-[10px] grid-rows-[max-content]
+grid-cols-[max-content] gap-[7px] gap-[4px] font-['SF_Pro_Display:Semibold'] font-['SF_Pro:Bold']
+flex-row border-[red] bg-white`
+  .trim()
+  .split(/\s+/);
+
+describe('the measured surface', () => {
+  test('every class from the real screen maps — 129/129, zero unmapped', () => {
+    const unmapped: string[] = [];
+    for (const cls of MEASURED_CLASSES) {
+      const r = mapClassName(cls, { fontTokens: DS_FONTS });
+      if (r.unmapped.length > 0) unmapped.push(cls);
+    }
+    expect(unmapped).toEqual([]);
+    expect(MEASURED_CLASSES.length).toBe(129);
+  });
+});
+
+describe('the disambiguations that are easy to get wrong', () => {
+  test('text-[16px] is a font size and text-[#hex] is a colour', () => {
+    expect(mapClassName('text-[16px]').declarations).toEqual({ fontSize: '16px' });
+    expect(mapClassName('text-[#0f161e]').declarations).toEqual({ color: '#0f161e' });
+  });
+
+  test("Tailwind's own color: hint wins", () => {
+    expect(mapClassName('text-[color:var(--black,#0f161e)]').declarations).toEqual({
+      color: 'var(--black,#0f161e)',
+    });
+  });
+
+  test('border-[red] is a colour, border-[2px] is a width', () => {
+    expect(mapClassName('border-[red]').declarations).toEqual({ borderColor: 'red' });
+    expect(mapClassName('border-[2px]').declarations).toEqual({
+      borderWidth: '2px',
+      borderStyle: 'solid',
+    });
+  });
+
+  test('a negative utility carries its sign on the FAMILY, not the value', () => {
+    expect(mapClassName('-ml-[26px]').declarations).toEqual({ marginLeft: '-26px' });
+  });
+
+  test('transforms compose into ONE declaration', () => {
+    expect(mapClassName('-translate-x-1/2 -translate-y-1/2').declarations.transform).toBe(
+      'translateX(-50%) translateY(-50%)'
+    );
+  });
+
+  test('leading-[0] becomes normal — a zero line box hides the text', () => {
+    // D6b's rule in miniature: the translator can GUARANTEE visibility, so it
+    // does, rather than faithfully reproducing a collapsed line and reporting
+    // success on an empty-looking screen.
+    expect(mapClassName('leading-[0]').declarations).toEqual({ lineHeight: 'normal' });
+    expect(mapClassName('leading-[20px]').declarations).toEqual({ lineHeight: '20px' });
+  });
+
+  test('size-[N] sets both axes', () => {
+    expect(mapClassName('size-[16px]').declarations).toEqual({ width: '16px', height: '16px' });
+  });
+});
+
+describe('what must NOT get through', () => {
+  test.each([
+    'bg-[url(https://attacker.example/beacon.png)]',
+    '[behavior:url(#x)]',
+    '[content:"pwned"]',
+    'w-[99999999px]',
+    'text-[expression(alert(1))]',
+    'bg-[#fff;position:fixed]',
+    'grid-cols-[repeat(999999,1fr)]',
+  ])('%s is reported, never emitted', (cls) => {
+    const r = mapClassName(cls);
+    expect(r.declarations).toEqual({});
+    expect(r.unmapped.length).toBeGreaterThan(0);
+  });
+
+  test('an unknown utility is REPORTED — "never silently dropped" is the criterion', () => {
+    const r = mapClassName('flex definitely-not-a-tailwind-class');
+    expect(r.declarations).toEqual({ display: 'flex' });
+    expect(r.unmapped).toEqual(['definitely-not-a-tailwind-class']);
+  });
+
+  test('a class list long enough to be a payload is capped, and the cap is reported', () => {
+    const many = Array.from({ length: MAX_CLASSES_PER_ELEMENT + 10 }, () => 'flex').join(' ');
+    const r = mapClassName(many);
+    expect(r.unmapped).toContain('class-cap-reached');
+  });
+
+  test('an oversized single token never reaches a grammar', () => {
+    const r = mapClassName(`w-[${'1'.repeat(500)}px]`);
+    expect(r.declarations).toEqual({});
+    expect(r.unmapped).toEqual(['oversized']);
+  });
+});
+
+describe('DS tokens', () => {
+  test('a bare hex snaps onto a near DS token', () => {
+    const r = mapClassName('bg-[#0f161e]', {
+      tokens: [{ name: '--fg-0', hex: '#0f161e' }],
+    });
+    expect(r.declarations.background).toBe('var(--fg-0)');
+  });
+
+  test('a var() Figma already resolved is NOT re-snapped — that would be a downgrade', () => {
+    const r = mapClassName('bg-[var(--black,#0f161e)]', {
+      tokens: [{ name: '--fg-0', hex: '#0f161e' }],
+    });
+    expect(r.declarations.background).toBe('var(--black,#0f161e)');
+  });
+});