@quario/layout 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-07
+
+### Added
+
+- The text join reads a cell's own `currency` code, ahead of the instance's
+  default, so every target built on this package presents a per-cell
+  denomination.
+
+### Changed
+
+- **A group instance that renders nothing no longer takes up space.** A group
+  whose header and footer items all resolve `visible: false`, with nothing
+  visible under it either, used to open the same half-line gap as any other
+  instance and could push the content after it onto a new page. A run of them
+  spaced whatever followed by a half-line each, so collapsing a level left the
+  rows above it at uneven distances. Such an instance now occupies nothing at
+  all and adds no PDF bookmark, which is what makes a group collapsible while
+  its rows stay in the aggregates. A group that declares `break: "page"` or
+  `reset: "page"` still starts its page either way. Every document with such a
+  group renders slightly shorter than it did.
+
+- **Numbers presented through `format` now show a fixed two fraction digits,
+  matching every other target** — `1,000.00` where `1,000` was rendered,
+  `21.00%` where `21%` was, and a currency's own minor units in place of a
+  universal two. Because this package presents text and then **measures** it,
+  a formatted cell is now up to three characters wider than it was: a line
+  that just fitted can wrap, which can move a page break in a PDF, the viewer,
+  or an editor preview. Nothing else about wrapping changed.
+
+### Fixed
+
+- **An image failure now names the item that asked for the bytes.** A file too
+  short to carry a size failed saying only that the size could not be read,
+  naming no item, so a report with two pictures gave no way to tell which one
+  was bad. The message is now prefixed with the item's `source` path, as every
+  other render error is.
+
+- **An image the browser cannot decode no longer costs the whole page.** A
+  PNG or JPEG whose pixel data is corrupt past the size in its header lays out
+  like any other — the size is all that is read of it — and used to throw out
+  of `paint()` before its first draw op, leaving the page blank: no white
+  fill, none of the other content, and no licence marking. The image is now
+  drawn as nothing and the page is drawn around it, so what a bad image costs
+  is the image.
+
+## [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

@@ -1,13 +1,18 @@
 /**
  * The drawing surface. Every mark the band flow makes goes through here, so
- * nothing above this module knows what a page is made of.
+ * nothing above this module knows how a page is drawn on. What a page *is* —
+ * its box, and the content box a margin leaves — is `page.js`'s `Frame`, which
+ * arrives here already derived: nothing below that module works one out. What
+ * this one owns is what becomes of it after — `blank` spreads it flat onto the
+ * canvas and `adopt` narrows `top`/`bottom` in place, which is why `layout.js`
+ * re-derives the untouched page frame it hangs a header from.
  *
  * Two adapters satisfy one interface. `listing` records marks onto the display
  * list — pages of ops and hit boxes, which the painters consume; `measuring`
  * 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.
@@ -21,60 +26,27 @@
 import { baseSans } from "./fonts.js";
 import { BLACK, dressed, shift } from "./style.js";
 
+/** @typedef {import('./page.js').Frame} Frame */
 /** @typedef {import('./text.js').Line} Line */
-/** @typedef {import('./text.js').Metrics} Metrics */
 /** @typedef {import('./style.js').Color} Color */
+// A canvas holds a render's settings and turns nothing into one: what a
+// settings is, and how an opening event becomes it, is settings.js's.
+/** @typedef {import('./settings.js').Settings} Settings */
 // 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.
-/**
- * `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
- */
-
-// 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) => ({
-  width,
-  height,
-  margin,
-  base,
-  family,
-  content: width - 2 * margin,
-  top: height - margin,
-  bottom: margin,
-});
-
 // `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,
  *     color: Color, dash: number[] | null) => void,
- *   picture: (bytes: Uint8Array, format: string, x: number, y: number,
- *     w: number, h: number) => void,
+ *   picture: (path: string | undefined, bytes: Uint8Array, format: string,
+ *     x: number, y: number, w: number, h: number) => void,
  *   drawLine: (line: Line, x: number, yTop: number, avail: number,
  *     align: any) => void,
  *   box: (path: string | undefined, x: number, yTop: number, w: number,
@@ -89,15 +61,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 +97,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} */
@@ -162,9 +134,12 @@ let listing = (box, fonts) => {
       dash,
     });
 
+  // `path` rides along for the one consumer that needs to name the item back
+  // to the author: a target whose embedder rejects the bytes has nothing else
+  // to say which image it was, the box beside the op being a different record.
   /** @type {Canvas['picture']} */
-  let picture = (bytes, format, x, y, w, h) =>
-    page.ops.push({ kind: "image", bytes, format, x, y: down(y + h), w, h });
+  let picture = (path, bytes, format, x, y, w, h) =>
+    page.ops.push({ kind: "image", path, bytes, format, x, y: down(y + h), w, h });
 
   // `advances` rides only where a painter can use it: a base-14 face's
   // one-per-code-point shaping, which is what lets a screen stand-in be
@@ -226,7 +201,7 @@ let listing = (box, fonts) => {
 
   /** @type {Listing} */
   let canvas = {
-    ...blank(box, fonts),
+    ...blank(box, render),
     get count() {
       return pages.length;
     },
@@ -253,10 +228,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 +247,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
@@ -332,4 +307,4 @@ let stamp = (canvas, text) => {
   };
 };
 
-export { adopt, decorateLine, frame, listing, measuring, stamp };
+export { adopt, decorateLine, listing, measuring, 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/image.js

@@ -53,6 +53,6 @@ export let intrinsic = (bytes, format) => {
   // The engine vouched for the magic numbers, not for the rest of the file:
   // a truncated header reaches here as a zero, and failing loudly beats
   // drawing an image with no size (SCHEMA.md, "Image item").
-  if (!(w > 0 && h > 0)) throw Error("image: could not read the image's size from its bytes");
+  if (!(w > 0 && h > 0)) throw Error("could not read the image's size from its bytes");
   return { w: w * PER_PX, h: h * PER_PX };
 };

package/lib/index.d.ts

@@ -1,6 +1,9 @@
 import type { Target } from "quario";
 
-/** Page geometry, in PostScript points. Host configuration, never schema. */
+/**
+ * Page geometry, in PostScript points. Host configuration, except that a
+ * document may declare `page.margin` in the host's stead — never both.
+ */
 export interface LayoutPage {
   /** Named size or `[width, height]` in points. Default `'A4'`. */
   size?: "A4" | "letter" | [number, number];
@@ -26,7 +29,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
@@ -81,9 +84,14 @@ export interface LineOp {
   dash: number[] | null;
 }
 
-/** An image, placed. `bytes` is the array the source expression yielded. */
+/**
+ * An image, placed. `bytes` is the array the source expression yielded, and
+ * `path` names the schema node it came from — the one thing a target whose
+ * embedder rejects those bytes has to report the failure with.
+ */
 export interface ImageOp {
   kind: "image";
+  path: string | undefined;
   bytes: Uint8Array;
   format: "png" | "jpeg";
   x: number;
@@ -197,6 +205,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

@@ -25,6 +25,7 @@ import { listing, stamp } from "./canvas.js";
 import { checkFonts, loadFonts } from "./fonts.js";
 import { flow, furniture } from "./layout.js";
 import { geometry } from "./page.js";
+import { settings } from "./settings.js";
 
 export { PX_PER_POINT, hit, paint } from "./paint.js";
 export { pageBox } from "./page.js";
@@ -78,8 +79,13 @@ export function layout(options) {
     let fonts = await loadFonts(custom);
     let gen = stream(data);
     let first = gen.next();
-    let geo = geometry(options?.page, first.done ? null : first.value);
-    let canvas = listing(geo, fonts);
+    // The opening event carries both halves this render is built from: the page
+    // frame and the document-wide settings. Peeked once here — the settings are
+    // complete and immutable by construction, so no later event can settle them
+    // a second time.
+    let opening = first.done ? null : first.value;
+    let geo = geometry(options?.page, opening);
+    let canvas = listing(geo, settings(fonts, opening));
     // 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);
@@ -88,21 +94,21 @@ export function layout(options) {
       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();
-    opening = opening || {};
+    // The flow reserved the page bands off the opening event on its way past;
+    // the passes below want the rest of it — the band closures to render per
+    // page, and the marking's wording to stamp. It is the same event peeked
+    // above, so this file reads it straight rather than through `finish`.
+    // Empty when nothing was peeked, which reads as a document owing neither.
+    let { marks, pages } = finish();
+    let doc = 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);
+    await furnish(canvas, doc.page, pages);
     // 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 layout's.
-    await markPages(canvas, opening.marking);
+    await markPages(canvas, doc.marking);
     return /** @type {Layout} */ ({
       width: geo.width,
       height: geo.height,