@quario/docx 0.1.0

package/lib/index.js

@@ -0,0 +1,289 @@
+/**
+ * @quario/docx — the Word render target: a pure consumer of the engine's
+ * public event stream, resolving the bytes of a `.docx` package. A **flow**
+ * target, not a painter: it states the geometry and the typography the preview
+ * shows and lets Word paginate, so a page break is Word's and everything above
+ * one is quario's.
+ *
+ * This module is the entry — the options a host writes, the walk over the
+ * stream, and the parts a package is made of. The writers each event kind
+ * needs live beside it: `body.js` for the paragraphs a report resolves to,
+ * `furniture.js` for the parts a page band becomes, `styles.js` for the base
+ * every part inherits, and `text.js` for the runs all of them are made of.
+ */
+import { walk } from "quario";
+import { bodyOf } from "./body.js";
+import { DOCUMENT_NS, furnish } from "./furniture.js";
+import { STYLES } from "./stylepart.js";
+import { DOCUMENT_PAGES, SECTION_PAGES } from "./text.js";
+import { geometry, pageBox, twips } from "./page.js";
+import { pack } from "./pack.js";
+import { W, XML, esc } from "./xml.js";
+
+const RELS = 'xmlns="http://schemas.openxmlformats.org/package/2006/relationships"';
+const OFFICE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const PACKAGE = "http://schemas.openxmlformats.org/package/2006/relationships";
+const WML = "application/vnd.openxmlformats-officedocument.wordprocessingml";
+
+// The distance from the paper's edge to a header or a footer, in twips: Word's
+// own default, and what the page bands will be laid against.
+const FURNITURE = 720;
+
+/** @type {(msg: string) => never} */
+let err = (msg) => {
+  throw Error(msg);
+};
+
+// Split from `object` below rather than inlined: the three terms together
+// breach the complexity budget `npm run fallow` holds this package to.
+/** @type {(value: any) => boolean} */
+let plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** @type {(value: any, at: string) => any} */
+let object = (value, at) => {
+  // oxlint-disable-next-line no-unused-expressions
+  value === undefined || plain(value) || err(at + ": expected an object");
+  return value;
+};
+
+/** @type {(value: any, keys: string[], at: string) => void} */
+let only = (value, keys, at) => {
+  for (let key in value) if (!keys.includes(key)) err(at + ': unknown option "' + key + '"');
+};
+
+// The three document properties a host may write.
+let PROPERTIES = ["title", "author", "subject"];
+
+// The document properties, validated: strings, and never a date. What a host
+// cannot write is what keeps a render deterministic -- `core.xml` is the one
+// part with a slot for a clock, and it has none of them.
+/** @type {(meta: any) => any} */
+let metaOf = (meta) => {
+  object(meta, "options.meta");
+  only(meta, PROPERTIES, "options.meta");
+  for (let key in meta)
+    // oxlint-disable-next-line no-unused-expressions
+    typeof meta[key] === "string" || err("options.meta." + key + ": expected a string");
+  return meta;
+};
+
+/**
+ * One section. The child order is the schema's and Word is strict about it:
+ * the part references, then `type`, the geometry, `pgNumType`, `cols`, and
+ * `titlePg` last.
+ *
+ * A section that restarts the numbering says so twice — `nextPage` so it opens
+ * on a fresh page, which is the "each instance starts on a fresh page" half of
+ * `reset`, and `pgNumType` for the numbering half. The first section says
+ * neither: it is where the document already was.
+ *
+ * @type {(geo: { width: number, height: number, margin: number }, section: Section) => string}
+ */
+let sectPr = (geo, section) => {
+  let m = twips(geo.margin);
+  return (
+    "<w:sectPr>" +
+    section.refs +
+    breakType(section) +
+    `<w:pgSz w:w="${twips(geo.width)}" w:h="${twips(geo.height)}"/>` +
+    `<w:pgMar w:top="${m}" w:right="${m}" w:bottom="${m}" w:left="${m}"` +
+    ` w:header="${FURNITURE}" w:footer="${FURNITURE}" w:gutter="0"/>` +
+    (section.reset ? '<w:pgNumType w:start="1"/>' : "") +
+    `<w:cols w:num="${section.columns || 1}" w:space="708" w:equalWidth="1"/>` +
+    (section.titlePg ? "<w:titlePg/>" : "") +
+    "</w:sectPr>"
+  );
+};
+
+/** How a section starts relative to the one before it: on a fresh page, where
+ *  it restarts the numbering, and on the same one where it only re-columns.
+ *  @type {(section: Section) => string} */
+let breakType = ({ reset, continuous }) =>
+  reset ? '<w:type w:val="nextPage"/>' : continuous ? '<w:type w:val="continuous"/>' : "";
+
+/** @type {(meta: any) => string} */
+let core = (meta) =>
+  XML +
+  '<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties"' +
+  ' xmlns:dc="http://purl.org/dc/elements/1.1/">' +
+  (meta.title ? `<dc:title>${esc(meta.title)}</dc:title>` : "") +
+  (meta.author ? `<dc:creator>${esc(meta.author)}</dc:creator>` : "") +
+  (meta.subject ? `<dc:subject>${esc(meta.subject)}</dc:subject>` : "") +
+  "</cp:coreProperties>";
+
+/** @typedef {{ reset?: boolean, continuous?: boolean, columns?: number,
+ *   refs: string, titlePg: boolean }} Section */
+
+// The parts every document relates to, in relationship order. A furniture part
+// numbers from after them, and both the content types and the relationships
+// below are one map over the pair, so a part cannot reach the package through
+// one and not the other.
+// A picture's bytes are typed by extension rather than by part name, the way
+// `rels` and `xml` already are: one `Default` covers every image of that kind.
+const IMAGE_TYPES = [
+  ["png", "png"],
+  ["jpeg", "jpeg"],
+];
+
+const FIXED = [
+  { path: "word/settings.xml", target: "settings.xml", kind: "settings", rId: "rId1" },
+  { path: "word/styles.xml", target: "styles.xml", kind: "styles", rId: "rId2" },
+];
+
+// The content type of one furniture part, and the relationship that reaches
+// it. Both are keyed off the same `{ path, kind, rId }` the registry hands
+// back, so a part cannot reach the package through one and not the other.
+/** @type {(part: { path: string, kind: string }) => string} */
+let override = ({ path, kind }) =>
+  `<Override PartName="/${path}" ContentType="${WML}.${kind}+xml"/>`;
+/** @type {(part: { target: string, kind: string, rId: string }) => string} */
+let related = ({ target, kind, rId }) =>
+  `<Relationship Id="${rId}" Type="${OFFICE}/${kind}" Target="${target}"/>`;
+
+/**
+ * The parts of the package. The floor is what Word opens: the content types,
+ * the package relationships and `document.xml` — plus `settings.xml`, which is
+ * not required at all and is here because Word opens a document without one in
+ * Compatibility Mode. `docProps/core.xml` rides only when a host wrote `meta`,
+ * and the header and footer parts only when a band or the marking needs one.
+ *
+ * @type {(body: string, meta: any, furniture: any, rels: any[]) => Record<string, string>}
+ */
+let parts = (body, meta, furniture, rels) => ({
+  "[Content_Types].xml":
+    XML +
+    '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">' +
+    '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+    '<Default Extension="xml" ContentType="application/xml"/>' +
+    `<Override PartName="/word/document.xml" ContentType="${WML}.document.main+xml"/>` +
+    rels.map(override).join("") +
+    IMAGE_TYPES.filter(([ext]) => rels.some((r) => r.target.endsWith("." + ext)))
+      .map(([ext, type]) => `<Default Extension="${ext}" ContentType="image/${type}"/>`)
+      .join("") +
+    (meta
+      ? '<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>'
+      : "") +
+    "</Types>",
+  "_rels/.rels":
+    XML +
+    `<Relationships ${RELS}>` +
+    `<Relationship Id="rId1" Type="${OFFICE}/officeDocument" Target="word/document.xml"/>` +
+    (meta
+      ? `<Relationship Id="rId2" Type="${PACKAGE}/metadata/core-properties" Target="docProps/core.xml"/>`
+      : "") +
+    "</Relationships>",
+  "word/document.xml": XML + `<w:document ${DOCUMENT_NS}><w:body>${body}</w:body></w:document>`,
+  "word/_rels/document.xml.rels":
+    XML + `<Relationships ${RELS}>` + rels.map(related).join("") + "</Relationships>",
+  "word/settings.xml":
+    XML +
+    `<w:settings ${W}><w:compat>` +
+    '<w:compatSetting w:name="compatibilityMode" w:uri="http://schemas.microsoft.com/office/word" w:val="15"/>' +
+    "</w:compat></w:settings>",
+  "word/styles.xml": STYLES,
+  ...furniture.parts,
+  ...(meta ? { "docProps/core.xml": core(meta) } : {}),
+});
+
+/**
+ * The Word render target:
+ * `quario().report(schema).render(docx({ page }), data)` resolves the document
+ * bytes described in SCHEMA.md ("The DOCX target"). Options are taken and
+ * validated at the factory call.
+ *
+ * @param {any} [options] Host controls: `page` and `meta`.
+ * @returns {{name: "docx", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function docx(options) {
+  object(options, "options");
+  only(options, ["page", "meta"], "options");
+  let page = object(options?.page, "options.page");
+  let meta = metaOf(options?.meta);
+  // The size fails here rather than at the first render: a host wrote it, so
+  // a host hears about it where it was written. The margin is validated again
+  // per render, because the document may be the one declaring it.
+  pageBox(page, "options.page");
+  /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
+  let compile = (stream) => async (data) => {
+    // The sections are written after the walk, so the opening event is taken
+    // in its handler rather than peeked ahead of the driver: the margin a
+    // document may declare instead of the host is settled by the time any
+    // second event is pulled, and the stream reaches `walk` unwrapped. The
+    // walk is what spends the render's budget and breathes for the host
+    // meanwhile.
+    let geo = geometry(page);
+    // Every relationship the document carries, in one place: the parts it
+    // always has, then whatever the furniture and the body ask for. One
+    // allocator, because a page band and the body both draw pictures and two
+    // would hand out the same number twice.
+    /** @type {{ path: string, target: string, kind: string, rId: string }[]} */
+    let rels = [...FIXED];
+    /** @type {Record<string, Uint8Array>} */
+    let media = {};
+    /** @type {(kind: string, target: string) => string} */
+    let relate = (kind, target) => {
+      let rId = "rId" + (rels.length + 1);
+      rels.push({ path: "word/" + target, target, kind, rId });
+      return rId;
+    };
+    // One part per distinct picture. Keyed on the bytes themselves: the
+    // page-band probe reads each band twice and every section reads it again,
+    // and a logo that arrived by reading a field is the same array each time,
+    // so the part -- and the header XML naming it -- stays identical and the
+    // furniture's own dedup still collapses the sections. A `source` that
+    // *computes* fresh bytes per call writes a part per call, which is
+    // wasteful and still correct.
+    /** @type {Map<Uint8Array, string>} */
+    let drawn = new Map();
+    /** @type {(event: any) => string} */
+    let picture = (event) => {
+      let seen = drawn.get(event.bytes);
+      if (seen) return seen;
+      let target = "media/image" + (drawn.size + 1) + "." + event.format;
+      media["word/" + target] = event.bytes;
+      let rId = relate("image", target);
+      drawn.set(event.bytes, rId);
+      return rId;
+    };
+    let furniture = furnish();
+
+    /** @type {(kind: any) => Section} */
+    let section = (kind) => ({
+      ...kind,
+      ...furniture.refsFor(kind.reset ? SECTION_PAGES : DOCUMENT_PAGES),
+    });
+    let body = bodyOf(section);
+    await walk(stream(data), {
+      ...body.handlers,
+      "report-start": (event) => {
+        geo = geometry(page, event);
+        // What a render carries that the events do not, settled once and handed
+        // to both writers: a fifth instance field must be read here and nowhere
+        // else (`furniture.js`, `Ctx`).
+        let ctx = {
+          base: event.style || null,
+          intl: { locale: event.locale, currency: event.currency, timeZone: event.timeZone },
+          width: geo.width - 2 * geo.margin,
+          picture,
+        };
+        furniture = furnish(event.page, event.marking, relate, ctx);
+        body.start(ctx, event);
+      },
+    });
+    // A stream that opened no section at all -- one walked from part-way
+    // through, which the driver allows -- still describes a page.
+    // oxlint-disable-next-line no-unused-expressions
+    body.sections.length || body.sections.push(section({}));
+    return pack({
+      ...parts(
+        body.xml((s) => sectPr(geo, s)),
+        meta,
+        furniture,
+        rels,
+      ),
+      ...media,
+    });
+  };
+  return { name: "docx", compile };
+}

package/lib/pack.js

@@ -0,0 +1,35 @@
+/**
+ * The package: named parts in, one zip out. The **only** module that imports
+ * fflate, which is what makes the writer a seam — a later one (a sibling OOXML
+ * writer, `CompressionStream`) replaces this file and nothing else.
+ *
+ * Only the synchronous names are ever called. The asynchronous family would
+ * reach for a worker built from a string, and the suites run under
+ * `--disallow-code-generation-from-strings` with the browser page under a
+ * `default-src 'none'` policy, so the path this target takes is proved rather
+ * than promised.
+ */
+import { strToU8, zipSync } from "fflate";
+
+// Every entry's modification time, pinned. A zip stamps each local header with
+// the clock, so without this two renders of one report differ in bytes and no
+// digest could pin anything. fflate builds the DOS stamp from the local-time
+// getters, so this is a local 1980-01-01 rather than an epoch instant.
+let EPOCH = new Date(1980, 0, 1);
+
+/**
+ * Pack the parts of an OOXML package.
+ *
+ * @param {Record<string, string | Uint8Array>} parts Part paths to their
+ *   contents: XML as a string, a picture's bytes as they arrived.
+ * @returns {Uint8Array} The zip, byte-identical for byte-identical parts.
+ */
+export let pack = (parts) => {
+  /** @type {Record<string, Uint8Array>} */
+  let entries = {};
+  for (let path in parts) {
+    let part = parts[path];
+    entries[path] = typeof part === "string" ? strToU8(part) : part;
+  }
+  return zipSync(entries, { level: 6, mtime: EPOCH });
+};

package/lib/page.js

@@ -0,0 +1,111 @@
+// fallow-ignore-file duplicate-export -- this module is the sanctioned copy of `packages/layout/lib/page.js` and keeps its names on purpose: `test/page-sizes.test.js` imports both and compares what each answers, which only works while the two spell the page the same way (ADR 0039).
+/**
+ * The page box: what a host's `page` option means in points, and the twips a
+ * section states it in. A **deliberate copy** of `packages/layout/lib/page.js`
+ * — the rules and their wording, not the frame derivation this target has no
+ * use for, because Word does the paginating.
+ *
+ * ADR 0039 gates the page-size table to one home, and `test/page-sizes.test.js`
+ * is that gate: a second table is a size that means one thing here and another
+ * there. This target is the one consumer that cannot reach the layout's — a
+ * flow target measures nothing, and taking `@quario/layout` would install the
+ * pagination engine and its font metrics for a two-entry table (ADR 0014: a
+ * target imports only public engine helpers). So the copy is hand-synced under
+ * that same gate, which asserts this table and these wordings against the
+ * layout's: change one and change the other, or the gate fails.
+ */
+
+// The named sizes, in points, exactly as `@quario/layout` states them; the
+// conversion to twips happens at use, so the two tables stay comparable.
+// fallow-ignore-next-line code-duplication -- @quario/docx keeps a deliberate copy of these rules: a flow target runs no layout, and taking @quario/layout for a two-entry table would install the pagination engine with it. test/page-sizes.test.js holds the two in sync (ADR 0039).
+let SIZES = /** @type {Record<string, [number, number]>} */ ({
+  A4: [595.28, 841.89],
+  letter: [612, 792],
+});
+
+/** @type {(msg: string) => never} */
+let err = (msg) => {
+  throw Error(msg);
+};
+
+/** @type {(value: number) => boolean} */
+let positive = (value) => Number.isFinite(value) && value > 0;
+
+/** @type {(size: any) => any} */
+let known = (size) => (Object.hasOwn(SIZES, size) ? SIZES[size] : null);
+
+/** @type {(size: any, at: string) => any} */
+let named = (size = "A4", at) => {
+  let dimensions = Array.isArray(size) ? size : known(size);
+  // oxlint-disable-next-line no-unused-expressions
+  dimensions || err(at + '.size: unknown page size "' + size + '"');
+  return dimensions;
+};
+
+/** @type {(dimensions: any, at: string) => { width: number, height: number }} */
+let pair = (dimensions, at) => {
+  let width = +dimensions[0],
+    height = +dimensions[1];
+  // oxlint-disable-next-line no-unused-expressions
+  (positive(width) && positive(height)) || err(at + ".size: expected finite positive dimensions");
+  return { width, height };
+};
+
+/** @type {(margin: any, width: number, height: number, path: string) => number} */
+let marginOf = (margin = 54, width, height, path) => {
+  let fits = Number.isFinite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
+  // oxlint-disable-next-line no-unused-expressions
+  fits || err(path + ": expected a non-negative number smaller than half the page");
+  return margin;
+};
+
+// Size is settled at the factory; margin may come from the document's
+// `report-start`, so a render peeks that event before writing a section.
+/** @type {(page: any) => any} */
+let hostMargin = (page) => (Object.hasOwn(page, "margin") ? page.margin : undefined);
+/** @type {(opening: any) => any} */
+let docMargin = (opening) => opening?.margin;
+/** @type {(doc: any, host: any) => boolean} */
+let bothMargins = (doc, host) => doc != null && host !== undefined;
+/** @type {(opening: any, page: any, at: string) => { value: any, path: string }} */
+let marginChoice = (opening, page, at) => {
+  let host = hostMargin(page);
+  let doc = docMargin(opening);
+  if (bothMargins(doc, host)) err("page.margin: document and target both declare a margin");
+  return { value: doc ?? host, path: doc != null ? "page.margin" : at + ".margin" };
+};
+
+/**
+ * The page box a `page` option describes, validated: width, height and margin
+ * in points. `at` prefixes the failure, so a host hears where it wrote the
+ * mistake.
+ *
+ * @param {any} page The `page` option, or undefined for the defaults.
+ * @param {string} [at] The option's name in a failure.
+ * @returns {{ width: number, height: number, margin: number }}
+ */
+export let pageBox = (page, at = "page") => {
+  let { width, height } = pair(named(page?.size, at), at);
+  return { width, height, margin: marginOf(page?.margin, width, height, at + ".margin") };
+};
+
+/**
+ * The page box for a render: the host's size, and whichever margin the host
+ * and the opening event agreed on.
+ *
+ * @type {(page: any, opening?: any) => { width: number, height: number, margin: number }}
+ */
+export let geometry = (page = {}, opening) => {
+  let { width, height } = pageBox(page, "options.page");
+  let chosen = marginChoice(opening, page, "options.page");
+  return { width, height, margin: marginOf(chosen.value, width, height, chosen.path) };
+};
+
+/**
+ * Points as twips, the unit WordprocessingML states a page in. Rounded, not
+ * truncated: A4's 595.28 x 841.89 pt lands on 11906 x 16838, the twips Word
+ * itself writes, where truncation would be a twip short of both.
+ *
+ * @type {(points: number) => number}
+ */
+export let twips = (points) => Math.round(points * 20);

package/lib/picture.js

@@ -0,0 +1,91 @@
+/**
+ * An [image item](../../../SCHEMA.md#image-item) as an inline picture. Never
+ * floating: a flow target states the document and lets Word lay it out, and a
+ * floating anchor is a position this target has no page to position against.
+ *
+ * The size is the picture's own, read by the engine out of the file header, at
+ * 96 dpi and capped at the text width — `fit: "width"` scales it to that width
+ * instead. Word measures a drawing in EMUs, 914400 to the inch, so a pixel is
+ * 9525 of them.
+ */
+import { text } from "quario";
+import { esc } from "./xml.js";
+
+const DRAWING = "http://schemas.openxmlformats.org/drawingml/2006";
+const WP = `xmlns:wp="${DRAWING}/wordprocessingDrawing"`;
+const A = `xmlns:a="${DRAWING}/main"`;
+const PIC = `xmlns:pic="${DRAWING}/picture"`;
+const REL = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+
+/** EMUs per pixel at 96 dpi, and per point. */
+const PER_PIXEL = 9525;
+const PER_POINT = 12700;
+
+/**
+ * The size one picture is drawn at, in EMUs: its own, capped at the text width,
+ * or scaled to that width where the author declared `fit: "width"`. The aspect
+ * ratio is kept either way, so a cap is a scale and never a crop.
+ *
+ * @type {(event: any, width: number) => { cx: number, cy: number }}
+ */
+export let sizeOf = (event, width) => {
+  let limit = width * PER_POINT;
+  let natural = event.width * PER_PIXEL;
+  let scale = event.fit === "width" ? limit / natural : Math.min(1, limit / natural);
+  return {
+    cx: Math.max(1, Math.round(natural * scale)),
+    cy: Math.max(1, Math.round(event.height * PER_PIXEL * scale)),
+  };
+};
+
+/**
+ * The drawing. `id` numbers the picture within the document, `rId` names the
+ * part its bytes live in, and `descr` carries the rendered `alt` — this is the
+ * first target after HTML to write one, so a reader's own accessibility tools
+ * see what the author wrote.
+ *
+ * @type {(event: any, id: number, rId: string, alt: string, size: { cx: number, cy: number }) => string}
+ */
+export let drawing = (event, id, rId, alt, size) => {
+  let extent = `<wp:extent cx="${size.cx}" cy="${size.cy}"/>`;
+  // Word's own wording for a drawing with no name of its own. Deliberately not
+  // the media file's name: the id numbers the drawing, and a picture reused in
+  // two places is one part under two drawings.
+  let name = "Picture " + id;
+  return (
+    `<w:r><w:drawing><wp:inline ${WP} ${A} ${PIC} distT="0" distB="0" distL="0" distR="0">` +
+    extent +
+    `<wp:docPr id="${id}" name="${esc(name)}" descr="${esc(alt)}"/>` +
+    "<a:graphic><a:graphicData " +
+    `uri="${DRAWING}/picture">` +
+    "<pic:pic><pic:nvPicPr>" +
+    `<pic:cNvPr id="${id}" name="${esc(name)}" descr="${esc(alt)}"/>` +
+    "<pic:cNvPicPr/></pic:nvPicPr>" +
+    `<pic:blipFill><a:blip xmlns:r="${REL}" r:embed="${rId}"/>` +
+    "<a:stretch><a:fillRect/></a:stretch></pic:blipFill>" +
+    '<pic:spPr><a:xfrm><a:off x="0" y="0"/>' +
+    `<a:ext cx="${size.cx}" cy="${size.cy}"/></a:xfrm>` +
+    '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></pic:spPr>' +
+    "</pic:pic></a:graphicData></a:graphic></wp:inline></w:drawing></w:r>"
+  );
+};
+
+/**
+ * A picture's description, joined through the engine's own display rule — so a
+ * `Date` in an `alt` reads as ISO 8601 UTC here as it does everywhere else, and
+ * the bytes do not move with the host's zone.
+ *
+ * @type {(event: any) => string}
+ */
+export let describe = (event) => text(event.alt || []);
+
+/**
+ * The number that names a drawing: its relationship's. One id space for the
+ * whole document, which is what `docPr` wants — a counter per writer hands the
+ * same number to a page band's picture and the body's — and stable across the
+ * two readings of a band, where a running count would move and make every band
+ * holding a logo look like one that differs on the first page.
+ *
+ * @type {(rId: string) => number}
+ */
+export let idOf = (rId) => Number(rId.slice(3));