justskill-design 0.0.1 → 3.2.0

package/lib/render.mjs

@@ -0,0 +1,503 @@
+/**
+ * lib/render.mjs — the document tree to what the canvas mounts.
+ *
+ * The renderer is shared by the canvas and by `export`. That is the whole point:
+ * what the user drags is what ships. A separate "preview renderer" is how a
+ * design tool ends up with two truths.
+ *
+ * Browser-safe on purpose. The canvas parses and renders the file itself, so the
+ * service never has to send a document tree over the wire and the two sides
+ * cannot disagree about what the file means.
+ *
+ * What the renderer does:
+ *   - resolves `var(--token)` from the file's token block
+ *   - inlines the token block into each page's scope
+ *   - positions pages with the page-frame block and `data-canvas`
+ *   - keeps every element's `data-id`, so the canvas can map a click to an op
+ *
+ * What it does not do:
+ *   - it does not rewrite the design file. A mount is a view.
+ *   - it does not inject canvas chrome into the design markup. The canvas puts
+ *     its own styles in its own document, and each page gets a shadow root.
+ *
+ * Pure. No node: imports.
+ */
+
+import { parse, parseDeclarations, getAttr, pagesOf, elementChildren, textOf, VOID_ELEMENTS, styleMapOf } from "./parse.mjs";
+import { collectTokens } from "./validate.mjs";
+import { CSS_ALLOWED, splitTopLevel } from "./table.mjs";
+import { resolveTokens } from "./tokens.mjs";
+
+// -- escaping ----------------------------------------------------------------
+
+const TEXT_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+const ATTR_ESCAPES = { "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" };
+
+export function escapeText(value) {
+  return String(value ?? "").replace(/[&<>]/g, (ch) => TEXT_ESCAPES[ch]);
+}
+
+export function escapeAttr(value) {
+  return String(value ?? "").replace(/[&"<>]/g, (ch) => ATTR_ESCAPES[ch]);
+}
+
+// -- style -------------------------------------------------------------------
+
+// `styleMapOf` is defined in `lib/parse.mjs`, next to `parseDeclarations`, and
+// re-exported here because this module is where its callers look for it. It had
+// a second copy of the declaration splitter beside it until the comment that
+// justified the copy turned out to be false: this module already imports `parse`
+// and `getAttr` from `parse.mjs`, so there was never a cycle to avoid.
+export { styleMapOf };
+
+/** Serialize a property map back to a `style` attribute value, in table order. */
+export function styleStringOf(map) {
+  const entries = [...map.entries()].filter(([, value]) => value !== undefined && value !== null && value !== "");
+  entries.sort((a, b) => {
+    const ai = EMIT.indexOf(a[0]);
+    const bi = EMIT.indexOf(b[0]);
+    if (ai !== bi) return (ai === -1 ? 999 : ai) - (bi === -1 ? 999 : bi);
+    return a[0] < b[0] ? -1 : 1;
+  });
+  return entries.map(([p, v]) => `${p}:${v}`).join(";");
+}
+
+const EMIT = Object.keys(CSS_ALLOWED);
+
+/**
+ * Replace `var(--name)` with the token's value, following the chain.
+ *
+ * `seen` is the chain, not the whole document: a name may be referenced twice in one
+ * value and only the second visit of the *same* chain is a cycle. Following a cycle
+ * is what `lib/export-html.mjs` did with its own copy of this function, and the
+ * report for a cyclic file was `REFUSED Maximum call stack size exceeded` — no line,
+ * no name, no hint. `docs/plan.md` §4.2 says the chain stops at 16 and that a cycle
+ * is refused; both stops are here so neither can be lost again.
+ */
+// `resolveTokens` is defined in `lib/tokens.mjs`, with the depth limit and the
+// cycle rule it obeys, and re-exported here because this module is where its
+// callers look for it.
+export { resolveTokens };
+
+/** `data-canvas="x,y"`, or null when the page has no stated position. */
+export function canvasPositionOf(node) {
+  const raw = getAttr(node, "data-canvas");
+  if (raw === null) return null;
+  const match = /^\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*$/.exec(raw);
+  if (!match) return null;
+  return { x: Number(match[1]), y: Number(match[2]) };
+}
+
+function cloneTree(node) {
+  if (node.kind === "text") return { kind: "text", value: node.value, raw: node.raw };
+  if (node.kind === "comment" || node.kind === "doctype") return { kind: node.kind, raw: node.raw };
+  return {
+    kind: "element",
+    tag: node.tag,
+    rawTag: node.rawTag,
+    selfClosing: node.selfClosing,
+    attrs: (node.attrs || []).map((a) => ({ ...a })),
+    children: (node.children || []).map(cloneTree),
+  };
+}
+
+// -- the render model --------------------------------------------------------
+
+/**
+ * Build the render model for a parsed document.
+ *
+ * @param {object} doc
+ * @param {object} options `{ resolveTokens: boolean }`
+ * @returns {{ pages: Array, tokens: Map, diagnostics: Array, pageFrame: string }}
+ */
+export function renderModel(doc, options = {}) {
+  const { tokens } = collectTokens(doc);
+  const pages = [];
+  let index = 0;
+
+  for (const node of pagesOf(doc)) {
+    const id = getAttr(node, "data-id") || `page-${index}`;
+    const map = styleMapOf(node);
+    const width = map.get("width") || "auto";
+    const height = map.get("height") || "auto";
+
+    const copy = cloneTree(node);
+
+    // The page's own declarations move to the page box, and the section keeps
+    // only what positions it on the canvas.
+    const boxStyle = new Map();
+    for (const [property, value] of map) boxStyle.set(property, value);
+    boxStyle.set("position", "absolute");
+    const position = canvasPositionOf(node);
+    if (position) {
+      boxStyle.set("left", `${position.x}px`);
+      boxStyle.set("top", `${position.y}px`);
+    }
+    if (boxStyle.get("overflow") === undefined) boxStyle.set("overflow", "hidden");
+
+    pages.push({
+      id,
+      name: getAttr(node, "data-name") || id,
+      width,
+      height,
+      position,
+      index,
+      boxStyle: styleStringOf(boxStyle),
+      declarations: map,
+      // Built from the COPY, not from `node`: a mount never shares the tree the
+      // file was parsed into, so nothing the canvas renders can be mutated back
+      // into the document.
+      markup: copy.children.map((child) => renderNodeHtml(child, tokens, options)).join(""),
+      node: copy,
+    });
+    index += 1;
+  }
+
+  return {
+    pages,
+    tokens,
+    diagnostics: doc.diagnostics || [],
+    pageFrame: pageFrameRule(doc),
+    // Every rule the file states about itself, in document order. A shadow root
+    // cannot see the document's stylesheets, so the canvas has to put them in
+    // the page's own root — and it must put in exactly these, not a reset of its
+    // own invention. A canvas that invents rules renders a document the file
+    // does not describe.
+    styleText: styleTextOf(doc),
+  };
+}
+
+/** The text of every `<style>` block in the document, in order. */
+export function styleTextOf(doc) {
+  return (doc.styleBlocks || []).map((block) => block.text ?? "").filter(Boolean).join("\n");
+}
+
+/**
+ * The same CSS with the `:root{…}` rule removed.
+ *
+ * `:root` matches no element inside a shadow root, so keeping the rule would
+ * define the tokens nowhere. The canvas declares them on `:host` instead; see
+ * `pageCss`.
+ */
+export function withoutRootRule(cssText) {
+  const text = String(cssText ?? "");
+  let out = "";
+  let index = 0;
+  while (index < text.length) {
+    const at = text.indexOf(":root", index);
+    if (at === -1) {
+      out += text.slice(index);
+      break;
+    }
+    const open = text.indexOf("{", at);
+    if (open === -1) {
+      out += text.slice(index);
+      break;
+    }
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < text.length; i += 1) {
+      if (text[i] === "{") depth += 1;
+      else if (text[i] === "}") {
+        depth -= 1;
+        if (depth === 0) { close = i; break; }
+      }
+    }
+    if (close === -1) {
+      out += text.slice(index);
+      break;
+    }
+    out += text.slice(index, at);
+    index = close + 1;
+  }
+  return out.replace(/\n{2,}/g, "\n").trim();
+}
+
+/** The page-frame rule, as the file declares it. */
+export function pageFrameRule(doc) {
+  for (const block of doc.styleBlocks || []) {
+    if (block.role === "page-frame" || block.role === "tokens+page-frame") {
+      const match = /section\s*\[\s*data-type\s*=\s*["']?page["']?\s*\]\s*\{([^}]*)\}/.exec(block.text);
+      if (match) return match[1].trim();
+    }
+  }
+  return "margin:0 0 24px";
+}
+
+/**
+ * Render one node as HTML for a mount.
+ *
+ * The element keeps its tag, its `data-*` attributes and its inline style. That
+ * is what makes the canvas able to map a clicked element straight back to its
+ * `data-id`, and what makes "what you see" the same bytes as "what you export".
+ */
+export function renderNodeHtml(node, tokens, options = {}) {
+  if (node.kind === "text") return escapeText(node.value);
+  if (node.kind === "comment") return node.raw || "";
+  if (node.kind === "doctype") return "";
+  if (node.kind !== "element") return "";
+
+  const attrs = [];
+  for (const attr of node.attrs || []) {
+    if (attr.name === "style") continue;
+    if (attr.value === null || attr.value === undefined) {
+      attrs.push(attr.rawName || attr.name);
+      continue;
+    }
+    attrs.push(`${attr.rawName || attr.name}="${escapeAttr(attr.value)}"`);
+  }
+
+  const styleText = styleForMount(node, tokens, options);
+  if (styleText) attrs.push(`style="${escapeAttr(styleText)}"`);
+
+  const name = node.tag;
+  const head = attrs.length ? `<${name} ${attrs.join(" ")}>` : `<${name}>`;
+  const body = (node.children || []).map((child) => renderNodeHtml(child, tokens, options)).join("");
+  if (VOID_ELEMENTS.has(name)) {
+    // A void element cannot hold children. A hand-written file may still put
+    // them there, so they are emitted after the void element rather than
+    // dropped: a mount must show everything the file contains.
+    return `${head}${body}`;
+  }
+  return `${head}${body}</${name}>`;
+}
+
+/** The inline style a mounted element carries, with tokens resolved or kept. */
+export function styleForMount(node, tokens, options = {}) {
+  const map = styleMapOf(node);
+  if (map.size === 0) return "";
+  if (options.resolveTokens === false) return styleStringOf(map);
+  const out = new Map();
+  for (const [property, value] of map) out.set(property, resolveTokens(value, tokens));
+  return styleStringOf(out);
+}
+
+/**
+ * The full CSS for one page's shadow root.
+ *
+ * A shadow root is what lets the canvas put a page's tokens and page-frame rule
+ * in exactly one scope, without either leaking into the canvas chrome. It is
+ * also why the canvas never has to write its own styles into the design file.
+ *
+ * The rules are the FILE's rules. A canvas that injects a reset of its own makes
+ * the file mean one thing on the canvas and another thing in a browser, and the
+ * author finds out at export time. So the only rule added here is what a shadow
+ * root needs and a document does not: `:host`.
+ */
+export function pageCss(model, options = {}) {
+  const parts = [];
+  // `all: initial` first, and it is not decoration. An inherited property crosses
+  // a shadow boundary: the canvas chrome sets `line-height: 1.5` on the document
+  // so its own panels read well, the page's elements inherit it through the host,
+  // and every label on the canvas is a pixel taller than the same label in the
+  // file. Nothing in the page can override an inheritance it never declared.
+  //
+  // The two declarations after it are what a mount needs and a document gets for
+  // free: a block box, and a positioning context for the overlay.
+  parts.push(":host{all:initial;display:block;position:relative}");
+  // `:root` matches nothing in a shadow tree, so the token values go on the host
+  // element. The rest of the file's CSS is copied as it stands.
+  const declarations = [...(model.tokens ?? new Map()).entries()].map(([name, token]) => `${name}:${token.value}`).join(";");
+  if (declarations) parts.push(`:host{${declarations}}`);
+  const rules = withoutRootRule(model.styleText ?? "");
+  if (rules) parts.push(rules);
+  else parts.push(`section[data-type="page"]{${model.pageFrame || ""}}`);
+  return parts.join("\n");
+}
+
+/**
+ * What the canvas injects into a page's shadow root: the file's rules, plus the
+ * one rule that belongs to the canvas.
+ *
+ * Where a page sits is the canvas's business. `data-canvas` says where, and the
+ * page box is the paper the page is drawn on. A page's outer margin is the
+ * document flow's business: it is what separates one page from the next when the
+ * file is opened in a browser. On the canvas it is nothing, and left in place it
+ * escapes the mount and the paper grows by it — the chrome then paints a 24px
+ * band under every page whose own background is not white. No reader of the file
+ * ever sees that band and the file does not describe it. So the canvas states
+ * the one thing it owns, after the file's rules, and nothing else.
+ */
+export function canvasMountCss(model, options = {}) {
+  return [pageCss(model, options), 'section[data-type="page"]{margin:0}'].join("\n");
+}
+
+/**
+ * The radius the canvas draws a page's paper with.
+ *
+ * The paper is the page's own shape. A page can round its own corners — the
+ * artboard can be a 24px-radius card rather than a screen — and the paper sits behind it.
+ * The chrome's own radius under a page with a bigger one leaves a white crescent
+ * in every corner, a shape the page never drew.
+ *
+ * The value is resolved here, not left to the page. The paper is drawn outside
+ * the shadow root, where the file's tokens are not defined: `var(--radius-lg)`
+ * would compute to nothing there and the corner would come back square.
+ */
+export function pagePaperRadius(page, tokens) {
+  const declared = page?.declarations?.get?.("border-radius");
+  if (!declared) return "";
+  return resolveTokens(declared, tokens);
+}
+
+/** The page box style for a page that sits on the canvas. */
+export function pageBoxStyle(page) {
+  const map = new Map();
+  for (const declaration of parseDeclarations(page.boxStyle)) map.set(declaration.property, declaration.value);
+  return styleStringOf(map);
+}
+
+/**
+ * Where a page sits, with a fallback when the file states no position.
+ * The canvas uses this when `data-canvas` is absent, so a fresh file is not a
+ * pile of pages at the same spot.
+ */
+export function arrangePages(pages, options = {}) {
+  const gap = options.gap ?? 48;
+  const perRow = options.perRow ?? 4;
+  let nextX = 0;
+  let nextY = 0;
+  let rowHeight = 0;
+  let column = 0;
+  return pages.map((page) => {
+    if (page.position) return page.position;
+    const width = parseFloat(page.width) || 390;
+    const height = parseFloat(page.height) || 844;
+    if (column >= perRow) {
+      column = 0;
+      nextX = 0;
+      nextY += rowHeight + gap;
+      rowHeight = 0;
+    }
+    const position = { x: nextX, y: nextY };
+    nextX += width + gap;
+    rowHeight = Math.max(rowHeight, height);
+    column += 1;
+    return position;
+  });
+}
+
+/**
+ * Font families a page uses that a browser does not already have.
+ *
+ * A design may name a family the machine does not have installed. Without a
+ * stylesheet the browser falls back, and the fallback has different metrics: the
+ * same text wraps at a different word and every box below it moves. That is not
+ * a cosmetic difference, it is a layout difference, and it is why the reference
+ * renders of an imported file disagreed with us while their total heights still
+ * matched.
+ *
+ * The list is what the file declares, resolved through its tokens. Nothing is
+ * appended: docs/format-v3.md §2.3 says a font family is written as given.
+ */
+export function webfontFamilies(model) {
+  const found = new Map();
+  const families = (value) => splitTopLevel(String(value ?? ""), ",")
+    .map((part) => decodeQuoteEntities(String(part).trim()).replace(/^["']|["']$/g, "").trim())
+    .filter(Boolean);
+
+  const visit = (node) => {
+    if (node.kind === "element") {
+      const style = styleMapOf(node).get("font-family");
+      if (style) {
+        for (const family of families(resolveTokens(style, model.tokens))) {
+          if (!SYSTEM_FAMILIES.has(family.toLowerCase())) found.set(family, family);
+        }
+      }
+    }
+    for (const child of node.children ?? []) visit(child);
+  };
+  for (const page of model.pages) visit(page.node);
+  return [...found.values()].sort();
+}
+
+/**
+ * One stylesheet URL per family, asking only for the weights a page uses.
+ *
+ * A family with no weights is still requested: the browser needs the family
+ * before it can pick a weight at all. The canvas asks for the same fonts the
+ * export declares, because the two must render the same file at the same text
+ * widths — otherwise the author ships a layout they never saw.
+ */
+export function webfontLinks(model, page) {
+  const families = webfontFamilies(model);
+  if (families.length === 0) return [];
+  const weights = new Set();
+  const visit = (node) => {
+    if (node?.kind === "element") {
+      const weight = styleMapOf(node).get("font-weight");
+      if (weight && /^\d{3}$/.test(weight)) weights.add(Number(weight));
+    }
+    for (const child of node?.children ?? []) visit(child);
+  };
+  // No page means the whole file. The canvas mounts every page at once, so it
+  // asks once for the union; asking per page would register the same family and
+  // weight from several subset files, and the browser would then have two
+  // `@font-face` rules for one face. `export` passes a page, because a
+  // deliverable should request only what it renders.
+  if (page) visit(page.node);
+  else for (const each of model.pages ?? []) visit(each.node);
+  const axis = [...weights].sort((a, b) => a - b);
+  return families.map((family) => {
+    const name = family.replace(/\s+/g, "+");
+    const query = axis.length ? `:wght@${axis.join(";")}` : "";
+    return `https://fonts.googleapis.com/css2?family=${name}${query}&display=swap`;
+  });
+}
+
+/**
+ * The families a browser is expected to have without being asked.
+ *
+ * The test is not "have I heard of it" but "does a stock machine ship it": the
+ * generic families, the three faces every desktop has, and the CJK faces the
+ * three desktop platforms install for their own scripts. `Inter`, `Roboto`,
+ * `Noto Sans` and `Noto Serif` are named by design tools and drawn from a
+ * webfont; a machine that has never installed one falls back, and the fallback
+ * has different metrics, so the design wraps somewhere else. Leaving them off
+ * this list is what makes the canvas and the deliverable ask for them, exactly as
+ * pen's own export does — offline the request fails and the fallback is what it
+ * always was, so nothing gets worse.
+ */
+const SYSTEM_FAMILIES = new Set([
+  "serif", "sans-serif", "monospace", "cursive", "fantasy", "system-ui", "ui-serif",
+  "ui-sans-serif", "ui-monospace", "ui-rounded", "math", "emoji", "fangsong",
+  "-apple-system", "blinkmacsystemfont", "segoe ui", "helvetica", "helvetica neue",
+  "arial", "pingfang sc", "hiragino sans gb",
+  "microsoft yahei", "simsun", "simhei", "wenquanyi micro hei", "source han sans sc",
+]);
+
+function decodeQuoteEntities(value) {
+  return value.replace(/&(?:quot|#0*34|#x0*22);/gi, '"').replace(/&(?:apos|#0*39|#x0*27);/gi, "'");
+}
+
+/** Convenience for a caller that only has text. */
+export function renderText(text, options = {}) {
+  return renderModel(parse(text), options);
+}
+
+/**
+ * Elements in a page, for the layer tree.
+ *
+ * The inside of an `<svg>` is not listed. It is the opaque layer: `<path>`,
+ * `<circle>` and `<title>` are how one glyph draws itself, not nodes a user can
+ * select, and listing them buries the real structure under a hundred rows of
+ * geometry. The glyph's own `<svg>` is listed, with its name.
+ */
+export function pageTree(node, depth = 0, out = [], insideSvg = false) {
+  for (const child of elementChildren(node)) {
+    if (insideSvg) continue;
+    const isGlyph = child.tag === "svg";
+    out.push({
+      id: getAttr(child, "data-id"),
+      type: getAttr(child, "data-type"),
+      tag: child.tag,
+      name: getAttr(child, "data-name"),
+      depth,
+      hidden: getAttr(child, "data-hidden") === "true",
+      childCount: isGlyph ? 0 : elementChildren(child).length,
+      text: textOf(child).trim().slice(0, 60),
+    });
+    pageTree(child, depth + 1, out, isGlyph);
+  }
+  return out;
+}