@quario/layout 0.1.0 → 0.3.0

package/lib/page.js

@@ -3,8 +3,15 @@
  * it is written. Owned here because every consumer of the list — the PDF
  * target, the viewer, the editor — lays out on the same page, and a size that
  * meant one thing on screen and another on paper would be a silent lie.
+ *
+ * The derivation belongs with the validation: `frame` below turns a validated
+ * page and margin into the geometry everything downstream lays out in, so a
+ * page becomes a content box here and `canvas.js` only takes the answer,
+ * rather than the drawing surface defining the page it draws on. Deriving a
+ * frame is not owning its lifetime, and this module claims only the first:
+ * `adopt` (`canvas.js`) narrows `top`/`bottom` once for the page bands, and
+ * `reserve` (`layout.js`) mints the frame it narrows from.
  */
-import { frame } from "./canvas.js";
 
 // The named sizes. `@quario/pdf` used to own this table, and the two element
 // packages restated it; the layout package is where all three now read it.
@@ -49,12 +56,6 @@ let marginOf = (margin = 54, width, height, path) => {
   return 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;
-
 // 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} */
@@ -86,14 +87,45 @@ export let pageBox = (page, at = "page") => {
   return { width, height, margin: marginOf(page?.margin, width, height, at + ".margin") };
 };
 
+// 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` (`canvas.js`), while the first page is still untouched. Everything
+// else that holds for a whole render is that module's `Settings`; 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.
+/**
+ * @typedef {{ width: number, height: number, margin: number,
+ *   content: number, top: number, bottom: number }} Frame
+ */
+
+// 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. A render reaches a frame through
+// `geometry` below and never through this; the package entry carries neither,
+// so no host reaches one at all. Exported for `layout.js`, which re-derives the
+// page frame a canvas presents, and for the suites that build a fixture frame
+// — the day that re-derivation goes, the export stands for the suites alone,
+// and they should take `geometry` rather than keep it standing.
+/** @type {(width: number, height: number, margin: number) => Frame} */
+export let frame = (width, height, margin) => ({
+  width,
+  height,
+  margin,
+  content: width - 2 * margin,
+  top: height - margin,
+  bottom: margin,
+});
+
 /**
  * The page box and the content box in one, for a render: the host's size,
  * and whichever margin the host and the opening event agreed on.
  *
- * @type {(page: any, opening?: any) => import('./canvas.js').Frame}
+ * @type {(page: any, opening?: any) => Frame}
  */
 export let geometry = (page = {}, opening) => {
   let { width, height } = pageBox(page, "options.page");
   let chosen = marginChoice(opening, page, "options.page");
-  return frame(width, height, marginOf(chosen.value, width, height, chosen.path), BASE);
+  return frame(width, height, marginOf(chosen.value, width, height, chosen.path));
 };

package/lib/paint.js

@@ -123,7 +123,9 @@ let loadFaces = async (fonts) => {
 };
 
 // Every bitmap decoded so far, by the bytes it was decoded from: one logo on
-// every page is decoded once.
+// every page is decoded once. A rejection is remembered too, so a file the
+// browser refused is refused from memory ever after — a caller repainting the
+// same page never pays for a second decode of bytes that will not decode.
 /** @type {WeakMap<Uint8Array, Promise<ImageBitmap>>} */
 let BITMAPS = new WeakMap();
 
@@ -183,9 +185,6 @@ let paintText = (ctx, op) => {
   }
 };
 
-/** @type {(ctx: CanvasRenderingContext2D, op: any, bitmap: ImageBitmap) => void} */
-let paintImage = (ctx, op, bitmap) => ctx.drawImage(bitmap, op.x, op.y, op.w, op.h);
-
 // The marking, as the PDF draws it: translucent grey along the page diagonal,
 // turned counter-clockwise by the list's angle. The canvas reads down, so the
 // turn is negative here.
@@ -207,16 +206,30 @@ let PAINTERS = { rect: paintRect, line: paintLine, text: paintText, mark: paintM
 
 /** @type {(ctx: CanvasRenderingContext2D, op: Op, bitmaps: Map<Op, ImageBitmap>) => void} */
 let paintOp = (ctx, op, bitmaps) => {
-  if (op.kind === "image") paintImage(ctx, op, /** @type {ImageBitmap} */ (bitmaps.get(op)));
-  else PAINTERS[op.kind](ctx, op);
+  // An image with no bitmap did not decode, and is drawn as nothing. The map
+  // is the one place that is known: `decode` keeps no entry for a file the
+  // browser refused, so there is no second flag to read and no way to ask
+  // this question twice.
+  if (op.kind === "image") {
+    let bitmap = bitmaps.get(op);
+    if (bitmap) ctx.drawImage(bitmap, op.x, op.y, op.w, op.h);
+  } else PAINTERS[op.kind](ctx, op);
 };
 
-// Every image on the page, decoded together rather than one after another.
+// Every image on the page, decoded together rather than one after another,
+// and each settling on its own: gathering with `Promise.all` made one file the
+// browser refused the whole page's failure, thrown before the first draw op.
+// `paint`'s own doc says why that is the wrong price. An image that did not
+// decode has no entry here, which is how `paintOp` knows.
 /** @type {(page: Page) => Promise<Map<Op, ImageBitmap>>} */
 let decode = async (page) => {
   let images = page.ops.filter((op) => op.kind === "image");
-  let bitmaps = await Promise.all(images.map(bitmapOf));
-  return new Map(images.map((op, i) => [op, bitmaps[i]]));
+  let bitmaps = await Promise.all(images.map((op) => bitmapOf(op).catch(() => null)));
+  return new Map(
+    /** @type {[Op, ImageBitmap][]} */ (
+      images.map((op, i) => [op, bitmaps[i]]).filter(([, bitmap]) => bitmap)
+    ),
+  );
 };
 
 /**
@@ -225,6 +238,21 @@ let decode = async (page) => {
  * the canvas, so it knows. `fonts` is the host's font mapping, 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 — which is what the viewer's
+ * stage retires a page for (docs/adr/0046).
+ *
+ * **An image the browser will not decode is drawn as nothing, and the page is
+ * drawn around it.** The engine vouched for the magic numbers and the layout
+ * read the size out of the header, so a file corrupt past that point is not
+ * known to be bad until here; costing the whole page for it — every other op
+ * and the marking with it — is a worse answer than costing the image. What is
+ * lost is what could not be drawn. A caller wanting the failure instead should
+ * decode before it paints.
+ *
  * @param {CanvasRenderingContext2D} ctx The context to paint on.
  * @param {Page} page One page of a `Layout`.
  * @param {{ scale?: number, fonts?: any }} [options]

package/lib/settings.js

@@ -0,0 +1,88 @@
+/**
+ * Everything that holds for a whole render and is not geometry — the render's
+ * `Settings`, and the one reading of what a report default amounts to.
+ *
+ * A `Frame` (canvas.js) is a page's geometry; a `Settings` is the other half:
+ * the faces to measure against, the report default narrowed to `base` and
+ * `family`, and the three intl facts a formatted value resolves in. A canvas
+ * holds one by reference, so a measuring canvas built for a probe reads exactly
+ * what the listing canvas reads and a band cannot be reserved against one
+ * locale and drawn in another. This module owns what a settings *is* and how a
+ * report's opening event becomes one; canvas.js draws with it, text.js measures
+ * against it, and neither has to know what `style.size` or `style.family`
+ * amount to.
+ */
+import { familyName } from "./fonts.js";
+import { sizeOf } from "./style.js";
+
+// 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.
+ *
+ * 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 each of the intl three is
+ * undefined when the engine settled none.
+ *
+ * @typedef {{ fonts: import('./fonts.js').Fonts, base: number,
+ *   family: string | null, locale?: string, currency?: string,
+ *   timeZone?: string }} Settings
+ */
+
+/**
+ * The render's settings, complete by construction from the opening event the
+ * target already peeked. 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. Reading 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 this target's own baseline, so a
+ * default declaring one of the pair leaves the other at the baseline, and one
+ * whose value is unusable leaves the baseline standing.
+ *
+ * Built once and never settled again: these hold for a whole render, so there
+ * is no event that could set them a second time — a second settling is not
+ * refused, it is unexpressible. `opening` is null when the stream is empty (no
+ * report to read a default from), which yields the bare baseline: the target's
+ * own size, no family, and the intl three unset. Those three are read straight
+ * off the event whether or not it declares them — a formatted value is the only
+ * thing that reads them, and an empty stream produces none, so an unset one
+ * never reaches `Intl`.
+ *
+ * @param {import('./fonts.js').Fonts} fonts The loaded faces.
+ * @param {any} [opening] The peeked `report-start` event, or null.
+ * @returns {Settings}
+ */
+let settings = (fonts, opening) => {
+  let event = opening || {};
+  let style = event.style || {};
+  return {
+    fonts,
+    base: sizeOf(style, BASE),
+    family: familyName(style) || null,
+    locale: event.locale,
+    currency: event.currency,
+    timeZone: event.timeZone,
+  };
+};
+
+export { settings };

package/lib/style.js

@@ -44,6 +44,13 @@ let BLACK = { r: 0, g: 0, b: 0 };
 let SHIFT = { right: 1, center: 0.5 };
 /** @type {(align: any, extra: number) => number} */
 let shift = (align, extra) => (Object.hasOwn(SHIFT, align) ? SHIFT[align] : 0) * extra;
+// The same for the leftover height -- the slack a box has over its content,
+// which is the only place `valign` is legal (CONTEXT.md "Box"). Top keeps it,
+// bottom takes all of it, middle takes half; undeclared is top.
+/** @type {Record<string, number>} */
+let VSHIFT = { bottom: 1, middle: 0.5 };
+/** @type {(valign: any, extra: number) => number} */
+let vshift = (valign, extra) => (Object.hasOwn(VSHIFT, valign) ? VSHIFT[valign] : 0) * extra;
 
 // A declared colour as a `Color`, or null when the value is not one.
 /** @type {(value: any) => Color | null} */
@@ -62,7 +69,7 @@ let sizeOf = (style, base) => (Number.isFinite(style.size) && style.size > 0 ? s
 // Style blocks layer outward-in: row under cell, split under slot. Those are
 // the two innermost of the four layers; the outer two reach a node without
 // being merged into it -- the band-role default through `roled` below, and the
-// report default through the canvas, as `layout.js`'s `adoptDefault` explains.
+// report default through the render's settings, as `settings.js` explains.
 /** @type {(under: any, over: any) => any} */
 let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
 
@@ -101,4 +108,19 @@ let dressed = (style) => !!(style && (style.underline || style.strikethrough));
 /** @type {(style: any) => boolean} */
 let upper = (style) => !!(style && style.uppercase);
 
-export { BAND, BLACK, GUTTER, LEAD, PADX, PADY, col, dressed, merge, roled, shift, sizeOf, upper };
+export {
+  BAND,
+  BLACK,
+  GUTTER,
+  LEAD,
+  PADX,
+  PADY,
+  col,
+  dressed,
+  merge,
+  roled,
+  shift,
+  sizeOf,
+  upper,
+  vshift,
+};

package/lib/text.js

@@ -7,15 +7,12 @@ import { display, format } from "quario";
 import { ascOf, face, printable, width } from "./fonts.js";
 import { LEAD, col, dressed, sizeOf, upper } from "./style.js";
 
-// What measuring needs and no more: the embedded faces to measure against, and
-// the base size and family a style falls back to — the report default's two
-// declarations, which the canvas carries for the whole render. A `Canvas`
-// satisfies it, so callers pass theirs straight in — but nothing here can
-// touch a page.
-/**
- * @typedef {{ fonts: import('./fonts.js').Fonts, base: number,
- *   family: string | null, locale?: string, currency?: string, timeZone?: string }} Metrics
- */
+// What measuring needs and no more, and it is exactly the render's settings:
+// the faces to measure against, the base size and family a style falls back to,
+// and the intl three a formatted value resolves in. Declared in `settings.js`,
+// the module that owns them; a caller hands over `canvas.settings` rather than
+// the canvas, so nothing here can touch a page.
+/** @typedef {import('./settings.js').Settings} Settings */
 
 /**
  * @typedef {{ text: string, font: any, size: number, color: any,
@@ -29,10 +26,10 @@ import { LEAD, col, dressed, sizeOf, upper } from "./style.js";
 
 /** @typedef {{ cur: Atom[], w: number, lines: Line[], base: number }} Wrap */
 
-/** @type {(token: any, style: any, metrics: Metrics) => string} */
-let rawOf = (token, style, metrics) => {
+/** @type {(token: any, style: any, settings: Settings) => string} */
+let rawOf = (token, style, settings) => {
   if ("literal" in token) return token.literal;
-  return format(token.value, style?.format, metrics) ?? display(token.value);
+  return format(token.value, style, settings) ?? display(token.value);
 };
 
 // This layout has no text-transform to defer to, so `uppercase` is applied to
@@ -43,12 +40,9 @@ let rawOf = (token, style, metrics) => {
 /** @type {(text: string, style: any) => string} */
 let cased = (text, style) => (upper(style) ? text.toUpperCase() : text);
 
-/** @type {(font: any, line: string) => string[]} */
-let partsOf = (font, line) => printable(font, line).split(/( +)/).filter(Boolean);
-
 /** @type {(out: Atom[], font: any, size: number, color: any, line: string) => void} */
 let pushParts = (out, font, size, color, line) => {
-  for (let part of partsOf(font, line))
+  for (let part of printable(font, line).split(/( +)/).filter(Boolean))
     out.push({ text: part, font, size, color, space: part[0] === " ", hard: false });
 };
 
@@ -58,12 +52,12 @@ let pushLine = (out, font, size, color, i, line) => {
   pushParts(out, font, size, color, line);
 };
 
-/** @type {(metrics: Metrics, style: any) => { font: any, size: number, color: any }} */
-let look = (metrics, style) => {
+/** @type {(settings: Settings, style: any) => { font: any, size: number, color: any }} */
+let look = (settings, style) => {
   let resolved = style || {};
   return {
-    font: face(metrics.fonts, resolved, metrics.family),
-    size: sizeOf(resolved, metrics.base),
+    font: face(settings.fonts, resolved, settings.family),
+    size: sizeOf(resolved, settings.base),
     color: col(resolved.color),
   };
 };
@@ -71,12 +65,12 @@ let look = (metrics, style) => {
 // Flatten a cell's tokens to word/space atoms carrying the cell's resolved
 // typography — one face, size and colour for the whole cell. CR, LF, and
 // CRLF are one hard break each (SCHEMA.md, Cell values).
-/** @type {(metrics: Metrics, tokens: any[], style: any) => Atom[]} */
-let atoms = (metrics, tokens, style) => {
+/** @type {(settings: Settings, tokens: any[], style: any) => Atom[]} */
+let atoms = (settings, tokens, style) => {
   let out = /** @type {Atom[]} */ ([]);
-  let { font, size, color } = look(metrics, style);
+  let { font, size, color } = look(settings, style);
   for (let token of tokens)
-    for (let [i, line] of cased(rawOf(token, style, metrics), style)
+    for (let [i, line] of cased(rawOf(token, style, settings), style)
       .split(/\r\n|\r|\n/)
       .entries())
       pushLine(out, font, size, color, i, line);
@@ -228,8 +222,8 @@ let placeAtom = (state, atom, avail) => {
 // breaks by character, hard breaks always break. A cell's atoms share one
 // typography, so a line's atoms merge into a single draw piece. `size` is the
 // empty-run height — a blank item, a hard-break hole.
-/** @type {(metrics: Metrics, list: Atom[], avail: number, size: number) => Line[]} */
-let wrap = (metrics, list, avail, size) => {
+/** @type {(list: Atom[], avail: number, size: number) => Line[]} */
+let wrap = (list, avail, size) => {
   /** @type {Wrap} */
   let state = { cur: [], w: 0, lines: [], base: size };
   for (let atom of list) placeAtom(state, atom, avail);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/layout",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "The paged display list for quario — the layout the PDF target writes and the viewer paints — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -40,18 +40,19 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
-    "@pdf-lib/fontkit": "^1.1.1",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.4.0",
+    "@types/fontkit": "^2.0.9",
+    "fontkit": "^2.0.4",
+    "quario": "^0.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "@pdf-lib/fontkit": "^1.1.1",
-    "quario": "^0.4.0"
+    "fontkit": "^2.0.4",
+    "quario": "^0.6.0"
   },
   "peerDependenciesMeta": {
-    "@pdf-lib/fontkit": {
+    "fontkit": {
       "optional": true
     }
   },