@quario/pdf 0.1.0 → 0.3.0

package/lib/index.js

@@ -5,8 +5,8 @@
  * headers, page bands, `break: "page"`, `reset: "page"` — while the writing is pdf-lib's, so
  * this target carries a typesetter rather than a PDF implementation. Output
  * is deterministic: the document carries no dates of its own, so the same
- * input renders the same bytes. Page geometry is target configuration
- * (`pdf({ page })`), never schema.
+ * input renders the same bytes. Page size is target configuration
+ * (`pdf({ page.size })`); `page.margin` may also be a document field.
  *
  * This file is options, fonts and geometry, the walk itself, and the passes
  * that follow it over the finished pages — page furniture and the marking,
@@ -36,29 +36,17 @@ let err = (msg) => {
   throw Error(msg);
 };
 
-/** @type {(value: any) => boolean} */
-let finite = (value) => typeof value === "number" && Number.isFinite(value);
-
 /** @type {(value: number) => boolean} */
 let positive = (value) => Number.isFinite(value) && value > 0;
 
-/** @type {(options: any) => any} */
-let pageOf = (options) => options?.page ?? {};
-
-/** @type {(options: any) => { meta: any, fonts: any }} */
-let host = (options) => ({ meta: options?.meta, fonts: options?.fonts });
-
 /** @type {(size: any) => any} */
-let named = (size) => {
+let named = (size = "A4") => {
   let dimensions = Array.isArray(size) ? size : SIZES[size];
   // oxlint-disable-next-line no-unused-expressions
   dimensions || err('options.page.size: unknown page size "' + size + '"');
   return dimensions;
 };
 
-/** @type {(page: any) => any} */
-let pageSize = (page) => named(page.size ?? "A4");
-
 /** @type {(dimensions: any) => { width: number, height: number }} */
 let pair = (dimensions) => {
   let width = +dimensions[0],
@@ -69,58 +57,62 @@ let pair = (dimensions) => {
   return { width, height };
 };
 
-/** @type {(page: any) => any} */
-let marginArg = (page) => page.margin ?? 54;
-
-/** @type {(margin: any, width: number, height: number) => number} */
-let marginOf = (margin, width, height) => {
-  let fits = finite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
+/** @type {(margin: any, width: number, height: number, path?: string) => number} */
+let marginOf = (margin = 54, width, height, path = "options.page.margin") => {
+  let fits = Number.isFinite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
   // oxlint-disable-next-line no-unused-expressions
-  fits || err("options.page.margin: expected a non-negative number smaller than half the page");
+  fits || err(path + ": expected a non-negative number smaller than half the page");
   return margin;
 };
 
-/** @type {(options: any) => any} */
-let baseArg = (options) => options?.baseSize ?? 10;
-
-/** @type {(base: any) => number} */
-let baseOf = (base) => {
-  // oxlint-disable-next-line no-unused-expressions
-  (finite(base) && base > 0) || err("options.baseSize: expected a positive number of points");
-  return base;
-};
+// This target's baseline type size. Not a host option: a document's type size
+// is the document's own, so it is `style.size` on the report and the number
+// here is only what text renders at when nothing declares one. The XLSX target
+// carries the same 10 for the same reason (docs/adr/0014, docs/adr/0033).
+let BASE = 10;
 
-// The page box and the content box in one, settled here beside the validation
-// that produced them. This frame never moves at all: it serves every render the
-// target compiles, so a narrowing here would be one document's page bands
-// reserved out of the next one too. The one narrowing a render does make is the
-// band flow's, off that render's own canvas.
-/** @type {(options: any) => import('./canvas.js').Frame} */
-let geometry = (options) => {
-  let page = pageOf(options);
-  let { width, height } = pair(pageSize(page));
-  return frame(width, height, marginOf(marginArg(page), width, height), baseOf(baseArg(options)));
+// The page box and the content box in one. Size is settled at the factory;
+// margin may come from the document's `report-start`, so a render peeks that
+// event before opening a canvas.
+/** @type {(page: any) => any} */
+let hostMargin = (page) => (Object.hasOwn(page, "margin") ? page.margin : undefined);
+/** @type {(opening: any) => any} */
+let docMargin = (opening) => opening?.margin;
+/** @type {(doc: any, host: any) => boolean} */
+let bothMargins = (doc, host) => doc != null && host !== undefined;
+/** @type {(fromDoc: boolean) => string} */
+let marginPath = (fromDoc) => (fromDoc ? "page.margin" : "options.page.margin");
+/** @type {(opening: any, page: any) => { value: any, path: string }} */
+let marginChoice = (opening, page) => {
+  let host = hostMargin(page);
+  let doc = docMargin(opening);
+  if (bothMargins(doc, host)) err("page.margin: document and target both declare a margin");
+  return { value: doc ?? host, path: marginPath(doc != null) };
 };
-
-let META = [
-  ["title", "setTitle"],
-  ["author", "setAuthor"],
-  ["subject", "setSubject"],
-];
-
-/** @type {(doc: any, meta: any, entry: string[]) => void} */
-let field = (doc, meta, [key, method]) => {
-  if (typeof meta[key] === "string") doc[method](meta[key]);
+/** @type {(options: any, opening?: any) => import('./canvas.js').Frame} */
+let geometry = (options, opening) => {
+  let { page = {} } = options ?? {};
+  let { width, height } = pair(named(page.size));
+  let chosen = marginChoice(opening, page);
+  return frame(width, height, marginOf(chosen.value, width, height, chosen.path), BASE);
 };
 
 // Optional document information. Never a date: pdf-lib stamps the current time
 // unless told otherwise, and a timestamp would make the same input render
-// different bytes on every run.
+// different bytes on every run. Each key names the pdf-lib setter it feeds,
+// here rather than in a table, and a value of any other shape is left off.
 /** @type {(doc: any, meta: any) => void} */
 let describe = (doc, meta) => {
   doc.setCreationDate(new Date(0));
   doc.setModificationDate(new Date(0));
-  if (meta) for (let entry of META) field(doc, meta, entry);
+  let field = (/** @type {string} */ method, /** @type {any} */ value) => {
+    if (typeof value === "string") doc[method](value);
+  };
+  if (meta) {
+    field("setTitle", meta.title);
+    field("setAuthor", meta.author);
+    field("setSubject", meta.subject);
+  }
 };
 
 /** @type {(canvas: import('./canvas.js').Drawing, draw: (i: number) => void) => Promise<void>} */
@@ -132,9 +124,6 @@ let overPages = async (canvas, draw) => {
   }
 };
 
-/** @type {(opening: any) => { bands: any, marking: any }} */
-let openingOf = (opening) => ({ bands: opening?.page, marking: opening?.marking });
-
 /** @type {(canvas: import('./canvas.js').Drawing, bands: any,
  *   pages: { number: number, total: number }[]) => Promise<void>} */
 let furnish = async (canvas, bands, pages) => {
@@ -161,8 +150,9 @@ let markPages = async (canvas, marking) => {
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function pdf(options) {
-  let geo = geometry(options);
-  let { meta, fonts: custom } = host(options);
+  geometry(options);
+  let meta = options?.meta,
+    custom = options?.fonts;
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
   let compile = (stream) => async (data) => {
     let doc = await PDFDocument.create();
@@ -170,21 +160,29 @@ export function pdf(options) {
     // Every face is embedded before the walk, so resolving a style to a
     // font during layout stays synchronous.
     let fonts = await embedFonts(doc, custom);
+    let gen = stream(data);
+    let first = gen.next();
+    let geo = geometry(options, first.done ? null : first.value);
     let canvas = drawing(doc, geo, fonts);
     // The band flow owns the placement state and every handler over it, and
     // opens the first page as it is built; this file only hands it the stream.
     let { handlers, finish } = flow(canvas);
-    await walk(stream(data), handlers);
+    function* events() {
+      if (!first.done) yield first.value;
+      yield* gen;
+    }
+    await walk(events(), handlers);
     // The flow settled the opening event on its way past — it reserves the
     // page bands off it — and hands it back with the marks. What is left on it
     // is what the passes below want: the band closures to render per page, and
     // the marking's wording to stamp.
+    // Null when nothing settled one, which reads as a document owing neither.
     let { marks, opening, pages } = finish();
-    let { bands, marking } = openingOf(opening);
+    opening = opening || {};
     // The passes below run over the finished pages, not the stream — no walk
     // at all — so they open each page themselves and breathe on their own
     // rather than through the driver.
-    await furnish(canvas, bands, pages);
+    await furnish(canvas, opening.page, pages);
     // Every image the walk and the furniture pass placed, embedded and drawn
     // now: a walk handler cannot await, and the page bands' images are not
     // placed until the pass above has run. Before the marking, so an image can
@@ -193,7 +191,7 @@ export function pdf(options) {
     // The unlicensed marking goes on last, over content and page furniture
     // alike, once per page (LICENSE section 6). Its wording rode in on
     // `report-start`; only the placement is this target's.
-    await markPages(canvas, marking);
+    await markPages(canvas, opening.marking);
     outline(doc, marks, canvas.refs);
     return doc.save();
   };