@quario/docx 0.1.0

package/lib/body.js

@@ -0,0 +1,340 @@
+/**
+ * The document body: the paragraphs, tables and pictures a report resolves to,
+ * and the two hints that move the document rather than occupy it.
+ *
+ * **Sections.** A `reset: "page"` instance starts a fresh page-number sequence,
+ * which Word spells as a section. A section break lives in the properties of
+ * the paragraph the section ends on, so it is folded into the last one the
+ * section held; a section that held none writes a paragraph for it, because
+ * there is nowhere else for the break to go. An instance with nothing at all
+ * before it does not end a section — it *is* the document's first one, which is
+ * SCHEMA.md's "an instance already at the top of a page does not force an empty
+ * page".
+ *
+ * **Page breaks.** `break: "page"` is `pageBreakBefore` on the instance's first
+ * paragraph, skipped where the instance also declared `reset`, whose section has
+ * already turned the page, and where it has nothing before it at all.
+ *
+ * **Page columns.** A count on the report columns the body's own sections; a
+ * count on a group wraps each instance in *continuous* section breaks, so the
+ * columns start and stop where the instance does without turning a page. Word
+ * and Writer draw any count; Google Docs draws at most three, which is the
+ * matrix's approximation here.
+ *
+ * **Headings.** A group header's *first* item takes `Heading{depth + 1}`, the
+ * way the PDF titles its outline entry by the first header text; the rest are
+ * plain paragraphs. The report header stays out of the outline entirely — the
+ * outline mirrors the group tree — so it wears its role default and no style.
+ *
+ * **Layers.** Outward-in: this target's baseline (`docDefaults`, so nothing is
+ * written per run), the report default, the band-role default, then the node's
+ * own — SCHEMA.md, "Style declarations". A `false` in an inner layer is a
+ * declaration and wins, which a plain overwrite already gives.
+ */
+import { headingAt } from "./stylepart.js";
+import { paraProps, under } from "./style.js";
+import { grid, record, splitting, tbl } from "./table.js";
+import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { EMPTY_CTX } from "./furniture.js";
+import { looking, paragraph, runs } from "./text.js";
+
+// The band roles this target supplies a default for, and the only look it puts
+// on a report that declared nothing. ADR 0014: a target supplies defaults where
+// its consumer has no seam to supply them, and a document is final on open.
+// `test/omakase-defaults.test.js` holds this copy and the other two in
+// agreement; it is not shared code, and that is the ADR's point.
+/** @type {Record<string, any>} */
+const ROLES = {
+  "report-header": { bold: true, size: 14 },
+  "group-header": { bold: true },
+};
+
+// The cell padding this target supplies on a side the author did not name: 6 pt
+// across, 2 pt down, the layout's own numbers. A named `0` beats it, which is
+// what makes the declaration a declaration (`docs/adr/0040`).
+const PAD = { top: 2, left: 6, bottom: 2, right: 6 };
+
+// The structural gap a group instance opens with, so groups read as blocks
+// without authored margins, and the band gap a table closes with. Half a line
+// of the base type at the lead `stylepart.js` writes -- 0.5 * 1.4 * 10 -- which
+// is the layout's own `instanceGap`, in points.
+const GAP = 7;
+
+// The space Word leaves between page columns, in twips: its own default, and
+// what `index.js` writes into every `cols`.
+const GUTTER = 708;
+
+// Nothing here names a sequence: a body cell can never hold a live field,
+// because only a page band binds the `page` anchor, so `looking` defaults to
+// the document's own and nothing below carries one.
+
+/**
+ * One report's body, built as the walk hands it events.
+ *
+ * @param {(kind: any) => any} section Opens a section of the given kind and
+ *   returns it; the caller owns what a section knows about its furniture.
+ */
+export let bodyOf = (section) => {
+  /** @type {{ props: string, inner: string, closes?: any, raw?: boolean }[]} */
+  let blocks = [];
+  /** @type {any[]} */
+  let sections = [];
+  // What the next paragraph is still owed. A break is markup; the structural
+  // gap is a *style layer* rather than a `<w:spacing>` of its own, because a
+  // paragraph carries one `spacing` element and the author may have declared
+  // it -- so the gap layers under their own `spaceBefore`, which then wins.
+  let owed = { broken: false, gapped: false };
+  // The heading a group instance's *first* header item is still owed, set when
+  // the instance opens and taken by whichever item claims it. One string rather
+  // than a depth and a flag: the two only ever moved together.
+  let heading = "";
+  /** What a render carries that the events do not: the report default, the
+   *  instance's `format` configuration, the text column and the picture
+   *  registry. Settled once, on the opening event, and read-only after —
+   *  `furniture.js`'s `Ctx`, so the two writers describe a render one way.
+   *  @type {import("./furniture.js").Ctx} */
+  let ctx = EMPTY_CTX;
+  /** The table being filled, if any: its grid, and the rows written so far. */
+  /** @type {{ widths: number[], rows: string } | null} */
+  let table = null;
+  /** The split being filled, if any. Splits never nest, so one is enough. */
+  /** @type {ReturnType<typeof splitting> | null} */
+  let split = null;
+
+  // `CT_PPr` is a sequence and not a bag: `pStyle` is its first child,
+  // `pageBreakBefore` its fourth, and everything `paraProps` writes comes after
+  // both. The order here is the contract.
+  /** @type {(props: string, style: any, inner: string) => void} */
+  let push = (props, style, inner) => {
+    let look = owed.gapped ? under({ spaceBefore: GAP }, style) : style;
+    blocks.push({
+      props: props + (owed.broken ? "<w:pageBreakBefore/>" : "") + paraProps(look),
+      inner,
+    });
+    owed = { broken: false, gapped: false };
+  };
+
+  /** A block that is not a paragraph -- a table -- which carries no properties
+   *  and so cannot take what the next paragraph is owed.
+   *  @type {(inner: string) => void} */
+  let block = (inner) => {
+    blocks.push({ props: "", inner, raw: true });
+  };
+
+  let sectionStart = 0;
+  /** @type {(kind: any) => void} */
+  let open = (kind) => {
+    sectionStart = blocks.length;
+    sections.push(section(kind));
+  };
+
+  /** The report's own page-column count, and the depths of the instances that
+   *  opened a columned section, so `group-end` knows whose to close. */
+  let columns = 1;
+  /** @type {number[]} */
+  let columned = [];
+  /** @type {(value: any) => number} */
+  let counted = (value) => (Number.isInteger(value) && value > 1 ? value : 0);
+
+  /** @type {(own: import("./furniture.js").Ctx, event: any) => void} */
+  let start = (own, event) => {
+    ctx = own;
+    columns = counted(event.columns) || 1;
+    open({ columns });
+  };
+
+  /** The style a node wears: the report default, its role's, then its own. */
+  /** @type {(event: any) => any} */
+  let styleOf = (event) =>
+    under(
+      under(ctx.base, Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null),
+      event.style,
+    );
+
+  /** @type {(event: any) => void} */
+  let breakBefore = (event) => {
+    // oxlint-disable-next-line no-unused-expressions
+    owed.broken ||= event.break === "page" && blocks.length > 0;
+  };
+
+  // A section ends on the last paragraph it held, so that is where its break
+  // goes. A section that held none gets a paragraph written for it -- and so
+  // does one whose last block is a table, which carries no properties for a
+  // break to live in. What the next instance is owed is untouched either way:
+  // this paragraph belongs to the section closing, not to the one opening.
+  let closeSection = () => {
+    let last = blocks.at(-1);
+    // oxlint-disable-next-line no-unused-expressions
+    (blocks.length === sectionStart || last?.raw) && blocks.push({ props: "", inner: "" });
+    /** @type {any} */ (blocks.at(-1)).closes = sections.at(-1);
+  };
+
+  /**
+   * The hints that move the document rather than occupy it. `reset` opens a
+   * section on a fresh page; a page-column count opens one that continues on
+   * the same page. An instance declaring both gets one section, which turns the
+   * page — a page already fresh does not turn twice.
+   *
+   * @type {(event: any) => void}
+   */
+  let group = (event) => {
+    heading = `<w:pStyle w:val="${headingAt(event.depth)}"/>`;
+    // A structural half-line before every instance, dropped where the document
+    // has not started: groups read as blocks without authored margins.
+    // oxlint-disable-next-line no-unused-expressions
+    owed.gapped ||= blocks.length > 0;
+    let own = counted(event.columns);
+    let kind = sectionFor(event.reset === "page", own);
+    if (!kind) return breakBefore(event);
+    // Its own count is what `group-end` closes; a section that merely inherits
+    // the report's is not one this instance opened.
+    // oxlint-disable-next-line no-unused-expressions
+    own && columned.push(event.depth);
+    reopen(kind);
+  };
+
+  /** The section an instance opens, or null where it opens none and is at most
+   *  a page break on its own first paragraph.
+   *  @type {(resets: boolean, own: number) => any} */
+  let sectionFor = (resets, own) =>
+    resets || own ? { reset: resets, continuous: !resets, columns: own || columns } : null;
+
+  /** Close the section this instance interrupts and open its own — unless
+   *  nothing at all has been written, in which case this instance opens the
+   *  document rather than ending anything, and the section it would have ended
+   *  becomes its own.
+   *  @type {(kind: any) => void} */
+  let reopen = (kind) => {
+    if (!blocks.length) return void (sections[sections.length - 1] = section(kind));
+    closeSection();
+    open(kind);
+  };
+
+  /** @type {(event: any) => void} */
+  let groupEnd = (event) => {
+    if (columned.at(-1) !== event.depth) return;
+    columned.pop();
+    reopen({ continuous: true, columns: columns });
+  };
+
+  /**
+   * The paragraph properties an item's role earns: the heading its instance is
+   * owed, on a group instance's *first* header item, and nothing anywhere else.
+   *
+   * @type {(role: string) => string}
+   */
+  let claimHeading = (role) => {
+    if (role !== "group-header") return "";
+    let owes = heading;
+    heading = "";
+    return owes;
+  };
+
+  /** One item or picture, as the content of the paragraph it becomes. `column`
+   *  is what caps a picture: the text column, or the slot holding it.
+   *  @type {(event: any, style: any, column?: number) => string} */
+  let contentOf = (event, style, column = columnWidth()) =>
+    event.type === "image"
+      ? pictureRun(event, column)
+      : runs(event.tokens, looking(style, ctx.intl));
+
+  /** @type {(event: any, column: number) => string} */
+  let pictureRun = (event, column) => {
+    let rId = ctx.picture(event);
+    return drawing(event, idOf(rId), rId, describe(event), sizeOf(event, column));
+  };
+
+  /** How wide the body is where it is being written: the text column, divided
+   *  between the [page columns](../../../SCHEMA.md#page-columns) of the section
+   *  it lands in, less the gutter between them. `708` twips is Word's own. */
+  let columnWidth = () => {
+    let count = sections.at(-1)?.columns || 1;
+    return (ctx.width - (GUTTER / 20) * (count - 1)) / count;
+  };
+
+  /** @type {(event: any) => void} */
+  let itemOf = (event) => {
+    if (split) {
+      let own = under(split.style, event.style);
+      return split.slot(own, (column) => contentOf(event, own, column));
+    }
+    let style = styleOf(event);
+    push(claimHeading(event.role), style, contentOf(event, style));
+  };
+
+  /** @type {(event: any) => void} */
+  let splitStart = (event) => {
+    split = splitting(event.slots, columnWidth(), styleOf(event));
+  };
+
+  let splitEnd = () => {
+    // oxlint-disable-next-line no-unused-expressions
+    split && block(split.close());
+    split = null;
+  };
+
+  /** What a table's cells are written with. `intl` is settled on the opening
+   *  event, so it is read here rather than captured at compile.
+   *  @type {() => { pad: Record<string, number>, intl: any }} */
+  let ruled = () => ({ pad: PAD, intl: ctx.intl });
+
+  /** @type {(event: any) => void} */
+  let tableStart = (event) => {
+    let widths = grid(
+      event.columns.map((/** @type {any} */ c) => (Number.isFinite(c.width) ? c.width : null)),
+      columnWidth(),
+    );
+    table = {
+      widths,
+      rows: record(event.header.cells, widths, true, under(ctx.base, event.header.style), ruled()),
+    };
+  };
+
+  /** @type {(event: any) => void} */
+  let row = (event) => {
+    // oxlint-disable-next-line no-unused-expressions
+    table &&
+      (table.rows += record(
+        event.cells,
+        table.widths,
+        false,
+        under(ctx.base, event.style),
+        ruled(),
+      ));
+  };
+
+  let tableEnd = () => {
+    // oxlint-disable-next-line no-unused-expressions
+    table && block(tbl(table.rows, table.widths));
+    table = null;
+    // The band gap the PDF leaves after a table, owed to whatever comes next.
+    owed.gapped = true;
+  };
+
+  return {
+    sections,
+    start,
+    handlers: {
+      "group-start": group,
+      "group-end": groupEnd,
+      item: itemOf,
+      image: itemOf,
+      "split-start": splitStart,
+      "split-end": splitEnd,
+      "table-start": tableStart,
+      row,
+      "total-row": row,
+      "table-end": tableEnd,
+    },
+    /** @type {(sectPr: (section: any) => string) => string} */
+    xml: (sectPr) =>
+      blocks
+        .map(
+          (b) =>
+            /** @type {any} */ (b).raw
+              ? b.inner
+              : paragraph(b.props + (b.closes ? sectPr(b.closes) : ""), b.inner),
+        )
+        .join("") + sectPr(sections.at(-1)),
+  };
+};

package/lib/furniture.js

@@ -0,0 +1,214 @@
+/**
+ * The page bands as Word furniture: the header and footer parts a section
+ * references, and the unlicensed marking that rides in every footer.
+ *
+ * A flow target has no pages of its own, so it cannot draw a band per page. It
+ * states each band once and lets Word repeat it, and the two things a band can
+ * say about the page it sits on are answered separately.
+ *
+ * *Which* page becomes a Word **field**: the engine tags a token whose
+ * interpolation is exactly `{{ page.number }}` or `{{ page.total }}` (see
+ * CONTEXT.md, "Live field"), and this module writes `PAGE` / `NUMPAGES` there
+ * so the reader's application recomputes the number as the document
+ * repaginates. Anything computed from a page value is ordinary text, frozen at
+ * what the probe below saw.
+ *
+ * *Where* on the page comes from the **probe**: the band closure is evaluated
+ * at page 1 of 2 and at page 2 of 2, and the two results are compared. Equal —
+ * which is what a band holding nothing but fields and literal text is — means
+ * one part and no `titlePg`; different means a first-page part, a default one,
+ * and `titlePg` in the section. The probe assumes a total of two, so a band
+ * gated on `page.total` sees 2, exactly as the PDF target's height probe does.
+ */
+import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { paraProps, under } from "./style.js";
+import { splitting } from "./table.js";
+import { looking, paragraph, run, runs } from "./text.js";
+import { R, W, XML } from "./xml.js";
+
+// The two pages every band is read at, in order: the first of two, then a
+// later one. Two is the whole of what the probe assumes about the document.
+const PROBE = [
+  { number: 1, total: 2 },
+  { number: 2, total: 2 },
+];
+
+// The marking's best-effort look: a mid grey at 7 pt (half-points). Its
+// presence and its place — the first paragraph of the part, its own paragraph
+// — are what the spec fixes; this is not.
+const MARKING_LOOK = '<w:color w:val="808080"/><w:sz w:val="14"/>';
+
+/**
+ * One band's events as the blocks they become: an item or a picture is a
+ * paragraph, a split is a borderless one-row table, and the bracket is filled
+ * exactly as the body fills one — `splitting` is the shared rule, so the two
+ * cannot drift on what a split is.
+ *
+ * `ctx` is what a render carries that the events do not: the report default
+ * every band item wears under its own, the instance's `format` configuration,
+ * the text column a picture is capped at, and the registry a picture's bytes
+ * become a part in.
+ *
+ * @type {(events: any[], ctx: Band) => string}
+ */
+let banded = (events, ctx) => {
+  /** @type {{ out: string, split: ReturnType<typeof splitting> | null }} */
+  let state = { out: "", split: null };
+  for (let e of events) STEPS.get(e.type)?.(state, e, ctx);
+  return state.out;
+};
+
+/** @type {(state: any, e: any, ctx: Band) => void} */
+let open = (state, e, ctx) => {
+  state.split = splitting(e.slots, ctx.width, under(ctx.base, e.style));
+};
+
+/** @type {(state: any) => void} */
+let close = (state) => {
+  state.out += state.split ? state.split.close() : "";
+  state.split = null;
+};
+
+/** One item or picture, into the split being filled or into the band itself.
+ *  @type {(state: any, e: any, ctx: Band) => void} */
+let draw = (state, e, ctx) => {
+  if (state.split) {
+    let own = under(state.split.style, e.style);
+    return state.split.slot(own, (/** @type {number} */ column) => content(e, own, column, ctx));
+  }
+  let style = under(ctx.base, e.style);
+  state.out += paragraph(paraProps(style), content(e, style, ctx.width, ctx));
+};
+
+// What each kind of band event does to the band being built. An event this does
+// not know contributes nothing rather than failing, which is what lets a
+// consumer written before an event kind existed go on working.
+/** @type {Map<string, (state: any, e: any, ctx: Band) => void>} */
+const STEPS = new Map([
+  ["split-start", open],
+  ["split-end", close],
+  ["item", draw],
+  ["image", draw],
+]);
+
+/**
+ * One item's or picture's content.
+ *
+ * @type {(e: any, style: any, column: number, ctx: Band) => string}
+ */
+let content = (e, style, column, ctx) => {
+  if (e.type !== "image") return runs(e.tokens, looking(style, ctx.intl, ctx.sequence));
+  let rId = ctx.picture(e);
+  return drawing(e, idOf(rId), rId, describe(e), sizeOf(e, column));
+};
+
+/**
+ * One reading of a band at one page, behind whatever the target leads the part
+ * with — the marking, in a footer, so a part holding only that is still a part.
+ *
+ * @type {(closure: any, at: any, lead: string, ctx: Band) => string}
+ */
+let reading = (closure, at, lead, ctx) => lead + (closure ? banded(closure(at), ctx) : "");
+
+/**
+ * What a render carries that the events do not: the report default every band
+ * item wears under its own, the instance's `format` configuration, the text
+ * column a picture is capped at, and the registry a picture's bytes become a
+ * part in. `body.js` holds the same shape, so the two writers describe a render
+ * one way.
+ *
+ * @typedef {{ base: any, intl: any, width: number,
+ *   picture: (event: any) => string }} Ctx
+ */
+
+/**
+ * A `Ctx` for one sequence: the same render, plus which field gives the length
+ * of the sequence this band's section numbers. It is the one thing a page band
+ * knows that the body does not.
+ *
+ * @typedef {Ctx & { sequence: string }} Band
+ */
+
+/**
+ * The part registry: every distinct part written once, whatever asks for it.
+ * Sections opened by `reset: "page"` all number themselves the same way, so a
+ * document of two hundred invoices carries one footer part, not two hundred.
+ *
+ * @param {any} [page] `report-start.page`, absent when no band is declared.
+ * @param {string} [marking] The wording, on an unlicensed render.
+ * @param {(kind: string, target: string) => string} [relate] Registers a part
+ *   and returns the relationship that reaches it; the caller owns the document's
+ *   one allocator, because the body draws pictures too.
+ * @param {Ctx} [ctx] What a render carries that the events do not.
+ */
+export let furnish = (page, marking, relate = () => "", ctx = EMPTY_CTX) => {
+  /** @type {Record<string, string>} */
+  let parts = {};
+  /** @type {Map<string, string>} */
+  let byXml = new Map();
+  /** @type {Record<string, number>} */
+  let counts = { header: 0, footer: 0 };
+
+  // A part for this body, or the one already written for it.
+  /** @type {(kind: string, body: string) => string} */
+  let partFor = (kind, body) => {
+    let tag = kind === "header" ? "hdr" : "ftr";
+    let xml = XML + `<w:${tag} ${W}>` + body + `</w:${tag}>`;
+    let seen = byXml.get(xml);
+    if (seen) return seen;
+    let target = kind + ++counts[kind] + ".xml";
+    let rId = relate(kind, target);
+    byXml.set(xml, rId);
+    parts["word/" + target] = xml;
+    return rId;
+  };
+
+  // One band's references. `titlePg` is one switch for both bands, and Word
+  // reads it as "the first page takes the first-page parts" -- so a band with
+  // no `first` reference shows *nothing* on page one once the other band has
+  // turned it on. Both therefore name a first-page part whenever either needs
+  // one; the steady one names the part it already wrote, which the registry
+  // hands back rather than writing twice.
+  /** @type {(kind: string, pair: string[], titlePg: boolean) => string} */
+  let references = (kind, [first, later], titlePg) => {
+    /** @type {(type: string, body: string) => string} */
+    let ref = (type, body) =>
+      `<w:${kind}Reference w:type="${type}" r:id="${partFor(kind, body)}"/>`;
+    return (titlePg ? ref("first", first) : "") + ref("default", later);
+  };
+
+  /**
+   * What one section's `sectPr` says about its furniture: the references, and
+   * whether either band read differently on the first page. A band with no
+   * closure and nothing for the target to lead with has no part and no
+   * reference — which is what a licensed report declaring no footer gets.
+   *
+   * @type {(sequence: string) => { refs: string, titlePg: boolean }}
+   */
+  let refsFor = (sequence) => {
+    let band = { ...ctx, sequence };
+    let lead = marking ? paragraph("", run(marking, MARKING_LOOK)) : "";
+    let bands = [
+      { kind: "header", closure: page?.header, lead: "" },
+      { kind: "footer", closure: page?.footer, lead },
+    ]
+      .filter((band) => band.closure || band.lead)
+      .map(({ kind, closure, lead: own }) => ({
+        kind,
+        pair: PROBE.map((at) => reading(closure, at, own, band)),
+      }));
+    let titlePg = bands.some(({ pair }) => pair[0] !== pair[1]);
+    return {
+      refs: bands.map(({ kind, pair }) => references(kind, pair, titlePg)).join(""),
+      titlePg,
+    };
+  };
+
+  return { parts, refsFor };
+};
+
+/** A render that declares no bands and marks nothing needs none of it. */
+export const EMPTY_CTX = { base: null, intl: null, width: 0, picture: () => "" };
+
+/** The namespaces a document referencing furniture declares. */
+export const DOCUMENT_NS = W + " " + R;

package/lib/index.d.ts

@@ -0,0 +1,32 @@
+import type { Target } from "quario";
+
+/**
+ * Page geometry, in PostScript points: the host's own, its margin one a
+ * document may declare instead. Restated rather than taken from
+ * `@quario/layout` — a flow target does not run the layout — and hand-synced
+ * with it under `test/page-sizes.test.js`.
+ */
+export interface DocxPage {
+  size?: "A4" | "letter" | [number, number];
+  margin?: number;
+}
+
+/** Optional document properties; never includes dates, so output stays deterministic. */
+export interface DocxMeta {
+  title?: string;
+  author?: string;
+  subject?: string;
+}
+
+/** Host controls, taken and validated at the factory call. */
+export interface DocxOptions {
+  page?: DocxPage;
+  meta?: DocxMeta;
+}
+
+/**
+ * The Word render target:
+ * `quario().report(schema).render(docx({ page }), data)` resolves the document
+ * bytes described in SCHEMA.md ("The DOCX target").
+ */
+export function docx(options?: DocxOptions): Target<"docx", Promise<Uint8Array>>;