@quario/docx 0.1.1 → 0.3.0

package/lib/rels.js

@@ -0,0 +1,66 @@
+/**
+ * The package's relationships: what a part may reach, and the id it refers to
+ * it by. A relationship is per part, so `document.xml` has its own and so does
+ * every header and footer — a picture a page band draws is reachable from the
+ * band's part or from nowhere.
+ *
+ * Two things a relationship says beyond its target. A **hyperlink** names a URL
+ * rather than a part, so it says `TargetMode` and the package types no content
+ * for it. Every other kind reaches a part this target packs, and of those the
+ * WordprocessingML ones each need a content type of their own — a picture's
+ * bytes are typed by their extension instead, one entry however many pictures
+ * there are.
+ */
+import { 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 one kind whose target leaves the package. */
+const EXTERNAL = "hyperlink";
+
+/** The kinds whose target is a WordprocessingML part of this package. */
+const TYPED = new Set(["settings", "styles", "header", "footer"]);
+
+/** @typedef {{ target: string, kind: string, rId: string }} Rel */
+
+/** One relationship. The target is a part name this target wrote or a URL the
+ *  engine admitted, and the escape is the same one every other string goes
+ *  through on the way out.
+ *  @type {(rel: Rel) => string} */
+let related = ({ target, kind, rId }) =>
+  `<Relationship Id="${rId}" Type="${OFFICE}/${kind}" Target="${esc(target)}"` +
+  (kind === EXTERNAL ? ' TargetMode="External"' : "") +
+  "/>";
+
+/** One relationships part, whether the package's or one part's own.
+ *  @type {(rels: Rel[]) => string} */
+export let relationships = (rels) =>
+  XML + `<Relationships ${RELS}>` + rels.map(related).join("") + "</Relationships>";
+
+/** The content types the relationships of one package earn: one per
+ *  WordprocessingML part they reach.
+ *  @type {(rels: Rel[]) => string} */
+export let overrides = (rels) =>
+  rels
+    .filter(({ kind }) => TYPED.has(kind))
+    .map(
+      ({ target, kind }) =>
+        `<Override PartName="/word/${target}" ContentType="${WML}.${kind}+xml"/>`,
+    )
+    .join("");
+
+/** The package's own relationships: `document.xml`, and the metadata part a
+ *  host's `meta` wrote. Its two entries name types from two vocabularies, which
+ *  is why they are spelled here rather than through `related`.
+ *  @type {(meta: any) => string} */
+export let packageRels = (meta) =>
+  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>";

package/lib/style.js

@@ -1,9 +1,7 @@
 /**
- * This target's reading of the closed style vocabulary — the counterpart of the
- * CSS table in the HTML target, the points-and-colours module in the layout,
- * and `style.js` in the XLSX target. Declarations are lenient at render: a
- * value of the wrong shape contributes nothing rather than reaching the
- * document.
+ * This target's reading of the closed style vocabulary. Declarations are
+ * lenient at render: a value of the wrong shape contributes nothing rather
+ * than reaching the document.
  *
  * Everything here is a property *string*, in the order the schema fixes.
  * `CT_RPr`, `CT_PPrBase`, `CT_TcPr` and the border containers are sequences,
@@ -22,10 +20,9 @@ let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 
 // A border container's sides, in the order `CT_PBdr` and `CT_TcBorders` both
 // declare them -- which is *not* the clockwise order the authoring surface
-// names them in. Each carries the declaration names it reads and the element
-// name it writes, built once: `borders` runs per paragraph and per cell, and
-// rebuilding four key strings per side per call is most of the garbage this
-// module makes.
+// names them in. Built once: `borders` runs per paragraph and per cell, and
+// rebuilding four key strings per side per call is most of this module's
+// garbage.
 let SIDES = ["Top", "Left", "Bottom", "Right"].map((side) => ({
   tag: side.toLowerCase(),
   width: "border" + side + "Width",
@@ -74,9 +71,8 @@ let underline = (value) =>
 /**
  * The face a declared family names. A generic maps to the name all three
  * readers ship with; any other is the author's own string, written for the
- * reader to substitute and **escaped** — it is the one value in this module
- * that is not a number, a hex colour or a closed name, so it is the one that
- * reaches an attribute as the author wrote it (root CLAUDE.md, constraint 4).
+ * reader to substitute and **escaped** — the one value in this module that is
+ * not a number, a hex colour or a closed name.
  *
  * @type {(family: any) => string}
  */
@@ -123,13 +119,10 @@ let tint = (value) => {
  * Unicode default case mapping, never the host's locale, exactly as the PDF
  * target does for its own reason (`text.js`).
  *
- * `boxed` is the same question `paraProps` asks below and means the same thing:
- * *is this element the one that draws the box?* The box belongs to the
- * innermost container that can hold one, so a `background` on a cell or an item
- * is that container's shading and a run draws none — which is why the default
- * here is `false` and there is `true`. Only a
- * [styled run](../../../SCHEMA.md#cell-values) has nothing but the run to draw
- * its own on.
+ * `boxed` is the same question `paraProps` asks below: *is this element the
+ * one that draws the box?* The box belongs to the innermost container that can
+ * hold one, which is why the default here is `false` and there `true`. Only a
+ * [styled run](../../../SCHEMA.md#cell-values) has nothing but the run.
  *
  * @type {(style: any, boxed?: boolean) => string}
  */

package/lib/stylepart.js

@@ -1,8 +1,7 @@
 /**
  * The `styles.xml` part, written on every render and carrying two things.
- * Named for the part rather than for the vocabulary: `style.js` beside it is
- * this target's reading of what an author declares, and the two are imported
- * together often enough that one letter between them would be a trap.
+ * Named for the part rather than the vocabulary: `style.js` beside it is this
+ * target's reading of what an author declares.
  *
  * `docDefaults` is the base every run and paragraph inherits: the sans
  * generic's own name, the report default's size, and the line spacing the
@@ -25,11 +24,13 @@
  */
 import { W, XML } from "./xml.js";
 
-// The base. Arial is the name the sans generic maps to; 10 pt is `sz` in
-// half-points; 1.4 line spacing is `line` in 240ths of a line, `auto` so a
-// larger run still fits.
+// The base. Arial is the name the sans generic maps to; `BASE` is the type
+// size in points, `sz` in half-points; 1.4 line spacing is `line` in 240ths
+// of a line, `auto` so a larger run still fits. The layout carries the same
+// 10 (docs/adr/0014).
 const FAMILY = "Arial";
-const SIZE = 20;
+export const BASE = 10;
+const SIZE = BASE * 2;
 const LINE = 336;
 
 /** Word caps the outline at nine levels, and so does the deepest style here. */

package/lib/table.js

@@ -63,7 +63,7 @@ let tc = (cell, width, body, pad) =>
   (cell.span > 1 ? `<w:gridSpan w:val="${cell.span}"/>` : "") +
   cellProps(cell.style, pad) +
   "</w:tcPr>" +
-  (body || "<w:p/>") +
+  body +
   "</w:tc>";
 
 /**
@@ -125,7 +125,7 @@ export let splitting = (slots, width, style) => {
   return {
     style,
     slot: (own, content) => {
-      let column = widths[at++] || 0;
+      let column = widths[at++];
       // `boxed: false`: the slot's box is the cell's, so the paragraph inside
       // it must not draw a second one.
       cells += tc(
@@ -142,12 +142,12 @@ export let splitting = (slots, width, style) => {
 /**
  * How wide one cell is, in twips: its own grid column, plus every column it
  * [spans](../../../SCHEMA.md#span). `record` walks the cells in order and keeps
- * the column it has reached, since a span consumes more than one.
+ * the column it has reached, since a span consumes more than one. It is also
+ * where a span becomes a count of at least one, so this one takes it as read.
  *
  * @type {(widths: number[], at: number, span: number) => number}
  */
-let spanned = (widths, at, span) =>
-  widths.slice(at, at + Math.max(1, span || 1)).reduce((sum, w) => sum + w, 0);
+let spanned = (widths, at, span) => widths.slice(at, at + span).reduce((sum, w) => sum + w, 0);
 
 /**
  * One row of cells, each wearing what the row layers over it and taking the
@@ -158,7 +158,8 @@ let spanned = (widths, at, span) =>
  * page band binds the `page` anchor, which is why no sequence is named here.
  *
  * @type {(cells: any[], widths: number[], heading: boolean, layer: any,
- *   how: { pad: Record<string, number>, intl: any }) => string}
+ *   how: { pad: Record<string, number>, intl: any,
+ *     link: (url: string) => string }) => string}
  */
 export let record = (cells, widths, heading, layer, how) => {
   let at = 0;
@@ -171,7 +172,7 @@ export let record = (cells, widths, heading, layer, how) => {
       spanned(widths, at, span),
       // `boxed: false`: the cell above draws the box, so the paragraph inside
       // it must not draw a second one.
-      paragraph(paraProps(style, false), runs(cell.tokens, looking(style, how.intl))),
+      paragraph(paraProps(style, false), runs(cell.tokens, looking(style, how))),
       how.pad,
     );
     at += span;

package/lib/text.js

@@ -18,7 +18,7 @@
  */
 import { display, format, styledRuns } from "quario";
 import { capitals, runProps } from "./style.js";
-import { esc } from "./xml.js";
+import { R, esc } from "./xml.js";
 
 /** One paragraph, its properties already written.
  *  @type {(props: string, inner: string) => string} */
@@ -104,38 +104,90 @@ let shown = (token, look) => format(token.value, look.style, look.intl) ?? displ
 /**
  * What a stretch of text is written with: the resolved style it wears, the run
  * properties that style became, whether it is capitalised, the instance's
- * `format` configuration, and which field gives the current sequence's length.
- * Carried together because every one of them is read for every token, and
- * derived once per run rather than per token — `sequence` included, which is
- * why nothing below it takes one as an argument.
+ * `format` configuration, which field gives the current sequence's length, and
+ * the registry a link's URL becomes a relationship in. Carried together because
+ * every one of them is read for every token, and derived once per run rather
+ * than per token — `sequence` included, which is why nothing below it takes one
+ * as an argument.
  *
  * @typedef {{ style: any, props: string, caps: boolean, intl: any,
- *   sequence: string }} Look
+ *   sequence: string, link: (url: string) => string }} Look
  */
 
-/** @type {(style: any, intl: any, sequence?: string, boxed?: boolean) => Look} */
-export let looking = (style, intl, sequence = DOCUMENT_PAGES, boxed = false) => ({
+/** A `Look` from what the render already carries — `content.js`'s `Ctx`, a
+ *  table's `how`, or an outer `Look`. A body cell names no sequence, because
+ *  only a page band binds the `page` anchor.
+ *  @type {(style: any, of: { intl: any, sequence?: string,
+ *    link: (url: string) => string }, boxed?: boolean) => Look} */
+export let looking = (style, of, boxed = false) => ({
   style,
   props: runProps(style, boxed),
   caps: capitals(style),
-  intl,
-  sequence,
+  intl: of.intl,
+  sequence: of.sequence || DOCUMENT_PAGES,
+  link: of.link,
 });
 
+/**
+ * A run that carries an [`href`](../../../SCHEMA.md#style-declarations), inside
+ * its hyperlink. The engine admitted the URL against the host's scheme
+ * allowlist before it crossed (`docs/adr/0085`), so this target escapes it like
+ * every other string and decides nothing about it.
+ *
+ * An `href` beginning `#` names a group's `label`, which is the bookmark below;
+ * anything else is a URL, and a URL leaves the package, so it is a relationship
+ * of the part the run lands in. A run with no text is no link: there would be
+ * nothing to click, and the relationship would reach out of the document for
+ * nobody.
+ *
+ * The relationship namespace is declared on the element that uses it, as the
+ * picture's `blip` declares it: a page band's part carries no `r` of its own,
+ * and a part that opened one only where a link happened to land would be a
+ * second rule about where a namespace comes from.
+ *
+ * @type {(inner: string, look: Look) => string}
+ */
+let linked = (inner, look) => {
+  let href = look.style?.href;
+  if (!href || !inner) return inner;
+  let at = href.startsWith("#")
+    ? `w:anchor="${esc(href.slice(1))}"`
+    : `${R} r:id="${look.link(href)}"`;
+  return `<w:hyperlink ${at}>` + inner + "</w:hyperlink>";
+};
+
+/**
+ * A destination inside the document: the bookmark an instance's
+ * [`label`](../../../SCHEMA.md#group-definition) names, around the content of
+ * the item that claimed it. The name is the label itself, which is what an
+ * `href` of `#label` asks for; the id is Word's own, an integer the document
+ * uses once.
+ *
+ * @type {(mark: { id: number, name: string } | null, inner: string) => string}
+ */
+export let bookmark = (mark, inner) =>
+  mark
+    ? `<w:bookmarkStart w:id="${mark.id}" w:name="${esc(mark.name)}"/>` +
+      inner +
+      `<w:bookmarkEnd w:id="${mark.id}"/>`
+    : inner;
+
 /**
  * A cell's tokens as Word runs. The engine's `styledRuns` is the grouping, so
  * a styled run's own resolved style replaces the cell's for its stretch — the
  * two are already composed on the stream — and a tagged token stays a field
- * whatever style it wears.
+ * whatever style it wears. A run carrying an `href` sits inside its hyperlink,
+ * which is an element of the paragraph rather than a run property.
  *
  * @type {(tokens: any[], look: Look) => string}
  */
 export let runs = (tokens, look) =>
   styledRuns(tokens)
     .map((styled) => {
-      let own = styled.style ? looking(styled.style, look.intl, look.sequence, true) : look;
-      return styled.tokens
+      let own = styled.style ? looking(styled.style, look, true) : look;
+      let inner = styled.tokens
         .map((token) => fieldOf(token, own.sequence) || run(textOf(token, own), own.props))
         .join("");
+      return linked(inner, own);
     })
     .join("");

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@quario/docx",
-  "version": "0.1.1",
-  "description": "The Word render target for quario — a flow target: real Word tables, a navigable outline, live page-number fields",
+  "version": "0.3.0",
+  "description": "Tiny, flow-based Word render target for quario. Real Word tables, a navigable outline, live page-number fields.",
+  "keywords": [
+    "csp",
+    "docx",
+    "ooxml",
+    "quario",
+    "word"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -26,12 +33,13 @@
     "access": "public"
   },
   "scripts": {
-    "check": "npm run size && npm test && npm run test:browser",
+    "check": "npm run size && npm test",
+    "coverage:check": "c8 report --src lib/ --temp-directory=../../coverage/tmp --reporter=text --check-coverage --100",
     "size": "size-limit",
-    "test": "npm run test:unit && npm run test:types",
+    "test": "npm run test:unit && npm run test:browser && npm run test:types && npm run coverage:check",
     "test:browser": "node test/browser/setup.js",
     "test:types": "tsc && attw --pack . --profile esm-only",
-    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "test:unit": "c8 --clean=false --src lib/ --reporter=none --temp-directory=../../coverage/tmp node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
     "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
@@ -41,12 +49,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.9.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.9.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {