@quario/pdf 0.3.0 → 0.5.0

package/lib/painter.js

@@ -0,0 +1,205 @@
+/**
+ * The pdf-lib painter: the list's pages become the document's, op by op. The
+ * only module in this target that talks to pdf-lib page primitives.
+ *
+ * The list reads down from the page's top-left corner; a PDF page reads up
+ * from its bottom-left, so every `y` turns over on its way in. Three passes
+ * per page rather than one walk over the ops: the marks in their order, then
+ * the images, then the marking — the images last because embedding is async
+ * and one logo on every page is embedded once, the marking after them so an
+ * image can never cover it (LICENSE section 6).
+ */
+import { breathe } from "quario";
+import { degrees, drawImage, drawText, rgb } from "@cantoo/pdf-lib";
+import { fontFor } from "./embed.js";
+
+/** @typedef {import('@cantoo/pdf-lib').PDFPage} PDFPage */
+/** @typedef {import('@cantoo/pdf-lib').PDFName} PDFName */
+
+// The operator builder wants explicit rotation and skew; report text has none.
+let NO_TURN = degrees(0);
+let GREY = rgb(0.5, 0.5, 0.5);
+
+/** @type {(color: { r: number, g: number, b: number }) => any} */
+let colorOf = ({ r, g, b }) => rgb(r, g, b);
+
+/**
+ * The resource name a page refers to a face or an image by, minted once per
+ * resource per page.
+ *
+ * pdf-lib's own page-level state cannot do this: `setFont` mints a fresh
+ * random-suffixed name on every call, and `drawText({ font })` calls it twice
+ * — once to select the face and once to restore the previous one. A report
+ * that alternates bold and regular therefore grows its font dictionary with
+ * its text rather than with its faces, and measured 4.8x larger for the same
+ * content. `drawImage` on the page has the same shape, so one logo down a
+ * thousand rows would put a thousand entries in one XObject dictionary,
+ * every one of them pointing at the same stream.
+ *
+ * @type {(mint: (on: PDFPage, resource: any) => PDFName) =>
+ *   (on: PDFPage, resource: any) => PDFName}
+ */
+let perPage = (mint) => {
+  /** @type {WeakMap<PDFPage, Map<any, PDFName>>} */
+  let keys = new WeakMap();
+  return (on, resource) => {
+    let minted = keys.get(on);
+    if (!minted) keys.set(on, (minted = new Map()));
+    let key = minted.get(resource);
+    if (!key) minted.set(resource, (key = mint(on, resource)));
+    return key;
+  };
+};
+
+/**
+ * @typedef {{ doc: any, fonts: import('./embed.js').Fonts, page: PDFPage,
+ *   height: number,
+ *   faceKey: (on: PDFPage, font: any) => PDFName,
+ *   imageKey: (on: PDFPage, image: any) => PDFName,
+ *   embedded: Map<Uint8Array, any> }} Painter
+ */
+
+/** @type {(painter: Painter, op: any) => void} */
+let paintRect = ({ page, height }, op) =>
+  page.drawRectangle({
+    x: op.x,
+    y: height - op.y - op.h,
+    width: op.w,
+    height: op.h,
+    color: colorOf(op.color),
+  });
+
+/** @type {(painter: Painter, op: any) => void} */
+let paintLine = ({ page, height }, op) =>
+  page.drawLine({
+    start: { x: op.x1, y: height - op.y1 },
+    end: { x: op.x2, y: height - op.y2 },
+    thickness: op.width,
+    color: colorOf(op.color),
+    ...(op.dash ? { dashArray: op.dash, dashPhase: 0 } : {}),
+  });
+
+/** @type {(painter: Painter, op: any) => void} */
+let paintText = ({ page, height, fonts, faceKey }, op) => {
+  let font = fontFor(fonts, op.font);
+  page.pushOperators(
+    ...drawText(font.encodeText(op.text), {
+      font: faceKey(page, font),
+      size: op.size,
+      color: colorOf(op.color),
+      x: op.x,
+      y: height - op.y - op.asc,
+      rotate: NO_TURN,
+      xSkew: NO_TURN,
+      ySkew: NO_TURN,
+    }),
+  );
+};
+
+// Draw one page's marking through the same operator path as body text, so the
+// face reuses the page's `faceKey` resource instead of growing the dictionary
+// per draw.
+/** @type {(painter: Painter, op: any) => void} */
+let paintMark = ({ page, height, fonts, faceKey }, op) => {
+  let font = fontFor(fonts, op.font);
+  page.pushOperators(
+    ...drawText(font.encodeText(op.text), {
+      font: faceKey(page, font),
+      size: op.size,
+      color: GREY,
+      x: op.x,
+      y: height - op.y,
+      rotate: degrees(op.angle),
+      xSkew: NO_TURN,
+      ySkew: NO_TURN,
+      // Opacity needs a named ExtGState resource on the page, and pdf-lib
+      // declares the only method that mints one private, with no public
+      // equivalent. The cast is deliberate and stays as narrow as the call.
+      graphicsState: /** @type {any} */ (page).maybeEmbedGraphicsState({ opacity: 0.15 }),
+    }),
+  );
+};
+
+// Keyed by the array the source expression yielded, so one logo reused
+// across pages is embedded once and every placement references it.
+/** @type {(painter: Painter, op: any) => Promise<any>} */
+let imageOf = async ({ doc, embedded }, op) => {
+  let image = embedded.get(op.bytes);
+  if (!image) {
+    image = await (op.format === "png" ? doc.embedPng(op.bytes) : doc.embedJpg(op.bytes));
+    embedded.set(op.bytes, image);
+  }
+  return image;
+};
+
+/** @type {(painter: Painter, op: any) => Promise<void>} */
+let paintImage = async (painter, op) => {
+  let { page, height, imageKey } = painter;
+  page.pushOperators(
+    ...drawImage(imageKey(page, await imageOf(painter, op)), {
+      x: op.x,
+      y: height - op.y - op.h,
+      width: op.w,
+      height: op.h,
+      rotate: NO_TURN,
+      xSkew: NO_TURN,
+      ySkew: NO_TURN,
+    }),
+  );
+};
+
+/** @type {Record<string, (painter: Painter, op: any) => void>} */
+let MARKS = { rect: paintRect, line: paintLine, text: paintText };
+
+/** @type {(painter: Painter, ops: any[]) => void} */
+let paintMarks = (painter, ops) => {
+  for (let op of ops) if (Object.hasOwn(MARKS, op.kind)) MARKS[op.kind](painter, op);
+};
+
+/** @type {(painter: Painter, ops: any[]) => Promise<void>} */
+let paintImages = async (painter, ops) => {
+  for (let op of ops) if (op.kind === "image") await paintImage(painter, op);
+};
+
+/** @type {(painter: Painter, ops: any[]) => void} */
+let paintMarking = (painter, ops) => {
+  for (let op of ops) if (op.kind === "mark") paintMark(painter, op);
+};
+
+/** @type {(painter: Painter, ops: any[]) => Promise<void>} */
+let paintPage = async (painter, ops) => {
+  paintMarks(painter, ops);
+  await paintImages(painter, ops);
+  paintMarking(painter, ops);
+};
+
+/**
+ * Paint every page of the list onto the document. Hands the loop back between
+ * pages, so a long document stays cooperative.
+ *
+ * @param {any} doc The pdf-lib document.
+ * @param {import('./embed.js').Fonts} fonts The embedded faces.
+ * @param {any} list The display list, from `@quario/layout`.
+ * @returns {Promise<any[]>} The pages' refs, in document order, for the outline.
+ */
+export async function paint(doc, fonts, list) {
+  /** @type {Painter} */
+  let painter = {
+    doc,
+    fonts,
+    page: /** @type {any} */ (null),
+    height: list.height,
+    faceKey: perPage((on, font) => on.node.newFontDictionary(font.name, font.ref)),
+    imageKey: perPage((on, image) => on.node.newXObject("Image", image.ref)),
+    embedded: new Map(),
+  };
+  /** @type {any[]} */
+  let refs = [];
+  for (let [i, page] of list.pages.entries()) {
+    painter.page = doc.addPage([list.width, list.height]);
+    refs.push(painter.page.ref);
+    await paintPage(painter, page.ops);
+    if (i % 50 === 49) await breathe();
+  }
+  return refs;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/pdf",
-  "version": "0.3.0",
+  "version": "0.5.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",
@@ -36,22 +36,24 @@
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
   "dependencies": {
-    "pdf-lib": "^1.17.1"
+    "@cantoo/pdf-lib": "^2.9.1",
+    "@quario/layout": "^0.2.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@pdf-lib/fontkit": "^1.1.1",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.3.0",
+    "@types/fontkit": "^2.0.9",
+    "fontkit": "^2.0.4",
+    "quario": "^0.5.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@pdf-lib/fontkit": "^1.1.1",
-    "quario": "^0.3.0"
+    "fontkit": "^2.0.4",
+    "quario": "^0.5.0"
   },
   "peerDependenciesMeta": {
-    "@pdf-lib/fontkit": {
+    "fontkit": {
       "optional": true
     }
   },
@@ -60,9 +62,10 @@
       "path": "lib/index.js",
       "ignore": [
         "quario",
-        "pdf-lib"
+        "@quario/layout",
+        "@cantoo/pdf-lib"
       ],
-      "limit": "10.5 kB"
+      "limit": "6 kB"
     }
   ],
   "engines": {

package/lib/balance.js

@@ -1,90 +0,0 @@
-// The one number a balanced region decides: how tall each of its strips is
-// (ADR 0027 — balancing is a strip height, not a pass). Pure arithmetic over
-// what the buffer holds, so nothing here reaches a canvas or the band flow.
-//
-// Balancing by height alone under-fills, because most of what a region holds
-// does not divide: a group instance, a table row and an image each move whole.
-// A share that is not a whole number of them holds one fewer than it should,
-// and the page-bounded last strip absorbs the remainder (beads `quario-s5c`,
-// `quario-cgk`). So the height is not `measured / count` but the shortest
-// whole-line height at which placing the units in order lands them all in
-// `count` strips.
-//
-// The candidates are line multiples, for the reason the average was rounded to
-// one before this: a floor cuts between lines, so a height that is not a whole
-// number of them leaves every strip a fraction short. They are scanned from the
-// shortest upward rather than searched, because the range is bounded by the
-// lines a page holds and a scan owes nothing to an argument about the fill
-// being monotone in the height. The average is not the starting point and not
-// a lower bound: an instance drops its opening gap at a strip head, so `count`
-// of those gaps are measured that no strip ever pays.
-
-// A **unit** is one thing a strip places: `h` is what it costs mid-strip and
-// `head` what it costs when it is the first thing in a strip — which can be
-// less (a group instance drops its opening gap there) or more (a table row
-// pays for the column headings restated above it). `whole` units move
-// undivided and are the only ones `head` is read for; the rest flow, and
-// nothing that flows costs a different amount for opening a strip. What fills each of these in is the caller's, in
-// `layout.js`, which is also where the model's stated limits are.
-/**
- * @typedef {{ whole: boolean, h: number, head: number }} Unit
- */
-// How far one trial has filled: the strips it has opened and the height taken
-// out of the one it is in.
-/**
- * @typedef {{ strips: number, used: number }} Fill
- */
-
-// The height, or `null` when no candidate packs the units into `count` strips
-// and the region should fill instead. `room` is what one strip could hold at
-// most — the page — and `line` the height a floor cuts on.
-/** @type {(units: Unit[], count: number, room: number, line: number) => number | null} */
-export let balance = (units, count, room, line) => {
-  for (let lines = 1; lines * line <= room; lines++) {
-    let height = lines * line;
-    if (stripsFor(units, height) <= count) return height;
-  }
-  return null;
-};
-
-// How many strips this height needs. `Infinity` when a unit is too tall for a
-// strip of it at all — the scan answers that by looking higher, and the region
-// fills once even the page is too short.
-// The only way a height fails outright is a whole unit taller than a strip of
-// it, so that case is answered here rather than through a result both helpers
-// would have to carry.
-/** @type {(units: Unit[], height: number) => number} */
-let stripsFor = (units, height) => {
-  /** @type {Fill} */
-  let fill = { strips: 1, used: 0 };
-  for (let unit of units) {
-    if (!unit.whole) placeFlow(fill, unit, height);
-    else if (unit.head > height) return Infinity;
-    else placeWhole(fill, unit, height);
-  }
-  return fill.strips;
-};
-
-// A whole unit that would cross the floor opens the next strip instead, where
-// its opening gap is dropped — the rule `breaksFor` applies during the replay.
-/** @type {(fill: Fill, unit: Unit, height: number) => void} */
-let placeWhole = (fill, unit, height) => {
-  if (!fill.used) fill.used = unit.head;
-  else if (fill.used + unit.h <= height) fill.used += unit.h;
-  else {
-    fill.strips++;
-    fill.used = unit.head;
-  }
-};
-
-// Breakable content fills to the floor and continues in the next strip, so it
-// spills across as many as it takes rather than moving whole. No height is too
-// short for it: content that splits always goes somewhere.
-/** @type {(fill: Fill, unit: Unit, height: number) => void} */
-let placeFlow = (fill, unit, height) => {
-  fill.used += unit.h;
-  while (fill.used > height) {
-    fill.strips++;
-    fill.used -= height;
-  }
-};

package/lib/box.js

@@ -1,111 +0,0 @@
-/**
- * The box model this target honours: per-side padding and border, border-box,
- * no collapse. Cell omakase (PADX / PADY) applies only where the author named
- * no padding on that side; a named 0 wins. A border side contributes only when
- * width, style and colour all resolve and width is positive — an incomplete
- * result at render is nothing, not a solid black stroke.
- */
-import { PADX, PADY, col } from "./style.js";
-
-let SIDES = ["Top", "Right", "Bottom", "Left"];
-/** @type {Record<string, number[] | null>} */
-let DASH = { solid: null, dashed: [3, 2], dotted: [1, 1.5] };
-
-/** @typedef {{ t: number, r: number, b: number, l: number }} Inset */
-
-/** @type {Inset} */
-let CELL_PAD = { t: PADY, r: PADX, b: PADY, l: PADX };
-/** @type {Inset} */
-let NO_PAD = { t: 0, r: 0, b: 0, l: 0 };
-
-/** @type {(name: string) => boolean} */
-let isBox = (name) => name.startsWith("padding") || name.startsWith("border");
-
-/** @type {(style: any) => any} */
-let unbox = (style) => {
-  if (!style) return style;
-  let names = Object.keys(style).filter((name) => !isBox(name));
-  if (!names.length) return null;
-  return Object.fromEntries(names.map((name) => [name, style[name]]));
-};
-
-/** @type {(style: any, side: string, fallback: number) => number} */
-let padOf = (style, side, fallback) => {
-  let value = style?.["padding" + side];
-  return Number.isFinite(value) && value >= 0 ? value : fallback;
-};
-
-/** @type {(width: any) => boolean} */
-let isStroke = (width) => Number.isFinite(width) && width > 0;
-/** @type {(line: any) => boolean} */
-let isLine = (line) => typeof line === "string" && Object.hasOwn(DASH, line);
-
-/**
- * @type {(width: any, line: any, color: any) =>
- *   { width: number, dash: number[] | null, color: any } | null}
- */
-let strokeOf = (width, line, color) => {
-  if (!isStroke(width) || !isLine(line) || !color) return null;
-  return { width, dash: DASH[line], color };
-};
-
-/**
- * @type {(style: any, side: string) =>
- *   { width: number, dash: number[] | null, color: any } | null}
- */
-let edgeOf = (style, side) => {
-  if (!style) return null;
-  return strokeOf(
-    style["border" + side + "Width"],
-    style["border" + side + "Style"],
-    col(style["border" + side + "Color"]),
-  );
-};
-
-/** @type {(style: any, side: string) => number} */
-let thick = (style, side) => {
-  let edge = edgeOf(style, side);
-  return edge ? edge.width : 0;
-};
-
-/** @type {(style: any, side: string, fallback: number) => number} */
-let inset = (style, side, fallback) => padOf(style, side, fallback) + thick(style, side);
-
-/** @type {(style: any, omakase: Inset) => Inset} */
-let insetOf = (style, omakase) => ({
-  t: inset(style, "Top", omakase.t),
-  r: inset(style, "Right", omakase.r),
-  b: inset(style, "Bottom", omakase.b),
-  l: inset(style, "Left", omakase.l),
-});
-
-/** Endpoints of one inner-centred edge, as stroke() takes them. */
-/** @type {Record<string, (x: number, yTop: number, w: number, h: number, half: number) => number[]>} */
-let SPAN = {
-  Top: (x, yTop, w, _h, half) => [x, yTop - half, x + w, yTop - half],
-  Bottom: (x, yTop, w, h, half) => [x, yTop - h + half, x + w, yTop - h + half],
-  Left: (x, yTop, _w, h, half) => [x + half, yTop, x + half, yTop - h],
-  Right: (x, yTop, w, h, half) => [x + w - half, yTop, x + w - half, yTop - h],
-};
-
-/** @type {(canvas: { stroke: Function }, x: number, yTop: number, w: number, h: number, style: any, side: string) => void} */
-let paintEdge = (canvas, x, yTop, w, h, style, side) => {
-  let edge = edgeOf(style, side);
-  if (!edge) return;
-  canvas.stroke(...SPAN[side](x, yTop, w, h, edge.width / 2), edge.width, edge.color, edge.dash);
-};
-
-/**
- * Fill and stroke one border-box. Background is the whole rect; each edge
- * sits inside it, centred on its own width, so a stroke does not spill past
- * the box the caller measured.
- *
- * @type {(canvas: { rect: Function, stroke: Function }, x: number, yTop: number,
- *   w: number, h: number, style: any, bg: any) => void}
- */
-let paintBox = (canvas, x, yTop, w, h, style, bg) => {
-  if (bg) canvas.rect(bg, x, yTop - h, w, h);
-  if (style) for (let side of SIDES) paintEdge(canvas, x, yTop, w, h, style, side);
-};
-
-export { CELL_PAD, NO_PAD, insetOf, paintBox, unbox };