justskill-design 0.0.1 → 3.2.0

package/lib/export-html.mjs

@@ -0,0 +1,309 @@
+/**
+ * lib/export-html.mjs — a design file to a deliverable.
+ *
+ * A design file is already valid HTML, so "export" is mostly subtraction: take
+ * one page out, drop the design layer's bookkeeping, and make the result stand
+ * on its own.
+ *
+ * What the deliverable keeps:
+ *   - the design's own tags, text and inline styles
+ *   - the token block, unless `resolveTokens` bakes the values into the styles
+ *   - the page's size, as a viewport meta so a browser renders it at that size
+ *
+ * What it drops:
+ *   - `data-id`, `data-type` and every other `data-*` marker. The design layer
+ *     is scaffolding for editing, not part of the page.
+ *   - the page-frame rule, which exists so a file with several pages reads as a
+ *     list. One page does not need it.
+ *   - the page's place on the canvas, which is `data-canvas` and, in a file a
+ *     canvas drag has touched, may also be spelled as `position:absolute` plus
+ *     `left`/`top`. A standalone page is the whole document, so it has nothing
+ *     to be positioned against.
+ *   - `<title>` and `<meta name="design-schema">` are replaced: a deliverable
+ *     needs the page's name, not the file's schema marker.
+ *
+ * What the deliverable takes from the page, rather than drops:
+ *   - the page's own `background-color`, on `<body>`, so the area the page does
+ *     not cover is not a colour the design never chose. See
+ *     `documentBackground`.
+ *
+ * The renderer is shared with the canvas, so what a user dragged is what lands
+ * in the file. There is no second implementation to drift.
+ *
+ * Pure. No node: imports.
+ */
+
+import { renderModel, escapeText, escapeAttr, webfontLinks, withoutRootRule, resolveTokens as resolveTokenValue } from "./render.mjs";
+import { hasBaseRules } from "./base-css.mjs";
+import { parseDeclarations } from "./parse.mjs";
+import { styleMapOf } from "./render.mjs";
+import { compareProperties, PAGE_PLACEMENT } from "./table.mjs";
+
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+const ATTR_ESCAPES = { "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" };
+const TEXT_ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;" };
+
+/** Attributes that belong to the design layer, not to the deliverable. */
+const DESIGN_ATTRS = /^data-(id|type|canvas|name|hidden|locked|kind|icon|icon-library|credit)$/;
+
+export class ExportError extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.name = "ExportError";
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+export function renderPageHtml(model, page, options = {}) {
+  const resolveTokens = options.resolveTokens === true;
+  const renderOptions = { resolveTokens };
+  const body = renderNodeHtml(deliverableRoot(page.node), model.tokens, renderOptions, options);
+
+  const head = [];
+  head.push('<meta charset="utf-8">');
+  head.push(`<title>${escapeText(page.name)}</title>`);
+  head.push(`<meta name="viewport" content="width=${cssLength(page.width)}, height=${cssLength(page.height)}">`);
+
+  // A deliverable declares the fonts it uses. Without this the browser falls
+  // back to a different family, the text wraps at different words, and the
+  // layout below it moves — so a page that looks right on the author's machine
+  // looks wrong on the reviewer's. Only the families the page actually uses are
+  // requested, and only the weights that appear.
+  const fontHrefs = options.fonts === false ? [] : webfontLinks(model, page);
+  for (const href of fontHrefs) head.push(`<link rel="stylesheet" href="${escapeAttr(href)}">`);
+
+  const styles = [];
+  if (!resolveTokens) {
+    // The tokens live in the file's <head>, not on the page, and every
+    // `var(--x)` in the page refers to them. Dropping the block would leave the
+    // deliverable with a broken color on every element that used one — and it
+    // would look fine in the canvas, which is the worst kind of bug.
+    const declarations = tokenDeclarations(model, page.node);
+    if (declarations) styles.push(`:root{${declarations}}`);
+  }
+  styles.push(fileCss(model));
+  head.push(`<style>${styles.join("\n")}</style>`);
+
+  return `<!doctype html>
+<html lang="${escapeAttr(options.lang ?? "zh")}">
+<head>
+${head.map((line) => `  ${line}`).join("\n")}
+</head>
+<body${documentBackground(page, model, resolveTokens)}>
+${body}
+</body>
+</html>
+`;
+}
+
+/**
+ * The document's own surface, taken from the page.
+ *
+ * A deliverable is one page in a document, and the page covers its own box and
+ * nothing more. A viewport taller than the page shows whatever is behind it, and
+ * left white that is a colour the design never chose: in the reference file 13 of
+ * 26 pages are shorter than an 812px screen, the shortest by 339px — 42% of the
+ * screen. Pen's own export writes the frame's fill on `<body>` for the same
+ * reason, and a `.pen` file gives it nowhere else to read one: the format states
+ * no canvas colour.
+ *
+ * The value is copied, not invented, and only when the page states one. A page
+ * whose surface is a gradient or a photograph keeps the plain document: how a
+ * gradient covers an area larger than the page is a second decision, and this is
+ * not the place to make it.
+ */
+function documentBackground(page, model, bakeTokens) {
+  const declared = styleMapOf(page.node).get("background-color");
+  if (!declared) return "";
+  const value = bakeTokens ? resolveTokenValue(declared, model.tokens) : declared;
+  if (!value || value === "transparent") return "";
+  return ` style="background-color:${escapeAttr(value)}"`;
+}
+
+/**
+ * The page as the deliverable sees it: without the canvas's placement.
+ *
+ * `data-canvas` is where a page sits, and the canvas positions it from there. A
+ * canvas drag also used to write that placement as `position:absolute` plus
+ * `left`/`top` on the page itself, which the canvas ignores and the deliverable
+ * does not: the page shipped absolutely positioned at (-85,-352), content
+ * pushed off the top-left corner of its own document. A standalone page is the
+ * whole document, so it has nothing to be positioned against.
+ */
+function deliverableRoot(node) {
+  const raw = (node.attrs ?? []).find((a) => a.name === "style")?.value ?? "";
+  const declarations = parseDeclarations(raw);
+  // A page cannot carry a rotation (`style/transform-on-page`), but export does
+  // not validate the file it is handed, so the declaration is dropped here as
+  // well: the deliverable is the page's own box, and a transform on it would
+  // ship an artboard turned inside a viewport that does not turn with it.
+  const canvasChrome = new Set([...PAGE_PLACEMENT, "transform"]);
+  if (!declarations.some((d) => canvasChrome.has(d.property))) return node;
+  const kept = declarations.filter((d) => !canvasChrome.has(d.property));
+  const style = kept.map((d) => `${d.property}:${d.value}`).join(";");
+  return {
+    ...node,
+    attrs: (node.attrs ?? []).map((a) => (a.name === "style" ? { ...a, value: style } : a)),
+  };
+}
+
+/**
+ * The `:root` declarations for a deliverable: the file's token block, plus any
+ * custom property declared on the page itself. The ones the page mentions win,
+ * because a page may override a token for its own subtree.
+ */
+function tokenDeclarations(model, pageNode) {
+  const found = new Map();
+  for (const [name, token] of model.tokens ?? new Map()) found.set(name, token.value);
+  const styleAttr = (pageNode.attrs ?? []).find((a) => a.name === "style");
+  if (styleAttr && /--/.test(styleAttr.value ?? "")) {
+    for (const declaration of parseDeclarations(styleAttr.value)) {
+      if (declaration.property.startsWith("--")) found.set(declaration.property, declaration.value);
+    }
+  }
+  return [...found.entries()].map(([name, value]) => `${name}:${value}`).join(";");
+}
+
+/**
+ * The rules the deliverable carries.
+ *
+ * These are the FILE's rules, copied. A deliverable is evidence about its
+ * source, and a deliverable that quietly adds a reset its source does not have
+ * proves the wrong thing: it looks right while the file it came from does not.
+ *
+ * The fallback is for a file written before the base block existed. A deliverable
+ * with no box model at all is a broken page, so one is added — and `validate`
+ * reports `style/no-base-rules` on the source, which is where the fix belongs.
+ */
+function fileCss(model) {
+  const rules = withoutRootRule(model.styleText ?? "");
+  if (hasBaseRules(rules)) return rules;
+  return resetCss();
+}
+
+function resetCss() {
+  return [
+    "*,*::before,*::after{box-sizing:border-box}",
+    "html,body{margin:0;padding:0}",
+    "p,h1,h2,h3,h4,h5,h6{margin:0}",
+    "img{display:block;max-width:100%}",
+    // An icon's geometry is stroke-based and carries no fill of its own: the 67
+    // built-in glyphs are paths and circles with no `fill` and no `stroke`, so
+    // the SVG defaults apply and the browser paints every icon as a solid black
+    // shape. These attributes belong on the icon's own `<svg>`, and pen's export
+    // writes them there; they are also what makes `color` on the element tint
+    // the icon.
+    //
+    // The selector matches an icon and nothing else: a built-in glyph is always
+    // `<svg><path|circle>`, with no attribute of its own and no text. A caller
+    // can opt out with `svg[data-fill]`.
+    "svg:not([data-fill]) > :not([fill]):not([stroke]){fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round}",
+  ].join("");
+}
+
+function cssLength(value) {
+  const text = String(value ?? "auto");
+  const match = /^(-?\d+(?:\.\d+)?)(px)?$/.exec(text.trim());
+  if (!match) return text.trim();
+  return `${match[1]}`;
+}
+
+/**
+ * Render one node for a deliverable.
+ *
+ * This is the renderer's node writer with the design attributes removed. It is a
+ * second walk rather than a post-processing regular expression, because a
+ * regular expression over HTML is how a `data-id` ends up inside a text node and
+ * a document gets corrupted.
+ */
+export function renderNodeHtml(node, tokens, renderOptions = {}, options = {}) {
+  if (node.kind === "text") return escapeText(node.value);
+  if (node.kind === "comment") return options.keepComments ? (node.raw ?? "") : "";
+  if (node.kind !== "element") return "";
+
+  const attrs = [];
+  for (const attr of node.attrs ?? []) {
+    if (attr.name === "style") continue;
+    if (DESIGN_ATTRS.test(attr.name)) 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 = serializeStyle(node, tokens, renderOptions);
+  if (styleText) attrs.push(`style="${escapeAttr(styleText)}"`);
+
+  const head = attrs.length ? `<${node.tag} ${attrs.join(" ")}>` : `<${node.tag}>`;
+  const body = (node.children ?? []).map((child) => renderNodeHtml(child, tokens, renderOptions, options)).join("");
+  if (VOID.has(node.tag)) return `${head}${body}`;
+  return `${head}${body}</${node.tag}>`;
+}
+
+/** A node's declarations, in table order, with tokens resolved or kept. */
+export function serializeStyle(node, tokens, renderOptions = {}) {
+  const styleAttr = (node.attrs ?? []).find((a) => a.name === "style");
+  if (!styleAttr || !styleAttr.value) return "";
+  const declarations = parseDeclarations(styleAttr.value);
+  if (declarations.length === 0) return "";
+  const kept = declarations
+    .filter((d) => d.property !== "" && d.value !== "")
+    .map((d, index) => ({
+      property: d.property,
+      value: renderOptions.resolveTokens === false ? d.value : resolveTokenValue(d.value, tokens),
+      index,
+    }))
+    .sort((a, b) => compareProperties(a.property, b.property) || a.index - b.index);
+  return kept.map(({ property, value }) => `${property}:${value}`).join(";");
+}
+
+/**
+ * One page of a design file, as a standalone document.
+ *
+ * @param {object} doc parsed design file
+ * @param {object} options `{ page, resolveTokens, keepComments, lang }`
+ */
+export function exportPage(doc, options = {}) {
+  const model = renderModel(doc, { resolveTokens: options.resolveTokens === true });
+  const pages = model.pages;
+  if (pages.length === 0) {
+    throw new ExportError("export/no-page", "The file has no page to export.", 'Add <section data-id="home" data-type="page">.');
+  }
+
+  let page;
+  if (options.page) {
+    page = pages.find((p) => p.id === options.page);
+    if (!page) {
+      throw new ExportError(
+        "export/unknown-page",
+        `There is no page with data-id ${JSON.stringify(options.page)}.`,
+        `Pages: ${pages.map((p) => p.id).join(", ")}.`,
+      );
+    }
+  } else {
+    page = pages[0];
+  }
+
+  return { html: renderPageHtml(model, page, options), page, model };
+}
+
+/** Every page, each written to a file named after its `data-id`. */
+export function exportAllPages(doc, options = {}) {
+  const model = renderModel(doc, { resolveTokens: options.resolveTokens === true });
+  const wanted = model.pages;
+  if (wanted.length === 0) {
+    throw new ExportError("export/no-page", "The file has no page to export.", null);
+  }
+  return wanted.map((page) => ({
+    page,
+    file: `${page.id}.html`,
+    html: renderPageHtml(model, page, options),
+  }));
+}
+
+/** True when the request asks for something only a browser can produce. */
+export function needsBrowser(format) {
+  return ["png", "jpeg", "jpg", "webp"].includes(String(format).toLowerCase());
+}

package/lib/export-svg.mjs

@@ -0,0 +1,111 @@
+/**
+ * lib/export-svg.mjs — a page as SVG, and as an image.
+ *
+ * ## SVG
+ *
+ * A page becomes one `<svg>` wrapping the HTML in `<foreignObject>`. This needs
+ * no browser, which makes it the only image-ish format that works on a machine
+ * with nothing installed.
+ *
+ * Be honest about what can open it: a browser renders `<foreignObject>` and
+ * Figma, Illustrator and Sketch show a blank rectangle. That is a property of
+ * the format, not a bug to work around, so the export says so.
+ *
+ * ## Raster
+ *
+ * PNG, JPEG and WebP need a browser, and `lib/node/raster-run.mjs` finds one.
+ * When none can be found the export fails and names three ways forward. It does
+ * NOT quietly write an SVG instead: a different format is a different
+ * deliverable, and nobody asked for it.
+ *
+ * Browser-safe for the SVG half. The raster half is in `lib/node/`.
+ */
+
+import { escapeAttr, escapeText } from "./render.mjs";
+
+export class ExportFormatError extends Error {
+  constructor(code, message, hint) {
+    super(message);
+    this.name = "ExportFormatError";
+    this.code = code;
+    this.hint = hint;
+  }
+}
+
+export const IMAGE_FORMATS = new Set(["svg", "png", "jpeg", "jpg", "webp"]);
+
+/**
+ * One page as an SVG document.
+ *
+ * @param {object} options `{ html, page, title }`
+ */
+export function pageToSvg(options) {
+  const html = String(options.html ?? "");
+  const page = options.page ?? {};
+  const width = numberOr(page.width, 390);
+  const height = numberOr(page.height, 844);
+  const title = options.title ?? page.name ?? "design";
+
+  // The body's own markup goes inside the foreignObject. A full document cannot
+  // nest inside an SVG, so the parts that carry meaning are lifted: the styles,
+  // the font links, and the body.
+  const styles = [...html.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/g)].map((m) => m[1]).join("\n");
+  const links = [...html.matchAll(/<link[^>]*>/g)].map((m) => m[0]).join("\n");
+  const body = /<body[^>]*>([\s\S]*?)<\/body>/.exec(html)?.[1] ?? "";
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xhtml="http://www.w3.org/1999/xhtml" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <title>${escapeText(title)}</title>
+  <desc>Rendered from a justSkill design file. A browser draws this; Figma, Illustrator and Sketch show an empty rectangle because they do not implement foreignObject.</desc>
+${links ? `  ${links}\n` : ""}  <style>${styles}
+    .sd-page{width:${width}px;height:${height}px;overflow:hidden;background:#ffffff}
+  </style>
+  <foreignObject x="0" y="0" width="${width}" height="${height}">
+    <xhtml:div class="sd-page" xmlns="http://www.w3.org/1999/xhtml">${body}</xhtml:div>
+  </foreignObject>
+</svg>
+`;
+}
+
+function numberOr(value, fallback) {
+  const parsed = parseFloat(String(value ?? ""));
+  return Number.isFinite(parsed) ? parsed : fallback;
+}
+
+/** A filename-safe extension for a format name. */
+export function extensionFor(format) {
+  const name = String(format).toLowerCase();
+  return name === "jpg" ? "jpeg" : name;
+}
+
+/**
+ * The pixel size one page renders at.
+ *
+ * `--size` wins, then the page's own width and height, then the default. It lives here,
+ * in the pure half, because it is a policy about the document and not about files: the
+ * node half that writes the image should not be where the shape of a page is decided.
+ */
+export function renderSize(page, sizeOption) {
+  const size = parseSize(sizeOption);
+  return {
+    width: size?.width ?? numberOr(page?.width, 390),
+    height: size?.height ?? numberOr(page?.height, 844),
+  };
+}
+
+/** `--size WxH`, or null when it is absent or unreadable. */
+export function parseSize(value) {
+  if (value === undefined || value === null || value === "") return null;
+  const match = /^\s*(\d+(?:\.\d+)?)\s*[x×]\s*(\d+(?:\.\d+)?)\s*$/i.exec(String(value));
+  if (!match) {
+    throw new ExportFormatError("export/bad-size", `--size wants WxH, and got ${JSON.stringify(value)}.`, 'Such as --size 390x844.');
+  }
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+
+/** A scale the browser accepts, so a typo cannot produce a 100× image. */
+export function clampScale(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return 1;
+  return Math.min(3, Math.max(1, Math.round(parsed)));
+}