@quario/docx 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @quario/docx
 
+## 0.3.0
+
+### Minor Changes
+
+- **A `capabilities` descriptor.** The target exports what it makes of each declaration the spec's support matrix names — `resolved`, `approximated`, `withdrawn` or `unread` — beside its factory, so a host can ask before it renders rather than reading the prose. It is keyed by the schema name an author writes (`valign`, `break`, `page.margin`, and `column.width` / `slot.width` where one word carries two declarations), hand-written and gated against that matrix. It carries no version of its own: the package that ships it is the version.
+- **A run that carries an `href` is a Word hyperlink.** A URL becomes a relationship of the part the run lands in, marked as leaving the package, and one relationship serves every run pointing at the same place. An `href` beginning `#` becomes a `w:anchor`, and the first instance of the group carrying that `label` writes the bookmark it names, beside the heading that item already takes. A run whose text is empty writes no link and relates to nothing. The support matrix recorded this target as withdrawing `href`, and it now resolves it.
+
+  Two things a page band's own part had wrong are fixed with it. A header or footer now carries its **own relationships part**, so a picture or a link inside a band resolves in the part that refers to it rather than only in `document.xml`'s. And `[Content_Types].xml` no longer writes an `Override` for a relationship that names no WordprocessingML part. That entry typed a picture's bytes as a document part, which said nothing true about them.
+
+- **`negative` and `zero` reach the runs.** The target presents through the engine's `format()`, so a cell declaring either reads the same in Word as on the page.
+- **A collapsed group does not draw its content.** An instance whose group declares `collapsed` renders as its header and footer, with the rows between them left out — a page has nowhere to put a row a reader could open. Aggregates are unchanged, so a footer still totals them.
+- **The report header scales with the report default.** A report-header run is written at 1.4× the report default's size rather than a fixed 14, rounded to Word's half-points. A document declaring no size keeps its bytes, because 1.4× the base 10 is the same 14. A document declaring `"size": 20` now renders its report header at 28 where it rendered at 14, smaller than its own body.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.11.0
+
+## 0.2.0
+
+### Minor Changes
+
+- **A group's `break` names a position, and `break: "page"` is retired.** Its values are `"before"`, `"between"`, `"after"` and `"around"`. Write `break: "before"` where you wrote `break: "page"`. That is the whole of the migration, and it changes nothing the report produces.
+
+  The boundary between two consecutive instances always turns a page. `before` adds the leading edge of the run, so the first instance opens a page of its own. `between` adds neither edge, which keeps the first instance on the page the report header opened — the case the old vocabulary could not express, and the reason for the change. `after` adds the trailing edge, and `around` adds both. A trailing edge turns the page for what follows the run, so a report whose last band is that group reads `after` as `between` and `around` as `before`. A nested group takes its two edges from each instance of the group above it, rather than from the document. `"page"` said which unit a break used, where the four say where it falls; one set cannot say both and still read at a glance.
+
+  **`reset: "page"` turns no page of its own, and now needs a `break` beside it.** It says only that a new `page.number` / `page.total` sequence starts at this instance. A sequence owns whole pages, so `reset` requires `break` to be `"before"` or `"around"`. Any other `break`, and `reset` with no `break` at all, is a definition error the compile reports. Add `break: "before"` to a group that declares `reset` alone today.
+
+  The HTML target adds `q-break` to an instance whose leading edge turns, as before, and the new `q-break-after` to one whose trailing edge turns. `@quario/html/style.css` gains `.q-break-after { break-after: page }` beside the rule it already shipped for `.q-break`.
+
+  The Word target also stops losing a page break a table would swallow. A table carries no paragraph properties, so a break owed where one starts had nowhere to sit and reached the next paragraph instead, on the wrong page or on none. It now gets a paragraph of its own, the same carrier a section break already took.
+
+  The render-event stream states the two edges rather than the four positions. `group-start` carries `break` where a page turns before the instance, and the new `breakAfter` where one turns after it, so a target reads boundaries and never the position that asked for them.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.10.0
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -69,7 +69,7 @@ that depends on a style lookup is a look three readers may resolve three ways.
 Page bands become a section's header and footer. A bare `{{ page.number }}` or `{{ page.total }}`
 becomes a live `PAGE` / `NUMPAGES` field the reader's own application recomputes. Anything computed
 from them freezes at the value the render saw. A group's `reset: "page"` opens a section that
-restarts the numbering, and `break: "page"` starts the instance on a fresh page.
+restarts the numbering, and a `break` turns a page at every boundary its position names.
 
 ## Determinism
 
@@ -77,6 +77,12 @@ Two renders of one report are byte-identical, on **every supported runtime**. `f
 JavaScript, so its deflate output does not vary by engine. The package stamps every entry
 1980-01-01 and nothing in the document carries a clock, so a digest over the bytes is a fair test.
 
+## Unlicensed marking
+
+An unlicensed render writes the wording from `report-start.marking` as the first paragraph of
+every footer. A licensed render writes none. The per-footer presence is normative. The wording's
+look is best-effort.
+
 ## Documentation
 
 [The quario documentation](https://getquario.com/docs/) is the reference.
@@ -96,5 +102,3 @@ Pass your license key once, on the instance. quario verifies it offline:
 const q = quario({ license: "quario_..." });
 await q.license; // { licensed: true, licensee: "Acme BV", id: "1-ACME" }
 ```
-
-An unlicensed render carries the marking as the first paragraph of every footer.

package/lib/body.js

@@ -11,9 +11,13 @@
  * 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 breaks.** The stream resolved a group's `break` position into the two
+ * edges of each instance (ADR 0077). A leading edge 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. A trailing edge is the same property on whatever paragraph follows the
+ * instance, and a document that ends owing one drops it: a break turns the page
+ * for what follows, and nothing follows.
  *
  * **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
@@ -28,27 +32,40 @@
  *
  * **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.
+ * own. A `false` in an inner layer is a declaration and wins.
  */
-import { headingAt } from "./stylepart.js";
+import { BASE, 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";
+import { grid, record, tbl } from "./table.js";
+import { content, splitBlock } from "./content.js";
+import { bookmark, paragraph } from "./text.js";
+
+// The page break a paragraph wears, spelled once: `push` folds it into a
+// paragraph's own properties, and `carrier` gives it one where no paragraph is
+// coming to take it.
+const BREAK = "<w:pageBreakBefore/>";
 
 // 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.
+// on a report that declared nothing (ADR 0014: 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 },
+  "report-header": { bold: true, scale: 1.4 },
   "group-header": { bold: true },
 };
 
+// A role's default as a style block: `scale` is a factor over the report
+// default's size, or over the base the style part writes when the report
+// declared none, so a larger document keeps its headline larger.
+/** @type {(role: string, base: any) => any} */
+const roleStyle = (role, base) => {
+  let { scale, ...rest } = ROLES[role];
+  // The engine admits only a positive number, so absent is the one other case.
+  let size = base?.size || BASE;
+  return scale ? { ...rest, size: Math.round(scale * size * 100) / 100 } : rest;
+};
+
 // 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`).
@@ -84,22 +101,29 @@ export let bodyOf = (section) => {
   // 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 group instance's *first* header item is still owed, set when the
+  // instance opens and taken by whichever item claims it: the heading its depth
+  // earns, and the bookmark its `label` is the destination of. One record rather
+  // than a depth, a flag and a name: they only ever move together.
+  /** @type {{ props: string, mark: { id: number, name: string } | null }} */
+  let owes = { props: "", mark: null };
+  // The labels a destination has already been written for, and how many there
+  // are. A label two instances share is one destination and the first wins
+  // (SCHEMA.md, "Style declarations"), and Word's bookmark id is an integer the
+  // document uses once.
+  /** @type {Set<string>} */
+  let labelled = new Set();
   /** 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;
+   *  `content.js`'s `Ctx`, so the two writers describe a render one way.
+   *  Nothing reads it before then, which is why the picture registry the real
+   *  one carries is absent here rather than stubbed.
+   *  @type {import("./content.js").Ctx} */
+  let ctx = /** @type {any} */ ({ base: null, intl: null, width: 0 });
   /** 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
@@ -107,17 +131,24 @@ export let bodyOf = (section) => {
   /** @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,
-    });
+    blocks.push({ props: props + (owed.broken ? BREAK : "") + paraProps(look), inner });
     owed = { broken: false, gapped: false };
   };
 
+  /** An empty paragraph, written where something is owed and no paragraph is
+   *  coming to take it: a section break whose last block is a table, and a page
+   *  break a table would otherwise swallow.
+   *  @type {(props?: string) => void} */
+  let carrier = (props = "") => void blocks.push({ props, inner: "" });
+
   /** A block that is not a paragraph -- a table -- which carries no properties
-   *  and so cannot take what the next paragraph is owed.
+   *  and so cannot take what the next paragraph is owed. A page break takes a
+   *  carrier of its own first, or the table would swallow it; the band gap
+   *  does not, because the next paragraph still takes it.
    *  @type {(inner: string) => void} */
   let block = (inner) => {
+    if (owed.broken) carrier(BREAK);
+    owed.broken = false;
     blocks.push({ props: "", inner, raw: true });
   };
 
@@ -128,15 +159,17 @@ export let bodyOf = (section) => {
     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. */
+  /** The report's own page-column count. */
   let columns = 1;
-  /** @type {number[]} */
-  let columned = [];
+  /** One frame per open instance, innermost last: the columned section this
+   *  instance opened, if any, and its trailing page break. The brackets pair,
+   *  so `group-end` pops the frame `group-start` pushed.
+   *  @type {{ columns: number, trailing: boolean }[]} */
+  let instances = [];
   /** @type {(value: any) => number} */
   let counted = (value) => (Number.isInteger(value) && value > 1 ? value : 0);
 
-  /** @type {(own: import("./furniture.js").Ctx, event: any) => void} */
+  /** @type {(own: import("./content.js").Ctx, event: any) => void} */
   let start = (own, event) => {
     ctx = own;
     columns = counted(event.columns) || 1;
@@ -147,7 +180,7 @@ export let bodyOf = (section) => {
   /** @type {(event: any) => any} */
   let styleOf = (event) =>
     under(
-      under(ctx.base, Object.hasOwn(ROLES, event.role) ? ROLES[event.role] : null),
+      under(ctx.base, Object.hasOwn(ROLES, event.role) ? roleStyle(event.role, ctx.base) : null),
       event.style,
     );
 
@@ -165,7 +198,7 @@ export let bodyOf = (section) => {
   let closeSection = () => {
     let last = blocks.at(-1);
     // oxlint-disable-next-line no-unused-expressions
-    (blocks.length === sectionStart || last?.raw) && blocks.push({ props: "", inner: "" });
+    (blocks.length === sectionStart || last?.raw) && carrier();
     /** @type {any} */ (blocks.at(-1)).closes = sections.at(-1);
   };
 
@@ -178,18 +211,17 @@ export let bodyOf = (section) => {
    * @type {(event: any) => void}
    */
   let group = (event) => {
-    heading = `<w:pStyle w:val="${headingAt(event.depth)}"/>`;
+    owes = { props: `<w:pStyle w:val="${headingAt(event.depth)}"/>`, mark: marking(event.label) };
     // 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;
+    // Its own count is what `group-end` closes; a section that merely inherits
+    // the report's is not one this instance opened.
     let own = counted(event.columns);
+    instances.push({ columns: own, trailing: event.breakAfter === "page" });
     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);
   };
 
@@ -210,38 +242,42 @@ export let bodyOf = (section) => {
     open(kind);
   };
 
-  /** @type {(event: any) => void} */
-  let groupEnd = (event) => {
-    if (columned.at(-1) !== event.depth) return;
-    columned.pop();
-    reopen({ continuous: true, columns: columns });
+  /** What an instance's close owes, in the order the document takes them: the
+   *  trailing page break the stream stated when it opened, then the columned
+   *  section it opened.
+   *  @type {(frame: { columns: number, trailing: boolean }) => void} */
+  let closeInstance = (frame) => {
+    if (frame.trailing) owed.broken ||= blocks.length > 0;
+    if (frame.columns) reopen({ continuous: true, columns });
+  };
+
+  /** @type {() => void} */
+  let groupEnd = () => {
+    let frame = instances.pop();
+    if (frame) closeInstance(frame);
+  };
+
+  /** The destination an instance's label is, or none where it declared none or
+   *  an earlier instance already carries it.
+   *  @type {(label: any) => { id: number, name: string } | null} */
+  let marking = (label) => {
+    if (!label || labelled.has(label)) return null;
+    labelled.add(label);
+    return { id: labelled.size, name: label };
   };
 
   /**
-   * 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.
+   * What an item's role earns from its instance: the heading and the bookmark
+   * it is owed, on a group instance's *first* header item, and nothing anywhere
+   * else.
    *
-   * @type {(role: string) => string}
+   * @type {(role: string) => { props: string, mark: { id: number, name: string } | null }}
    */
-  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));
+  let claim = (role) => {
+    if (role !== "group-header") return { props: "", mark: null };
+    let owed = owes;
+    owes = { props: "", mark: null };
+    return owed;
   };
 
   /** How wide the body is where it is being written: the text column, divided
@@ -254,29 +290,22 @@ export let bodyOf = (section) => {
 
   /** @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));
+    let { props, mark } = claim(event.role);
+    push(props, style, bookmark(mark, content(event, style, columnWidth(), ctx)));
   };
 
   /** @type {(event: any) => void} */
-  let splitStart = (event) => {
-    split = splitting(event.slots, columnWidth(), styleOf(event));
+  let splitOf = (event) => {
+    block(splitBlock(event, columnWidth(), styleOf(event), ctx));
   };
 
-  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 });
+  /** What a table's cells are written with. `intl` and the link registry are
+   *  settled on the opening event, so they are read here rather than captured
+   *  at compile.
+   *  @type {() => { pad: Record<string, number>, intl: any,
+   *    link: (url: string) => string }} */
+  let ruled = () => ({ pad: PAD, intl: ctx.intl, link: ctx.link });
 
   /** @type {(event: any) => void} */
   let tableStart = (event) => {
@@ -319,22 +348,27 @@ export let bodyOf = (section) => {
       "group-end": groupEnd,
       item: itemOf,
       image: itemOf,
-      "split-start": splitStart,
-      "split-end": splitEnd,
+      split: splitOf,
       "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)),
+    xml: (sectPr) => {
+      // A page break the document ends owing is dropped, and `owed` is simply
+      // left set: a break turns the page for what follows it, and nothing
+      // follows. Word, the PDF and a printed fragment agree on that.
+      return (
+        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/content.js

@@ -0,0 +1,51 @@
+/**
+ * What an item, a picture or a split becomes, one way for both writers: the
+ * body and a page band fill the same paragraphs and the same one-row table,
+ * and differ on nothing but the layer under an event's style and which field
+ * numbers the pages. Both arrive in `ctx`, so neither writer keeps a copy.
+ */
+import { describe, drawing, idOf, sizeOf } from "./picture.js";
+import { under } from "./style.js";
+import { splitting } from "./table.js";
+import { looking, runs } from "./text.js";
+
+/**
+ * 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, the registries a picture's bytes and a link's
+ * URL become relationships in, and -- for a page band only -- which field gives
+ * the length of the sequence its section numbers. Both writers hand one of
+ * these down, so they describe a render one way.
+ *
+ * @typedef {{ base: any, intl: any, width: number,
+ *   picture: (event: any) => string, link: (url: string) => string,
+ *   sequence?: string }} Ctx
+ */
+
+/**
+ * One item's or picture's content: the runs a text item's tokens become, or
+ * the inline drawing a picture is. `column` is what caps a picture: the text
+ * column, or the slot holding it.
+ *
+ * @type {(event: any, style: any, column: number, ctx: Ctx) => string}
+ */
+export let content = (event, style, column, ctx) => {
+  if (event.type !== "image") return runs(event.tokens, looking(style, ctx));
+  let rId = ctx.picture(event);
+  return drawing(event, idOf(rId), rId, describe(event), sizeOf(event, column));
+};
+
+/**
+ * One split, folded, as the borderless one-row table it becomes: a slot per
+ * cell, each slot's own style layered over the split's, which is `style`.
+ *
+ * @type {(event: any, width: number, style: any, ctx: Ctx) => string}
+ */
+export let splitBlock = (event, width, style, ctx) => {
+  let split = splitting(event.slots, width, style);
+  for (let slot of event.items) {
+    let own = under(split.style, slot.style);
+    split.slot(own, (column) => content(slot, own, column, ctx));
+  }
+  return split.close();
+};