@quario/pdf 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-03
+
+### Changed
+
+- **A split slot's box now fills the split's height.** A slot's background and
+  border stopped at that slot's own content and now take the split's height,
+  the way a table cell's take their row's. See the `@quario/layout` changelog
+  for the rule and for what it costs a report that relied on the short box.
+
+- **A date string under `format: "date"` now presents as a date.** The
+  drawn text comes from the engine's `format()` helper, which revives the two
+  read forms. See the `quario` changelog for the forms and the timezone rule.
+
+### Changed
+
+- **The layout moved to `@quario/layout`; this target paints its list.**
+  Measurement, wrapping, pagination, page furniture, the marking's geometry
+  and the page-size table now live in the layout package, which this target
+  depends on and runs first; pdf-lib writes the resulting display list. **The
+  move itself changed no output**, byte for byte, for the same input; the fix
+  below is a separate change and does move some. The `page` and `fonts`
+  options are the layout's own, so the same object configures `pdf()`, the
+  viewer and the editor. The font mapping's shape is now refused at the
+  factory call rather than at render.
+
+### Fixed
+
+- **A nested group's footer keeps the page columns.** Inside a page-column
+  region, the first footer of a group nested in it ended the region: the
+  strips collapsed and every band after it was laid out across the page, as
+  if `columns` were absent. Only the node that declared `columns` closes its
+  own region now — a nested group's header and footer are region content,
+  laid out in the strips.
+
+- **A padded or bordered item or row that breaks across a page keeps its
+  box.** Content too tall for one page is drawn as slices, and a slice now
+  carries the box sides the break left it — the top on the first, the bottom
+  on the last. Previously an item that overflowed lost its box entirely, so
+  the same declaration drew a border on short data and none on long; a
+  bordered table cell drew all four sides on every slice, putting an edge
+  across the middle of its own text; and a row's own border vanished when
+  the row was too tall for a page. A slice's lines are also drawn inside
+  the horizontal padding they were wrapped for, rather than flush to the
+  column. **This changes output** for reports where such content breaks.
+
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- **`format` stringifies at the edge from the instance locale.** A PDF
+  without a host locale still uses `en-US` / UTC, so the bytes stay
+  reproducible.
+
+- **A height-declared report header pins from the page top.** Leftover sits
+  under the items; the next band starts at the pin. The half-line group gap
+  drops after it. `page.margin` on the document is the inset when the host
+  omits it; both is a render error.
+
+- **`spaceBefore` / `spaceAfter` skip the cursor.** Adjacent gaps add.
+  `spaceBefore` drops at a fresh body page or strip top; page-band items
+  keep it.
+
+- **The box is honoured in layout.** Padding and border inset wrap width; a
+  named padding `0` beats the cell omakase (`PADX` 6 / `PADY` 2) on that
+  side. Incomplete sides draw nothing.
+
+### Changed
+
+- **The last data row keeps the whole emitted total block.** A stack taller
+  than a page degrades like a tall row.
+
+- **An unstyled table has no rules.** This target used to draw two 0.5 pt
+  rules, under the header and above the total, that no declaration could
+  ask for or refuse. Those strokes are gone. The strokes an author wants
+  are the box they declared. Cell padding omakase stays on undeclared cell
+  sides.
+
+- **A visible text item occupies a line at its own `size`, empty or not.** An
+  empty or whitespace-only value used to sit at the report's base leading
+  (~14 pt at the 10 pt baseline). It now occupies `1.4 ×` the item's size, the
+  same as a glyph line. A literal newline is a line break; the blank line
+  among `"a\n\nb"` is that size too. A table cell that is empty or only
+  horizontal whitespace still has no content height.
+
+### Fixed
+
+- **A missing TrueType glyph draws as `?`, not `.notdef`.** Characters
+  outside WinAnsi already substituted `?`; an embedded face's cmap holes
+  drew a box instead, and text extraction hid it. Same rule for every
+  face: a character the face cannot draw becomes `?`.
+
+- **CR, LF, and CRLF are one hard line break.** Cell text already broke
+  on LF; a CRLF left a CR on the previous line, and a lone CR did not
+  break. All three are now one break, matching `SCHEMA.md` Cell values.
+  Wrapping still applies within each line.
+
 ## [0.2.0] - 2026-09-01
 
 ### Added

package/README.md

@@ -3,8 +3,9 @@
 **The PDF render target for [quario](https://www.npmjs.com/package/quario).** Renders a report
 definition straight to a paginated PDF. No headless browser, no print CSS, deterministic bytes.
 
-quario does the typesetting: pagination, keep-together, tables, fonts, the document outline.
-[pdf-lib](https://pdf-lib.js.org) writes the file. You get typesetting plus pdf-lib: no Chromium
+quario does the typesetting — pagination, keep-together, tables, fonts, the document outline —
+through `@quario/layout`, the same layout the viewer paints on screen, so the preview and the
+document break their pages in the same places. [pdf-lib](https://pdf-lib.js.org) writes the file. You get typesetting plus pdf-lib: no Chromium
 in your container, no page-load race, no fonts-not-ready flake.
 
 ## Install
@@ -135,8 +136,9 @@ without authored margins.
 
 The base-14 Helvetica, Times, and Courier families carry the default output (`family: "sans"`,
 `"serif"`, `"mono"`, each with regular, bold, italic, and bold-italic faces), using WinAnsi
-encoding. Characters outside WinAnsi render as `?` rather than failing the report, because cell
-text is untrusted data and one stray character must not take a document down.
+encoding. Characters a face cannot draw render as `?` rather than failing the report, because cell
+text is untrusted data and one stray character must not take a document down. WinAnsi is the
+base-14 limit; a TrueType face's cmap is its own.
 
 For full Unicode, supply TrueType families and select them by name:
 

package/lib/embed.js

@@ -0,0 +1,111 @@
+/**
+ * The faces a document can draw with, embedded before anything is painted.
+ *
+ * Every face is embedded on the document before the list is painted, so
+ * resolving a list op's face to a pdf-lib font is synchronous — pdf-lib's
+ * `embedFont` is async, and the paint is not. Embedding the twelve base-14
+ * faces up front costs under 200 bytes in the output, which is cheaper than a
+ * two-pass split to embed only what is used.
+ *
+ * The registry mirrors the layout's: the same family names, the same four
+ * variants indexed by `bold + 2 * italic`, a missing variant falling back to
+ * the family's regular — so a `FaceRef` on the list names one font here.
+ */
+import { StandardFonts } from "pdf-lib";
+
+let BASE = {
+  sans: [
+    StandardFonts.Helvetica,
+    StandardFonts.HelveticaBold,
+    StandardFonts.HelveticaOblique,
+    StandardFonts.HelveticaBoldOblique,
+  ],
+  serif: [
+    StandardFonts.TimesRoman,
+    StandardFonts.TimesRomanBold,
+    StandardFonts.TimesRomanItalic,
+    StandardFonts.TimesRomanBoldItalic,
+  ],
+  mono: [
+    StandardFonts.Courier,
+    StandardFonts.CourierBold,
+    StandardFonts.CourierOblique,
+    StandardFonts.CourierBoldOblique,
+  ],
+};
+
+/** @typedef {{ families: Record<string, any[]> }} Fonts */
+
+// Host-supplied TrueType families need a font parser, which is an optional
+// peer: base-14 reports install nothing extra. Loaded only when `fonts` is
+// passed, and a missing package is reported as what it is.
+/** @type {(doc: any) => Promise<void>} */
+let useFontkit = async (doc) => {
+  let fontkit;
+  try {
+    fontkit = (await import("@pdf-lib/fontkit")).default;
+  } catch {
+    throw Error("options.fonts: install @pdf-lib/fontkit to embed TrueType families");
+  }
+  doc.registerFontkit(fontkit);
+};
+
+/** @type {(doc: any) => Promise<Record<string, any[]>>} */
+let embedBase = async (doc) => {
+  /** @type {Record<string, any[]>} */
+  let families = {};
+  for (let [name, variants] of Object.entries(BASE))
+    families[name] = await Promise.all(variants.map((v) => doc.embedFont(v)));
+  return families;
+};
+
+/** @type {(doc: any, src: any, path: string, variant: string) => Promise<any>} */
+let embedOne = async (doc, src, path, variant) => {
+  try {
+    return await doc.embedFont(src[variant], { subset: true });
+  } catch (e) {
+    throw Error(path + "." + variant + ": " + /** @type {Error} */ (e).message);
+  }
+};
+
+// Missing variants fall back to the family's regular, so a face is always
+// resolvable once the family is named. The shape was checked at the layout's
+// factory call; this only embeds.
+/** @type {(doc: any, name: string, def: any) => Promise<any[]>} */
+let familyOf = async (doc, name, def) => {
+  let path = "options.fonts." + name;
+  /** @type {any[]} */
+  let faces = [];
+  for (let variant of ["regular", "bold", "italic", "boldItalic"])
+    faces.push(def[variant] == null ? faces[0] : await embedOne(doc, def, path, variant));
+  return faces;
+};
+
+/** @type {(doc: any, custom: any, families: Record<string, any[]>) => Promise<void>} */
+let embedCustom = async (doc, custom, families) => {
+  if (!(custom && Object.keys(custom).length)) return;
+  await useFontkit(doc);
+  for (let [name, def] of Object.entries(custom))
+    families[name.toLowerCase()] = await familyOf(doc, name, def);
+};
+
+/**
+ * Embed every face the list can name and return the registry the painter
+ * reads.
+ *
+ * @param {any} doc The pdf-lib document.
+ * @param {any} custom `options.fonts`, or null.
+ * @returns {Promise<Fonts>}
+ */
+export async function embedFonts(doc, custom) {
+  let families = await embedBase(doc);
+  await embedCustom(doc, custom, families);
+  return { families };
+}
+
+/**
+ * The embedded font one list op names.
+ *
+ * @type {(fonts: Fonts, ref: { family: string, variant: number }) => any}
+ */
+export let fontFor = (fonts, ref) => fonts.families[ref.family][ref.variant];

package/lib/index.d.ts

@@ -1,12 +1,8 @@
+import type { LayoutFontFamily, LayoutPage } from "@quario/layout";
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points. Target configuration, never schema. */
-export interface PdfPage {
-  /** Named size or `[width, height]` in points. Default `'A4'`. */
-  size?: "A4" | "letter" | [number, number];
-  /** Margin on all four sides, in points. Default `54` (0.75 in). */
-  margin?: number;
-}
+/** Page geometry, in PostScript points: the layout's own, never schema. */
+export type PdfPage = LayoutPage;
 
 /** Optional document information; never includes dates, so output stays deterministic. */
 export interface PdfMeta {
@@ -15,13 +11,8 @@ export interface PdfMeta {
   subject?: string;
 }
 
-/** One embeddable TrueType family; missing variants fall back to `regular`. */
-export interface PdfFontFamily {
-  regular: Uint8Array | ArrayBuffer;
-  bold?: Uint8Array | ArrayBuffer;
-  italic?: Uint8Array | ArrayBuffer;
-  boldItalic?: Uint8Array | ArrayBuffer;
-}
+/** One embeddable TrueType family: the layout's own, measured and embedded from the same bytes. */
+export type PdfFontFamily = LayoutFontFamily;
 
 /** Host controls, taken and validated at the factory call. */
 export interface PdfOptions {

package/lib/index.js

@@ -1,88 +1,28 @@
 /**
  * @quario/pdf — the PDF render target: a pure consumer of the engine's public
- * event stream, passed to a compiled report's `render`, laying the banded walk out on
- * pages. Layout is ours — wrapped paragraphs, keep-together, repeated table
- * 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.
+ * event stream, passed to a compiled report's `render`. The layout is
+ * `@quario/layout`'s — one paged display list, the same one the viewer paints
+ * on screen (docs/adr/0039) — and **pdf-lib writes the file**, so this target
+ * is a painter of that list rather than a typesetter or a PDF implementation.
+ * Output is deterministic: the document carries no dates of its own, so the
+ * same 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,
- * neither of which can be drawn until the page count is known. Every handler
- * the driver dispatches to is the band flow's, next door in `layout.js`; this
- * file adds none. The work lives in the sibling modules, which ship beside it
- * — the package publishes `lib/` verbatim.
+ * This file is options, the layout pass, and the document: faces embedded,
+ * pages painted, the group tree attached as bookmarks. The work lives in the
+ * sibling modules, which ship beside it — the package publishes `lib/`
+ * verbatim.
  */
 import { PDFDocument } from "pdf-lib";
-import { breathe, walk } from "quario";
-import { drawing, frame, stamp } from "./canvas.js";
-import { embedFonts } from "./fonts.js";
-import { flow, furniture } from "./layout.js";
+import { layout } from "@quario/layout";
+import { embedFonts } from "./embed.js";
 import { outline } from "./outline.js";
+import { paint } from "./painter.js";
 
 // The options are described once, in the hand-written public declarations, and
 // read back here — a second copy in JSDoc is a copy that drifts.
 /** @import { PdfOptions } from './index.d.ts' */
 
-let SIZES = /** @type {Record<string, [number, number]>} */ ({
-  A4: [595.28, 841.89],
-  letter: [612, 792],
-});
-
-/** @type {(msg: string) => never} */
-let err = (msg) => {
-  throw Error(msg);
-};
-
-/** @type {(value: number) => boolean} */
-let positive = (value) => Number.isFinite(value) && value > 0;
-
-/** @type {(size: any) => any} */
-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 {(dimensions: any) => { width: number, height: number }} */
-let pair = (dimensions) => {
-  let width = +dimensions[0],
-    height = +dimensions[1];
-  // oxlint-disable-next-line no-unused-expressions
-  (positive(width) && positive(height)) ||
-    err("options.page.size: expected finite positive dimensions");
-  return { width, height };
-};
-
-/** @type {(margin: any, width: number, height: number) => number} */
-let marginOf = (margin = 54, width, height) => {
-  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");
-  return margin;
-};
-
-// 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 = {} } = options ?? {};
-  let { width, height } = pair(named(page.size));
-  return frame(width, height, marginOf(page.margin, width, height), 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. Each key names the pdf-lib setter it feeds,
@@ -101,27 +41,11 @@ let describe = (doc, meta) => {
   }
 };
 
-/** @type {(canvas: import('./canvas.js').Drawing, draw: (i: number) => void) => Promise<void>} */
-let overPages = async (canvas, draw) => {
-  for (let i = 0; i < canvas.count; i++) {
-    canvas.select(i);
-    draw(i);
-    if (i % 50 === 49) await breathe();
-  }
-};
-
-/** @type {(canvas: import('./canvas.js').Drawing, bands: any,
- *   pages: { number: number, total: number }[]) => Promise<void>} */
-let furnish = async (canvas, bands, pages) => {
-  if (!bands) return;
-  await overPages(canvas, (i) => furniture(canvas, bands, pages[i]));
-};
-
-/** @type {(canvas: import('./canvas.js').Drawing, marking: any) => Promise<void>} */
-let markPages = async (canvas, marking) => {
-  if (!marking) return;
-  let mark = stamp(canvas, marking);
-  await overPages(canvas, () => canvas.watermark(mark));
+/** @type {(meta: any, custom: any) => Promise<{ doc: any, fonts: import('./embed.js').Fonts }>} */
+let open = async (meta, custom) => {
+  let doc = await PDFDocument.create();
+  describe(doc, meta);
+  return { doc, fonts: await embedFonts(doc, custom) };
 };
 
 /**
@@ -129,50 +53,29 @@ let markPages = async (canvas, marking) => {
  * `quario().report(schema).render(pdf({ page }), data)` resolves the
  * complete document as a `Uint8Array` (the host writes the file). Rendering
  * hands the loop back between event and page batches, so large reports stay
- * cooperative. Geometry and options are validated here, at the factory call.
+ * cooperative. Geometry and the font mapping are validated here, at the
+ * factory call — by the layout target, whose options they are.
  *
  * @param {PdfOptions} [options] Host controls (see SCHEMA.md, "The PDF target").
  * @returns {{name: "pdf", compile: (stream: any) => (data?: any) => Promise<Uint8Array>}}
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function pdf(options) {
-  let geo = geometry(options);
-  let meta = options?.meta,
-    custom = options?.fonts;
+  let { page, fonts: custom, meta } = options ?? {};
+  let paged = layout({ page, fonts: custom });
   /** @type {(stream: any) => (data?: any) => Promise<Uint8Array>} */
-  let compile = (stream) => async (data) => {
-    let doc = await PDFDocument.create();
-    describe(doc, meta);
-    // 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 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);
-    // 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();
-    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, 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
-    // never cover it.
-    await canvas.pictures();
-    // 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, opening.marking);
-    outline(doc, marks, canvas.refs);
-    return doc.save();
+  let compile = (stream) => {
+    let lay = paged.compile(stream);
+    return async (data) => {
+      // The list measures against its own faces, so the document is written
+      // from the same breaks the preview shows; opening the document and
+      // embedding its faces depend on nothing the list decides, so they
+      // overlap the layout pass.
+      let [list, { doc, fonts }] = await Promise.all([lay(data), open(meta, custom)]);
+      let refs = await paint(doc, fonts, list);
+      outline(doc, list.marks, refs);
+      return doc.save();
+    };
   };
   return { name: "pdf", compile };
 }