@quario/layout 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,56 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-05
+
+### Added
+
+- **A spanning cell is drawn as one box** across the columns it covers,
+  starting where the first of them starts. It takes no part in allocating their
+  widths, and a column no cell votes on opens at the cell-padding floor, so an
+  empty table still shows its geometry. A spanning row too tall for the page it
+  is on slices like any other, each slice following the geometry of the page or
+  page-column strip it lands in.
+
+- **`valign`** places a cell's lines, or a slot's lines or picture, in the slack
+  its row or split leaves over its own content: middle halves it, bottom takes
+  it. The box does not move, and a picture is not scaled. A row too tall for
+  any page, sliced across pages, paints from the top.
+
+### Changed
+
+- **A row's box is drawn by the row's cells.** A box declared on a table row
+  used to be one rect across the summed column widths; it is now each covered
+  cell's own, so a row's `borderBottom` still reads as one continuous edge
+  while a row's `borderLeft` becomes an edge on every cell rather than one at
+  the row's outer left. A row's border also occupies height now, as a cell's
+  always has, so a bordered row is taller by its border's width.
+
+- **Measuring TrueType families now needs `fontkit`, not `@pdf-lib/fontkit`.**
+  Install `fontkit` instead; nothing else about `options.fonts` changes. The
+  old package's bundle crashed with a bare `ReferenceError` on any OpenType
+  face needing a shaping state machine — which is every Devanagari, Bengali,
+  Tamil, Khmer or Myanmar webfont in practice, and some fifty further scripts
+  besides. Those faces now measure where they used to throw. Which scripts a
+  face supports remains the font's and the parser's to answer, not this
+  package's.
+
+### Fixed
+
+- **A group header no longer strands above a split.** A split cannot be broken
+  across a page, so a header that introduces one has to keep the whole of it
+  company — but the keep-together test measured a split by its first two lines
+  of text, and a split holds its text in its slots, not in itself. It therefore
+  measured as nothing: the header was drawn at the foot of the page with room
+  reserved for none of what followed, the split moved on to the next page, and
+  the instance's header repeated above it there. A record card whose total row
+  is a split was drawn twice — once orphaned at a page bottom, once whole. The
+  header now moves with the split, exactly as it already moved with an image.
+
+  Where a split is taller than the page has left, the header behaves as it
+  always has before content no page can hold: it degrades to plain paginated
+  flow and repeats nothing.
+
 ## [0.1.0] - 2026-09-03
 
 ### Added

package/README.md

@@ -18,7 +18,7 @@ The engine is a peer. The one runtime dependency is `@pdf-lib/standard-fonts`, t
 base-14 PDF families. To lay out with your own TrueType families, add the optional peer:
 
 ```bash
-npm install @pdf-lib/fontkit
+npm install fontkit
 ```
 
 ESM-only, Node 22+, and browser-ready through a standards-based bundler. CSP-safe: no

package/lib/box.js

@@ -106,6 +106,10 @@ let paintEdge = (canvas, x, yTop, w, h, style, side) => {
 
 /** @type {Slice} */
 let WHOLE = { first: true, more: false };
+// Owns both ends: a block, or a row, drawn in one piece. `sliced` builds fresh
+// slices, so this is a predicate rather than identity against `WHOLE`.
+/** @type {(slice: Slice) => boolean} */
+let isWhole = ({ first, more }) => first && !more;
 
 // The sides one slice still owns. Left and right belong to every slice; the
 // top is the first slice's and the bottom the last's, so a middle slice
@@ -140,4 +144,4 @@ let paintBox = (canvas, x, yTop, w, h, style, bg, slice = WHOLE) => {
   if (style) for (let side of sidesOf(slice)) paintEdge(canvas, x, yTop, w, h, style, side);
 };
 
-export { CELL_PAD, NO_PAD, WHOLE, insetOf, paintBox, sliceInset, unbox };
+export { CELL_PAD, NO_PAD, WHOLE, insetOf, isWhole, paintBox, sliceInset, unbox };

package/lib/canvas.js

@@ -7,7 +7,7 @@
  * moves the cursor and marks nothing, which is how `probe` reserves a band's
  * height without emitting it. Measuring is therefore a choice of adapter
  * rather than a mode every primitive has to remember to check — and since a
- * measuring canvas is built from a frame and a font registry, there is no
+ * measuring canvas is built from a frame and the render's settings, there is no
  * parameter through which a list could reach it. Pagination is the one thing
  * measuring must never do: a page turn would reset the cursor mid-measure and
  * return a silently wrong height, so `newPage` throws there.
@@ -18,57 +18,77 @@
  * it lands: a list coordinate is measured from the page's top-left corner,
  * `y` descending, the way a screen reads. Points throughout.
  */
-import { baseSans } from "./fonts.js";
-import { BLACK, dressed, shift } from "./style.js";
+import { baseSans, familyName } from "./fonts.js";
+import { BLACK, dressed, shift, sizeOf } from "./style.js";
 
 /** @typedef {import('./text.js').Line} Line */
-/** @typedef {import('./text.js').Metrics} Metrics */
 /** @typedef {import('./style.js').Color} Color */
 // The list's own shapes — `Op`, `Box`, `Page` — are described once, in the
 // hand-written public declarations, and read back here.
 /** @import { Box, Op, Page } from './index.d.ts' */
 
-// The page box and the content box. Settled at `report-start` and fixed
-// thereafter: the geometry is the factory's and never moves, while `base` and
-// `family` take the report default one event into the render, before anything
-// is measured. The page bands are measured against the page box and take their
-// height off `top`/`bottom` through `adopt` below, while the first page is
-// still untouched.
+// The page box and the content box, and nothing whatever else: geometry, all
+// of it derived below from a page and a margin. Fixed for the document — the
+// one exception is `top`/`bottom`, which the page bands narrow once through
+// `adopt` below, while the first page is still untouched. Everything else that
+// holds for a whole render is `Settings`, next door; a frame carrying either
+// half of that was a type with two lifetimes, and the copy that kept a probe
+// reading the same locale as the draw had to be written out by hand.
 /**
- * `family` is the report default's typeface, normalised, and `base` its size —
- * the two declarations that default is narrowed to. They ride the frame so a
- * measuring canvas built off it reads the same pair the listing canvas does,
- * and so the default reaches a node as a fallback rather than a merged layer;
- * `layout.js`'s `adoptDefault` carries why. `family` is null when the report
- * declares none.
- *
- * @typedef {{ width: number, height: number, margin: number, base: number,
- *   content: number, top: number, bottom: number, family: string | null,
- *   locale?: string, currency?: string, timeZone?: string }} Frame
+ * @typedef {{ width: number, height: number, margin: number,
+ *   content: number, top: number, bottom: number }} Frame
  */
 
-// A frame from the page box and the base size: how `content`/`top`/`bottom`
-// fall out of a page and a margin is derived here, once, so no caller and no
-// suite has to restate it and drift from what a real render uses.
-/**
- * @type {(width: number, height: number, margin: number, base: number,
- *   family?: string | null) => Frame}
- */
-let frame = (width, height, margin, base, family = null) => ({
+// A frame from the page box: how `content`/`top`/`bottom` fall out of a page
+// and a margin is derived here, once, so no caller and no suite has to restate
+// it and drift from what a real render uses.
+/** @type {(width: number, height: number, margin: number) => Frame} */
+let frame = (width, height, margin) => ({
   width,
   height,
   margin,
-  base,
-  family,
   content: width - 2 * margin,
   top: height - margin,
   bottom: margin,
 });
 
+// This layout'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;
+
+/**
+ * Everything that holds for a whole render and is not geometry: the faces to
+ * measure against, the report default narrowed to `family` and `size` (landing
+ * in `family` and `base` here), and the three intl facts a formatted value
+ * resolves in. Settled once, at
+ * `report-start`, by `adoptSettings` below, and only read thereafter.
+ *
+ * A canvas holds one of these by reference, never a copy, which is the whole
+ * reason it is an object. A measuring canvas built off the same settings reads
+ * exactly what the listing canvas reads, so a page band cannot be reserved
+ * against one locale and drawn in another — an agreement that used to rest on
+ * a hand-written copy staying in step.
+ *
+ * `family` is null when the report declares none, and the intl three are
+ * absent when the engine settled none.
+ *
+ * @typedef {{ fonts: import('./fonts.js').Fonts, base: number,
+ *   family: string | null, locale?: string, currency?: string,
+ *   timeZone?: string }} Settings
+ */
+
+// What a render starts from: the loaded faces, and this target's own baseline
+// standing in for a default no report has declared yet.
+/** @type {(fonts: import('./fonts.js').Fonts) => Settings} */
+let settings = (fonts) => ({ fonts, base: BASE, family: null });
+
 // `y` is the cursor on the open page and `fresh` says nothing has been drawn on
 // it yet, which is what makes a break legal. `count` is how many pages exist.
 /**
- * @typedef {Frame & Metrics & { y: number, fresh: boolean, count: number,
+ * @typedef {Frame & { settings: Settings, y: number, fresh: boolean,
+ *   count: number,
  *   newPage: () => void,
  *   rect: (color: Color, x: number, y: number, w: number, h: number) => void,
  *   stroke: (x1: number, y1: number, x2: number, y2: number, thickness: number,
@@ -89,15 +109,15 @@ let frame = (width, height, margin, base, family = null) => ({
  *   watermark: (mark: Mark) => void }} Listing
  */
 
-// What every canvas starts as, whichever adapter it is: its frame and faces,
-// and a cursor that has drawn nothing yet. Shared because the parity test
-// compares member names, not their values — two hand-written copies of this
-// could drift in what they start from and nothing would notice.
+// What every canvas starts as, whichever adapter it is: its frame and the
+// render's settings, and a cursor that has drawn nothing yet. Shared because
+// the parity test compares member names, not their values — two hand-written
+// copies of this could drift in what they start from and nothing would notice.
 /**
- * @type {(box: Frame, fonts: import('./fonts.js').Fonts) =>
- *   Frame & Metrics & { y: number, fresh: boolean }}
+ * @type {(box: Frame, render: Settings) =>
+ *   Frame & { settings: Settings, y: number, fresh: boolean }}
  */
-let blank = (box, fonts) => ({ ...box, fonts, y: 0, fresh: true });
+let blank = (box, render) => ({ ...box, settings: render, y: 0, fresh: true });
 
 // Text decoration in the text colour. Thickness and offset come from the
 // line's ascender (the face metric already measured for baseline placement).
@@ -125,9 +145,9 @@ let decorateLine = (stroke, line, left, baseline) => {
 /**
  * The adapter that records: a canvas whose marks become the display list.
  *
- * @type {(box: Frame, fonts: import('./fonts.js').Fonts) => Listing}
+ * @type {(box: Frame, render: Settings) => Listing}
  */
-let listing = (box, fonts) => {
+let listing = (box, render) => {
   // A page under construction: its `number`/`total` are the target's to add
   // once the count is known.
   /** @type {any} */
@@ -226,7 +246,7 @@ let listing = (box, fonts) => {
 
   /** @type {Listing} */
   let canvas = {
-    ...blank(box, fonts),
+    ...blank(box, render),
     get count() {
       return pages.length;
     },
@@ -253,10 +273,10 @@ let MARKS_NOTHING = () => {};
  * The adapter that only measures: the same cursor arithmetic with every mark
  * discarded. It holds no page, so a measurement cannot record.
  *
- * @type {(box: Frame, fonts: import('./fonts.js').Fonts) => Canvas}
+ * @type {(box: Frame, render: Settings) => Canvas}
  */
-let measuring = (box, fonts) => ({
-  ...blank(box, fonts),
+let measuring = (box, render) => ({
+  ...blank(box, render),
   count: 0,
   newPage: () => {
     throw new Error("probe reached newPage: the measuring path must not paginate");
@@ -272,10 +292,10 @@ let measuring = (box, fonts) => ({
  * Take on a content box someone else worked out — how much page furniture
  * needs is layout's policy (`reserve` there), while which of a frame's members
  * may move at all is this module's invariant. `top` and `bottom` are the two,
- * and the only two read here: the page box and the base size are fixed for the
- * whole document, so the rest of the frame that arrives is this canvas's own
- * and is left alone. Layout reads the bounds live, so every page the body then
- * flows through sees the narrowed box.
+ * and the only two read here: the page box is fixed for the whole document, so
+ * the rest of the frame that arrives is this canvas's own and is left alone.
+ * Layout reads the bounds live, so every page the body then flows through sees
+ * the narrowed box.
  *
  * Legal only while the render has not committed to a page — the band flow
  * adopts from its `report-start` handler, with its own first page open but
@@ -294,6 +314,42 @@ let adopt = (canvas, box) => {
   canvas.y = canvas.top;
 };
 
+/**
+ * The document-wide facts off `report-start`, taken once, before anything is
+ * measured. The report default is narrowed to `family` and `size`, and each
+ * replaces this target's own baseline outright: row heights and band gaps scale
+ * with the document's type rather than staying at a size nothing is set in, and
+ * text declaring no family is set in the document's. Settling the pair here is
+ * the whole of this target's reading of docs/adr/0033 — the default reaches a
+ * node as a fallback the settings carry, never as a layer merged into its
+ * style, so a document-wide fact costs no allocation however many cells a
+ * report has.
+ *
+ * `sizeOf` and `familyName` are this target's one reading each of what a
+ * declared size and family amount to, so they read the default here too — both
+ * reach this unchecked from a computed style, and two spellings of that
+ * leniency would drift. Each falls back to what the settings already carry, so
+ * a default declaring one of the pair leaves the other alone, and one whose
+ * value is unusable leaves this target's own baseline standing.
+ *
+ * Settled once, the statement `adopt` makes about geometry: these hold for a
+ * whole render, so a second event setting them would mean two documents in one.
+ * The freeze is what enforces it, and the check is what names it.
+ *
+ * @param {Settings} render The render's settings.
+ * @param {any} event The `report-start` event.
+ */
+let adoptSettings = (render, event) => {
+  if (Object.isFrozen(render)) throw Error("adoptSettings: the render settings are fixed");
+  let style = event.style || {};
+  render.base = sizeOf(style, render.base);
+  render.family = familyName(style) || render.family;
+  render.locale = event.locale;
+  render.currency = event.currency;
+  render.timeZone = event.timeZone;
+  Object.freeze(render);
+};
+
 // The unlicensed-output marking (LICENSE section 6): one translucent line
 // drawn corner-to-corner across the finished page — over the content, not
 // under it, so no filled table header or background rectangle can cover it.
@@ -332,4 +388,4 @@ let stamp = (canvas, text) => {
   };
 };
 
-export { adopt, decorateLine, frame, listing, measuring, stamp };
+export { adopt, adoptSettings, decorateLine, frame, listing, measuring, settings, stamp };

package/lib/fonts.js

@@ -20,25 +20,16 @@ import { Encodings, Font, FontNames } from "@pdf-lib/standard-fonts";
 // The three families the vocabulary names, four variants each, indexed by
 // `bold + 2 * italic` — the same ordering the schema's `bold`/`italic` flags
 // produce. Unknown family names fall back to sans, as SCHEMA.md specifies.
+// A family's four names are one stem plus the weight and slant suffixes that
+// family spells, so each family names its two and the four are walked out of
+// them rather than written twelve times over.
+/** @type {(stem: string, slant: string) => string[]} */
+let variants = (stem, slant) =>
+  ["", "Bold", slant, "Bold" + slant].map((v) => /** @type {any} */ (FontNames)[stem + v]);
 let BASE = {
-  sans: [
-    FontNames.Helvetica,
-    FontNames.HelveticaBold,
-    FontNames.HelveticaOblique,
-    FontNames.HelveticaBoldOblique,
-  ],
-  serif: [
-    FontNames.TimesRoman,
-    FontNames.TimesRomanBold,
-    FontNames.TimesRomanItalic,
-    FontNames.TimesRomanBoldItalic,
-  ],
-  mono: [
-    FontNames.Courier,
-    FontNames.CourierBold,
-    FontNames.CourierOblique,
-    FontNames.CourierBoldOblique,
-  ],
+  sans: variants("Helvetica", "Oblique"),
+  serif: variants("TimesRoman", "Italic"),
+  mono: variants("Courier", "Oblique"),
 };
 
 /**
@@ -69,9 +60,6 @@ let BASE = {
  */
 /** @typedef {{ families: Record<string, Face[]> }} Fonts */
 
-/** @type {(text: string) => string[]} */
-let codePoints = (text) => Array.from(text);
-
 // A base-14 face: AFM widths and kerning over WinAnsi. The width of a string
 // is the sum of its glyph widths plus the kerning between neighbours — the
 // same arithmetic pdf-lib's standard-font embedder does, kept in step so the
@@ -88,7 +76,7 @@ let standard = (family, variant, name) => {
   let encoding = Encodings.WinAnsi;
   /** @type {(text: string) => { code: number, name: string }[]} */
   let glyphs = (text) =>
-    codePoints(text).map((char) => encoding.encodeUnicodeCodePoint(char.codePointAt(0) ?? 0));
+    Array.from(text).map((char) => encoding.encodeUnicodeCodePoint(char.codePointAt(0) ?? 0));
   /** @type {(glyph: { name: string }, next?: { name: string }) => number} */
   let advance = (glyph, next) =>
     (font.getWidthOfGlyph(glyph.name) || 250) +
@@ -153,10 +141,6 @@ let baseFamilies = () =>
     ]),
   ));
 
-// A render's own copy, so adding a host's families cannot reach the memo.
-/** @type {() => Record<string, Face[]>} */
-let loadBase = () => ({ ...baseFamilies() });
-
 /**
  * The base-14 sans regular, whatever a host mapped `sans` to. Reached only by
  * the marking, which is the one thing on a page a host's font mapping must not
@@ -171,9 +155,9 @@ export let baseSans = () => baseFamilies().sans[0];
 /** @type {() => Promise<any>} */
 let useFontkit = async () => {
   try {
-    return (await import("@pdf-lib/fontkit")).default;
+    return await import("fontkit");
   } catch {
-    throw Error("options.fonts: install @pdf-lib/fontkit to measure TrueType families");
+    throw Error("options.fonts: install fontkit to measure TrueType families");
   }
 };
 
@@ -287,7 +271,8 @@ let loadCustom = async (custom, families) => {
  * @returns {Promise<Fonts>}
  */
 export async function loadFonts(custom) {
-  let families = loadBase();
+  // A render's own copy, so adding a host's families cannot reach the memo.
+  let families = { ...baseFamilies() };
   await loadCustom(custom, families);
   return { families };
 }
@@ -397,7 +382,7 @@ let replaceUndrawable = (set, text) => {
   let sub = set.has(0x3f) ? "?" : "";
   // Encodedness is a per-code-point question, so that is the unit to ask it
   // in — the grapheme clusters the rule protects are undrawable anyway.
-  return codePoints(text)
+  return Array.from(text)
     .map((char) => (set.has(char.codePointAt(0) ?? -1) ? char : sub))
     .join("");
 };
@@ -405,5 +390,5 @@ let replaceUndrawable = (set, text) => {
 /** @type {(font: any, text: string) => boolean} */
 let encodable = (font, text) => {
   let set = charsetOf(font);
-  return codePoints(text).every((char) => set.has(char.codePointAt(0) ?? -1));
+  return Array.from(text).every((char) => set.has(char.codePointAt(0) ?? -1));
 };

package/lib/index.d.ts

@@ -26,7 +26,7 @@ export interface LayoutOptions {
    * TrueType families to measure against, selected from styles by
    * `family: '<name>'`. Pass the same record to `pdf({ fonts })` and to
    * `paint()`, so preview and document break their lines in the same places
-   * and draw in the same faces. Requires the optional peer `@pdf-lib/fontkit`;
+   * and draw in the same faces. Requires the optional peer `fontkit`;
    * the base-14 families need nothing extra.
    *
    * Hold the record and the buffers in it across renders rather than building
@@ -197,6 +197,12 @@ export const PX_PER_POINT: number;
  * Paint one page onto a Canvas 2D context: a white page, then every op in
  * order. `scale` is device pixels per point. `fonts` is the same record
  * given to `layout()`, so a TrueType family draws in its own face.
+ *
+ * It awaits its faces and images before it draws, and it draws whatever
+ * happened in between: a canvas re-sized under a call still in flight is
+ * filled at that call's own `scale`, not the size it now has. A caller that
+ * repaints one canvas at changing scales owns that, by not letting a
+ * superseded call reach a canvas still on screen.
  */
 export function paint(
   ctx: CanvasRenderingContext2D,

package/lib/index.js

@@ -21,7 +21,7 @@
  * file adds none. The package publishes `lib/` verbatim.
  */
 import { breathe, walk } from "quario";
-import { listing, stamp } from "./canvas.js";
+import { listing, settings, stamp } from "./canvas.js";
 import { checkFonts, loadFonts } from "./fonts.js";
 import { flow, furniture } from "./layout.js";
 import { geometry } from "./page.js";
@@ -79,7 +79,7 @@ export function layout(options) {
     let gen = stream(data);
     let first = gen.next();
     let geo = geometry(options?.page, first.done ? null : first.value);
-    let canvas = listing(geo, fonts);
+    let canvas = listing(geo, settings(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);