@quario/pdf 0.1.0

package/lib/outline.js

@@ -0,0 +1,100 @@
+/**
+ * The group tree as the document's bookmark outline.
+ *
+ * Every group instance leaves a mark while it lays out (`layout.js` anchors it
+ * at the page and cursor where its content begins). Here those marks become
+ * `/Outlines`: nested by group depth, in document order, each targeting its
+ * own position. pdf-lib has no bookmark API, so the objects are built through
+ * its low-level context — the only place in this target that does.
+ */
+import { PDFHexString, PDFName, PDFNumber } from "pdf-lib";
+
+// A PDF *text string*: UTF-16BE with a BOM, so a title survives whatever the
+// author wrote. `PDFHexString.fromText` encodes exactly that.
+/** @type {(marks: any[]) => number[]} */
+let parents = (marks) =>
+  marks.map((mark, i) => {
+    // The nearest earlier mark shallower than this one, or the root.
+    for (let j = i - 1; j >= 0; j--) if (marks[j].depth < mark.depth) return j;
+    return -1;
+  });
+
+/** @type {(parent: number[], of: number) => number[]} */
+let kidsOf = (parent, of) => parent.map((_, i) => i).filter((i) => parent[i] === of);
+
+// An open entry's /Count is its open descendants at every level
+// (ISO 32000-1 §12.3.3). Marks are in document order, so a mark's
+// descendants are the following marks until the depth returns.
+/** @type {(marks: any[], i: number) => number} */
+let descendants = (marks, i) => {
+  let n = 0;
+  for (let j = i + 1; j < marks.length && marks[j].depth > marks[i].depth; j++) n++;
+  return n;
+};
+
+/** @type {(parent: number[], i: number, root: any, refs: any[]) => any} */
+let parentRef = (parent, i, root, refs) => (parent[i] < 0 ? root : refs[parent[i]]);
+
+/** @type {(entry: Record<string, any>, refs: any[], siblings: number[], index: number) => void} */
+let linkSiblings = (entry, refs, siblings, index) => {
+  if (index > 0) entry.Prev = refs[siblings[index - 1]];
+  if (index < siblings.length - 1) entry.Next = refs[siblings[index + 1]];
+};
+
+/** @type {(entry: Record<string, any>, refs: any[], kids: number[], n: number) => void} */
+let linkKids = (entry, refs, kids, n) => {
+  if (!kids.length) return;
+  entry.First = refs[kids[0]];
+  entry.Last = refs[kids[kids.length - 1]];
+  entry.Count = n;
+};
+
+/** @type {(ctx: any, refs: any[], root: any, parent: number[], marks: any[], pageRefs: any[], i: number, mark: any) => void} */
+let writeEntry = (ctx, refs, root, parent, marks, pageRefs, i, mark) => {
+  let siblings = kidsOf(parent, parent[i]);
+  let index = siblings.indexOf(i);
+  let kids = kidsOf(parent, i);
+  let target = pageRefs[Math.min(mark.page, pageRefs.length - 1)];
+  /** @type {Record<string, any>} */
+  let entry = {
+    Title: PDFHexString.fromText(mark.title),
+    Parent: parentRef(parent, i, root, refs),
+    // `/XYZ <x> <y> null`: scroll to the mark's line, keep the zoom. The
+    // left edge is the mark's own column, so two instances sharing a y in
+    // two page columns are two distinct destinations.
+    Dest: [target, PDFName.of("XYZ"), PDFNumber.of(mark.x), PDFNumber.of(mark.y), null],
+  };
+  linkSiblings(entry, refs, siblings, index);
+  linkKids(entry, refs, kids, descendants(marks, i));
+  ctx.assign(refs[i], ctx.obj(entry));
+};
+
+/**
+ * Attach an outline built from `marks` to the document.
+ *
+ * @param {any} doc The pdf-lib document.
+ * @param {any[]} marks Group marks in document order, each `{ title, depth, page, x, y }`.
+ * @param {any[]} pageRefs The pages' refs, in document order, indexed by a mark's `page`.
+ */
+export function outline(doc, marks, pageRefs) {
+  if (!marks.length) return;
+  let ctx = doc.context;
+  let parent = parents(marks);
+  let refs = marks.map(() => ctx.nextRef());
+  let root = ctx.nextRef();
+  for (let [i, mark] of marks.entries())
+    writeEntry(ctx, refs, root, parent, marks, pageRefs, i, mark);
+
+  let top = kidsOf(parent, -1);
+  ctx.assign(
+    root,
+    ctx.obj({
+      Type: "Outlines",
+      First: refs[top[0]],
+      Last: refs[top[top.length - 1]],
+      Count: marks.length,
+    }),
+  );
+  doc.catalog.set(PDFName.of("Outlines"), root);
+  doc.catalog.set(PDFName.of("PageMode"), PDFName.of("UseOutlines"));
+}

package/lib/style.js

@@ -0,0 +1,84 @@
+/**
+ * The PDF target's reading of the closed style vocabulary — the counterpart of
+ * the CSS table in the HTML target package. Declarations are lenient at
+ * render: a value of the wrong shape contributes nothing rather than reaching
+ * the page.
+ *
+ * `finite`/`HEX` are restated per target on purpose: the coercions are each
+ * target's own edge, never shared engine code.
+ */
+import { rgb } from "pdf-lib";
+
+/** @type {(value: any) => boolean} */
+let finite = (value) => typeof value === "number" && Number.isFinite(value);
+let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+// Leading as a fraction of the font size, cell padding, the gap between a
+// page band and the body, and the gutter between two page-column strips.
+// `example/print.css` is the reference look (10pt/1.4) — body type stays a
+// host decision, so `@quario/html/style.css` carries no `body` rule and this
+// pairs with the example rather than it.
+//
+// GUTTER is this target's structural default: SCHEMA.md gives page columns no
+// gap knob deliberately, so the space between strips is the target's to pick
+// and an author never writes it. Twice the cell padding, which is the widest
+// space this target already puts between two columns of anything.
+let LEAD = 1.4;
+let PADX = 6;
+let PADY = 2;
+let BAND = 8;
+let GUTTER = 2 * PADX;
+
+let BLACK = rgb(0, 0, 0);
+
+// Horizontal placement within a given leftover width: left keeps it, right
+// takes all of it, center takes half. Own-key so an authored `constructor`
+// cannot resolve an inherited member.
+/** @type {Record<string, number>} */
+let SHIFT = { right: 1, center: 0.5 };
+/** @type {(align: any, extra: number) => number} */
+let shift = (align, extra) => (Object.hasOwn(SHIFT, align) ? SHIFT[align] : 0) * extra;
+
+// A declared colour as a pdf-lib colour, or null when the value is not one.
+/** @type {(value: any) => any} */
+let col = (value) => {
+  let match = typeof value === "string" && HEX.exec(value);
+  if (!match) return null;
+  // `#abc` is `#aabbcc`.
+  let digits = match[1].length === 3 ? match[1].replace(/./g, (d) => d + d) : match[1];
+  let [r, g, b] = [0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16) / 255);
+  return rgb(r, g, b);
+};
+
+/** @type {(style: any, base: number) => number} */
+let sizeOf = (style, base) => (finite(style.size) && style.size > 0 ? style.size : base);
+
+// Style blocks layer outward-in: row under cell.
+/** @type {(under: any, over: any) => any} */
+let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
+
+// Band-role omakase defaults — the outermost layer of that same stack, under
+// the author's own style, which therefore always wins. Only the headline
+// roles carry one; the XLSX target carries the same two, byte-identical, in
+// `packages/xlsx/lib/index.js`, and they move together (SCHEMA.md states the
+// pair for both). A target can only import public engine helpers, so there is
+// nowhere to share this from and the two copies are synced by hand.
+//
+// `@quario/html` deliberately carries none of this, nor the leading, padding
+// and band gap below: its consumer has a stylesheet and the `q-*` classes are
+// the seam. The rule is docs/adr/0014-a-target-supplies-defaults-only-where-its-consumer-has-no-seam.md —
+// a target supplies defaults only where its consumer has no seam to supply
+// them. `@quario/html/style.css` and `packages/viewer/lib/style.js` are what supply
+// them there; keep all four in agreement.
+/** @type {Record<string, any>} */
+let ROLES = { "report-header": { bold: true, size: 14 }, "group-header": { bold: true } };
+
+// One item event wearing its role's defaults. Events reach layout as events,
+// so the default is folded into a copy rather than passed alongside.
+/** @type {(event: any) => any} */
+let roled = (event) =>
+  Object.hasOwn(ROLES, event.role)
+    ? { ...event, style: merge(ROLES[event.role], event.style) }
+    : event;
+
+export { BAND, BLACK, GUTTER, LEAD, PADX, PADY, col, merge, roled, shift, sizeOf };

package/lib/text.js

@@ -0,0 +1,241 @@
+/**
+ * Measuring and breaking text: tokens flatten to word and space atoms carrying
+ * their resolved typography, and a greedy breaker turns those into lines. Pure
+ * measurement against the font registry — nothing here touches the page.
+ */
+import { ascOf, face, printable, width } from "./fonts.js";
+import { LEAD, col, sizeOf } from "./style.js";
+
+// What measuring needs and no more: the embedded faces to measure against
+// and the base size a style falls back to. A `Canvas` satisfies it, so
+// callers pass theirs straight in — but nothing here can touch a page.
+/** @typedef {{ fonts: import('./fonts.js').Fonts, base: number }} Metrics */
+
+/**
+ * @typedef {{ text: string, font: any, size: number, color: any,
+ *   space: boolean, hard: boolean }} Atom
+ */
+/**
+ * @typedef {{ pieces: { text: string, font: any, size: number, color: any,
+ *   w: number }[], w: number, h: number, size: number, asc: number,
+ *   underline?: boolean, strikethrough?: boolean }} Line
+ */
+
+/**
+ * @typedef {{ cur: Atom[], w: number, lines: Line[], base: number,
+ *   fonts: import('./fonts.js').Fonts }} Wrap
+ */
+
+/** @type {(token: any) => string} */
+let rawOf = (token) => ("literal" in token ? token.literal : String(token.value ?? ""));
+
+/** @type {(font: any, line: string) => string[]} */
+let partsOf = (font, line) => printable(font, line).split(/( +)/).filter(Boolean);
+
+/** @type {(out: Atom[], font: any, size: number, color: any, line: string) => void} */
+let pushParts = (out, font, size, color, line) => {
+  for (let part of partsOf(font, line))
+    out.push({ text: part, font, size, color, space: part[0] === " ", hard: false });
+};
+
+/** @type {(out: Atom[], font: any, size: number, color: any, i: number, line: string) => void} */
+let pushLine = (out, font, size, color, i, line) => {
+  if (i) out.push({ text: "", font, size, color, space: false, hard: true });
+  pushParts(out, font, size, color, line);
+};
+
+/** @type {(metrics: Metrics, style: any) => { font: any, size: number, color: any }} */
+let look = (metrics, style) => {
+  let resolved = style || {};
+  return {
+    font: face(metrics.fonts, resolved),
+    size: sizeOf(resolved, metrics.base),
+    color: col(resolved.color),
+  };
+};
+
+// Flatten a cell's tokens to word/space atoms carrying the cell's resolved
+// typography — one face, size and colour for the whole cell.
+/** @type {(metrics: Metrics, tokens: any[], style: any) => Atom[]} */
+let atoms = (metrics, tokens, style) => {
+  let out = /** @type {Atom[]} */ ([]);
+  let { font, size, color } = look(metrics, style);
+  for (let token of tokens)
+    for (let [i, line] of rawOf(token).split("\n").entries())
+      pushLine(out, font, size, color, i, line);
+  return out;
+};
+
+/** @type {(cur: Atom[]) => void} */
+let trimEnd = (cur) => {
+  while (cur.length && cur[cur.length - 1].space) cur.pop();
+};
+
+/** @type {(pieces: Line['pieces'], atom: Atom, atomWidth: number) => void} */
+let mergeAtom = (pieces, atom, atomWidth) => {
+  let last = pieces[pieces.length - 1];
+  if (last) {
+    last.text += atom.text;
+    last.w += atomWidth;
+    return;
+  }
+  pieces.push({
+    text: atom.text,
+    font: atom.font,
+    size: atom.size,
+    color: atom.color,
+    w: atomWidth,
+  });
+};
+
+/** @typedef {{ pieces: Line['pieces'], w: number, size: number, asc: number }} Run */
+
+/** @type {(run: Run, atom: Atom) => void} */
+let growPiece = (run, atom) => {
+  let atomWidth = width(atom.font, atom.text, atom.size);
+  run.w += atomWidth;
+  if (atom.size > run.size) run.size = atom.size;
+  let atomAsc = ascOf(atom.font, atom.size);
+  if (atomAsc > run.asc) run.asc = atomAsc;
+  mergeAtom(run.pieces, atom, atomWidth);
+};
+
+/** @type {(state: Wrap, run: Run) => void} */
+let finish = (state, run) => {
+  if (!run.size) run.size = state.base;
+  if (!run.asc) run.asc = ascOf(face(state.fonts, {}), run.size);
+  state.lines.push({
+    pieces: run.pieces,
+    w: run.w,
+    h: LEAD * run.size,
+    size: run.size,
+    asc: run.asc,
+  });
+  state.cur = [];
+  state.w = 0;
+};
+
+// `force` keeps deliberately blank lines (hard breaks, an empty value);
+// a word-overflow close passes false so a line of pure trimmed spaces
+// vanishes instead of becoming a phantom line.
+/** @type {(state: Wrap, force?: boolean) => void} */
+let emit = (state, force = true) => {
+  trimEnd(state.cur);
+  if (!force && !state.cur.length) {
+    state.w = 0;
+    return;
+  }
+  /** @type {Run} */
+  let run = { pieces: [], w: 0, size: 0, asc: 0 };
+  for (let atom of state.cur) growPiece(run, atom);
+  finish(state, run);
+};
+
+/** @type {(atom: Atom, rest: string[], avail: number) => number} */
+let fitChars = (atom, rest, avail) => {
+  let n = 1;
+  while (n < rest.length) {
+    let longer = rest.slice(0, n + 1).join("");
+    if (width(atom.font, longer, atom.size) > avail) break;
+    n++;
+  }
+  return n;
+};
+
+/** @type {(state: Wrap, atom: Atom, rest: string[], avail: number) => string[]} */
+let takeChunk = (state, atom, rest, avail) => {
+  let n = fitChars(atom, rest, avail);
+  let take = rest.slice(0, n).join("");
+  state.cur.push({ ...atom, text: take });
+  state.w = width(atom.font, take, atom.size);
+  return rest.slice(n);
+};
+
+// An over-wide word alone on its line breaks by character. Both callers
+// enter with the line empty, and `emit()` empties it again between
+// chunks, so each chunk appends to a bare line. The final chunk stays in
+// `cur` (with `w` set) instead of closing, so following atoms may join its
+// line. Split by code point, so an astral character is never halved.
+/** @type {(state: Wrap, atom: Atom, avail: number) => void} */
+let chunk = (state, atom, avail) => {
+  // Slicing is per code point throughout this module — `no-misused-spread`
+  // is warning about the grapheme clusters no base-14 face can encode.
+  // oxlint-disable-next-line typescript/no-misused-spread
+  let rest = [...atom.text];
+  while (rest.length) {
+    rest = takeChunk(state, atom, rest, avail);
+    if (rest.length) emit(state);
+  }
+};
+
+/** @type {(atom: Atom, atomWidth: number, avail: number) => boolean} */
+let isWide = (atom, atomWidth, avail) => {
+  // oxlint-disable-next-line typescript/no-misused-spread
+  return atomWidth > avail && [...atom.text].length > 1 && !atom.space;
+};
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number, avail: number) => boolean} */
+let canFit = (state, atom, atomWidth, avail) =>
+  state.w + atomWidth <= avail || !state.cur.length || atom.space;
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number) => void} */
+let append = (state, atom, atomWidth) => {
+  state.cur.push(atom);
+  state.w += atomWidth;
+};
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number, avail: number, wide: boolean) => void} */
+let overflow = (state, atom, atomWidth, avail, wide) => {
+  emit(state, false);
+  if (atom.space) return;
+  if (wide) chunk(state, atom, avail);
+  else append(state, atom, atomWidth);
+};
+
+/** @type {(state: Wrap, wide: boolean) => boolean} */
+let startWide = (state, wide) => !state.cur.length && wide;
+
+/** @type {(state: Wrap, atom: Atom, avail: number) => void} */
+let placeAtom = (state, atom, avail) => {
+  if (atom.hard) return emit(state);
+  let atomWidth = width(atom.font, atom.text, atom.size);
+  let wide = isWide(atom, atomWidth, avail);
+  if (!canFit(state, atom, atomWidth, avail)) return overflow(state, atom, atomWidth, avail, wide);
+  if (startWide(state, wide)) return chunk(state, atom, avail);
+  append(state, atom, atomWidth);
+};
+
+// Greedy wrap against `avail`: spaces never start a line, an over-wide word
+// breaks by character, hard breaks always break. A cell's atoms share one
+// typography, so a line's atoms merge into a single draw piece.
+/** @type {(metrics: Metrics, list: Atom[], avail: number) => Line[]} */
+let wrap = (metrics, list, avail) => {
+  /** @type {Wrap} */
+  let state = { cur: [], w: 0, lines: [], base: metrics.base, fonts: metrics.fonts };
+  for (let atom of list) placeAtom(state, atom, avail);
+  emit(state);
+  return state.lines;
+};
+
+// Stamp cell-level decorations onto every wrapped fragment. Measurement does
+// not need them; drawing does, and wrapping must not lose them.
+/** @type {(line: Line, underline: boolean, strikethrough: boolean) => void} */
+let stamp = (line, underline, strikethrough) => {
+  if (underline) line.underline = true;
+  if (strikethrough) line.strikethrough = true;
+};
+
+/** @type {(style: any) => boolean} */
+let dressed = (style) => !!(style && (style.underline || style.strikethrough));
+
+/** @type {(lines: Line[], style: any) => Line[]} */
+let dress = (lines, style) => {
+  if (!dressed(style)) return lines;
+  for (let line of lines) stamp(line, !!style.underline, !!style.strikethrough);
+  return lines;
+};
+
+/** @type {(lines: Line[]) => number} */
+let heightOf = (lines) => lines.reduce((total, line) => total + line.h, 0);
+
+export { atoms, dress, heightOf, wrap };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@quario/pdf",
+  "version": "0.1.0",
+  "description": "The browserless, paginated PDF render target for quario — in the makings, not yet released",
+  "homepage": "https://getquario.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/pdf"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "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",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
+  },
+  "dependencies": {
+    "pdf-lib": "^1.17.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@pdf-lib/fontkit": "^1.1.1",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "quario": "^0.1.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@pdf-lib/fontkit": "^1.1.1",
+    "quario": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@pdf-lib/fontkit": {
+      "optional": true
+    }
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "ignore": [
+        "quario",
+        "pdf-lib"
+      ],
+      "limit": "9.2 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}