@quario/layout 0.1.0

package/lib/page.js

@@ -0,0 +1,99 @@
+/**
+ * The page box: what a host's `page` option means in points, validated where
+ * 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.
+ */
+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.
+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 known = (size) => (Object.hasOwn(SIZES, size) ? SIZES[size] : null);
+
+/** @type {(size: any, at: string) => any} */
+let named = (size = "A4", at) => {
+  let dimensions = Array.isArray(size) ? size : known(size);
+  // oxlint-disable-next-line no-unused-expressions
+  dimensions || err(at + '.size: unknown page size "' + size + '"');
+  return dimensions;
+};
+
+/** @type {(dimensions: any, at: string) => { width: number, height: number }} */
+let pair = (dimensions, at) => {
+  let width = +dimensions[0],
+    height = +dimensions[1];
+  // oxlint-disable-next-line no-unused-expressions
+  (positive(width) && positive(height)) || err(at + ".size: expected finite positive dimensions");
+  return { width, height };
+};
+
+/** @type {(margin: any, width: number, height: number, path: string) => number} */
+let marginOf = (margin = 54, width, height, path) => {
+  let fits = Number.isFinite(margin) && margin >= 0 && 2 * margin < Math.min(width, height);
+  // oxlint-disable-next-line no-unused-expressions
+  fits || err(path + ": expected a non-negative number smaller than half the page");
+  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} */
+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 {(opening: any, page: any, at: string) => { value: any, path: string }} */
+let marginChoice = (opening, page, at) => {
+  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: doc != null ? "page.margin" : at + ".margin" };
+};
+
+/**
+ * The page box a `page` option describes, validated: width, height and
+ * margin in points. `at` prefixes the failure — `options.page` for a target's
+ * option, `page` for an element's property — so a host hears where it wrote
+ * the mistake.
+ *
+ * @param {any} page The `page` option, or undefined for the defaults.
+ * @param {string} [at] The option's name in a failure.
+ * @returns {{ width: number, height: number, margin: number }}
+ */
+export let pageBox = (page, at = "page") => {
+  let { width, height } = pair(named(page?.size, at), at);
+  return { width, height, margin: marginOf(page?.margin, width, height, at + ".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}
+ */
+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);
+};

package/lib/paint.js

@@ -0,0 +1,266 @@
+/**
+ * The Canvas 2D painter, and the hit-test beside it: the browser half of the
+ * list, for the viewer's sheet and the editor's design surface. Everything
+ * the list says is in points from the page's top-left corner, so painting is
+ * one scale and a walk over the ops; nothing here re-measures, re-wraps or
+ * decides where anything goes.
+ *
+ * Text is drawn one of two ways, and the op says which. A base-14 family is
+ * drawn glyph by glyph at the advances the measurer recorded, because what the
+ * browser has is a [stand-in face](../../../CONTEXT.md#stand-in-face) — Arial
+ * for Helvetica — and the correction is what makes the words fill the same
+ * width and break on the same line as the PDF. A host-supplied family is
+ * registered as a `FontFace` from the same bytes the layout measured and the
+ * PDF embeds, and its runs are drawn whole: the browser is shaping the very
+ * font pdf-lib will, so correcting it would be replacing a good answer with a
+ * worse one — and a shaped run has no advance per character to correct with.
+ */
+
+import { VARIANTS, bytesOf } from "./fonts.js";
+
+/**
+ * CSS pixels per point at 100%: the browser's own 96 dpi over PostScript's
+ * 72. The one home for how a point becomes a length on screen, so every
+ * surface that shows a page shows it at the same size — a zoom is a factor
+ * on top of this, never a second answer to it.
+ */
+export let PX_PER_POINT = 96 / 72;
+
+/** @import { Box, FaceRef, Op, Page } from './index.d.ts' */
+/** @typedef {import('./style.js').Color} Color */
+
+// The screen stand-ins for the three generic families. Each is the face the
+// base-14 metrics describe, then the platform's nearest.
+/** @type {Record<string, string>} */
+let GENERIC = {
+  sans: "Helvetica, Arial, sans-serif",
+  serif: '"Times New Roman", Times, serif',
+  mono: '"Courier New", Courier, monospace',
+};
+
+/** @type {(family: string) => string} */
+let registered = (family) => "quario-" + family;
+
+// Own-key lookup, and sans for anything else: a base-14 ref only ever names
+// one of the three, but `paint` is public and the list it is handed is data.
+/** @type {(family: string) => string} */
+let generic = (family) => (Object.hasOwn(GENERIC, family) ? GENERIC[family] : GENERIC.sans);
+
+/** @type {(color: Color) => string} */
+let css = ({ r, g, b }) =>
+  "rgb(" + Math.round(r * 255) + "," + Math.round(g * 255) + "," + Math.round(b * 255) + ")";
+
+// Which face to ask the browser for, from the ref's own account of itself. It
+// turns on `embedded`, never on the family name: a host may map its family onto
+// `sans`, `serif` or `mono` (SCHEMA.md), and reading the name would hand back
+// the generic stand-in for a face whose bytes are registered and waiting.
+/** @type {(font: FaceRef, size: number) => string} */
+let fontOf = (font, size) => {
+  let family = font.embedded ? registered(font.family) : generic(font.family);
+  return (
+    (font.variant & 2 ? "italic " : "") + (font.variant & 1 ? "bold " : "") + size + "px " + family
+  );
+};
+
+// Every FontFace registered so far, so a family a host passes on every render
+// is registered once. Keyed on the source object itself, never on the bytes:
+// a host may hand over an ArrayBuffer, and `bytesOf` allocates a fresh view
+// every call, so a bytes-keyed entry would never be found twice. That makes
+// the host's own object the identity — the stability `LayoutOptions.fonts`
+// asks for.
+//
+// A face is a family and a descriptor as much as it is bytes, so one file
+// aliased across two families, or across a family's regular and bold, is two
+// faces: the inner key carries the pair, and sharing one entry between them
+// would leave the second name unregistered and its weight to the browser's
+// synthesis.
+/** @type {WeakMap<object, Map<string, Promise<FontFace>>>} */
+let FACES = new WeakMap();
+
+// The CSS descriptors of each variant, by the measurer's own index.
+/** @type {(variant: number) => { weight: string, style: string }} */
+let descriptors = (variant) => ({
+  weight: variant & 1 ? "bold" : "normal",
+  style: variant & 2 ? "italic" : "normal",
+});
+
+/** @type {(family: string, source: any, variant: number) => Promise<FontFace>} */
+let register = (family, source, variant) => {
+  let registry = FACES.get(source);
+  if (!registry) FACES.set(source, (registry = new Map()));
+  let key = family + "/" + variant;
+  let loading = registry.get(key);
+  if (loading) return loading;
+  // The cast: TypeScript's `BufferSource` does not admit a `Uint8Array` over
+  // a shared buffer, which the bytes never are here.
+  let face = new FontFace(
+    registered(family),
+    /** @type {any} */ (bytesOf(source)),
+    descriptors(variant),
+  );
+  document.fonts.add(face);
+  loading = face.load();
+  // Written before the first await, so concurrent paints share one load.
+  registry.set(key, loading);
+  return loading;
+};
+
+// A missing variant is not registered: the layout measured it as the regular
+// face, and the browser's synthesis would draw it differently. The CSS font
+// string still asks for bold, so the face descriptor decides.
+/** @type {(name: string, def: any) => Promise<FontFace>[]} */
+let registerFamily = (name, def) => {
+  let family = name.toLowerCase();
+  return VARIANTS.map((key, variant) => [key, variant])
+    .filter(([key]) => def[key] != null)
+    .map(([key, variant]) => register(family, def[key], /** @type {number} */ (variant)));
+};
+
+/** @type {(fonts: any) => Promise<void>} */
+let loadFaces = async (fonts) => {
+  if (!fonts || typeof FontFace === "undefined") return;
+  await Promise.all(Object.entries(fonts).flatMap(([name, def]) => registerFamily(name, def)));
+};
+
+// Every bitmap decoded so far, by the bytes it was decoded from: one logo on
+// every page is decoded once.
+/** @type {WeakMap<Uint8Array, Promise<ImageBitmap>>} */
+let BITMAPS = new WeakMap();
+
+/** @type {(op: { bytes: Uint8Array, format: string }) => Promise<ImageBitmap>} */
+let bitmapOf = (op) => {
+  let decoding = BITMAPS.get(op.bytes);
+  if (decoding) return decoding;
+  decoding = createImageBitmap(
+    new Blob([/** @type {any} */ (op.bytes)], { type: "image/" + op.format }),
+  );
+  BITMAPS.set(op.bytes, decoding);
+  return decoding;
+};
+
+/** @type {(ctx: CanvasRenderingContext2D, op: any) => void} */
+let paintRect = (ctx, op) => {
+  ctx.fillStyle = css(op.color);
+  ctx.fillRect(op.x, op.y, op.w, op.h);
+};
+
+/** @type {(ctx: CanvasRenderingContext2D, op: any) => void} */
+let paintLine = (ctx, op) => {
+  ctx.strokeStyle = css(op.color);
+  ctx.lineWidth = op.width;
+  ctx.setLineDash(op.dash || []);
+  ctx.beginPath();
+  ctx.moveTo(op.x1, op.y1);
+  ctx.lineTo(op.x2, op.y2);
+  ctx.stroke();
+};
+
+// One of two placements, on `embedded` alone — inferring it from whether
+// `advances` happens to be there would be a second answer to a question the
+// ref already answers, which is the mistake this replaced.
+//
+// A host's face draws the run whole. Nothing to correct: the browser is
+// shaping the same bytes, so its ligatures, its mark placement and its RTL
+// order are the ones the document will have. A base-14 face draws character by
+// character at the recorded advances, because the face on screen only stands
+// in for the one measured and would otherwise drift across the run — and one
+// advance per code point holds by construction, the encoding being a
+// one-to-one table with no shaping behind it, so there is nothing to check.
+/** @type {(ctx: CanvasRenderingContext2D, op: any) => void} */
+let paintText = (ctx, op) => {
+  ctx.font = fontOf(op.font, op.size);
+  ctx.fillStyle = css(op.color);
+  ctx.textBaseline = "alphabetic";
+  let baseline = op.y + op.asc;
+  if (op.font.embedded) {
+    ctx.fillText(op.text, op.x, baseline);
+    return;
+  }
+  let x = op.x;
+  for (let [i, char] of Array.from(op.text).entries()) {
+    ctx.fillText(char, x, baseline);
+    x += op.advances[i];
+  }
+};
+
+/** @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.
+/** @type {(ctx: CanvasRenderingContext2D, op: any) => void} */
+let paintMark = (ctx, op) => {
+  ctx.save();
+  ctx.translate(op.x, op.y);
+  ctx.rotate((-op.angle * Math.PI) / 180);
+  ctx.globalAlpha = 0.15;
+  ctx.font = fontOf(op.font, op.size);
+  ctx.fillStyle = "rgb(128,128,128)";
+  ctx.textBaseline = "alphabetic";
+  ctx.fillText(op.text, 0, 0);
+  ctx.restore();
+};
+
+/** @type {Record<string, (ctx: CanvasRenderingContext2D, op: any) => void>} */
+let PAINTERS = { rect: paintRect, line: paintLine, text: paintText, mark: paintMark };
+
+/** @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);
+};
+
+// Every image on the page, decoded together rather than one after another.
+/** @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]]));
+};
+
+/**
+ * Paint one page of the list onto a Canvas 2D context: a white page, then
+ * every op in order. `scale` is device pixels per point — the caller sized
+ * 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.
+ *
+ * @param {CanvasRenderingContext2D} ctx The context to paint on.
+ * @param {Page} page One page of a `Layout`.
+ * @param {{ scale?: number, fonts?: any }} [options]
+ * @returns {Promise<void>} Settles once the page is painted — after the
+ *   faces it needs have loaded and its images decoded.
+ */
+export async function paint(ctx, page, { scale = 1, fonts } = {}) {
+  await loadFaces(fonts);
+  let bitmaps = await decode(page);
+  ctx.save();
+  ctx.setTransform(scale, 0, 0, scale, 0, 0);
+  ctx.fillStyle = "#fff";
+  ctx.fillRect(0, 0, page.width, page.height);
+  for (let op of page.ops) paintOp(ctx, op, bitmaps);
+  ctx.restore();
+}
+
+/** @type {(box: Box, x: number, y: number) => boolean} */
+let inside = (box, x, y) => x >= box.x && x <= box.x + box.w && y >= box.y && y <= box.y + box.h;
+
+/** @type {(best: Box | null, box: Box) => boolean} */
+let smaller = (best, box) => !best || box.w * box.h < best.w * best.h;
+
+/**
+ * The schema node drawn at a point on a page: the smallest box containing it,
+ * so a slot inside a split wins over the split. Points from the page's
+ * top-left corner.
+ *
+ * @param {Page} page One page of a `Layout`.
+ * @param {number} x
+ * @param {number} y
+ * @returns {Box | null} The box, or `null` where nothing was drawn.
+ */
+export function hit(page, x, y) {
+  /** @type {Box | null} */
+  let best = null;
+  for (let box of page.boxes) if (inside(box, x, y) && smaller(best, box)) best = box;
+  return best;
+}

package/lib/style.js

@@ -0,0 +1,104 @@
+/**
+ * The layout's reading of the closed style vocabulary — the counterpart of
+ * the CSS table in the HTML target package. Declarations are lenient at
+ * render: a value of the wrong shape contributes nothing rather than reaching
+ * the page.
+ *
+ * `HEX` is restated per target on purpose: the coercion is each target's own
+ * edge, never shared engine code. Finiteness is not one of those coercions —
+ * `Number.isFinite` never coerces, so this layout asks it directly.
+ */
+
+/**
+ * A colour on the list: three channels in `0..1`, the way pdf-lib takes them.
+ * Format-neutral on purpose — the PDF painter wraps it in pdf-lib's `rgb`,
+ * the Canvas painter writes it as a CSS `rgb()`.
+ * @typedef {{ r: number, g: number, b: number }} Color
+ */
+
+let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+// Leading as a fraction of the font size, cell padding, the gap between a
+// page band and the body, and the gutter between two page-column strips.
+// `example/print.css` is the reference look (10pt/1.4) — body type stays a
+// host decision, so `@quario/html/style.css` carries no `body` rule and this
+// pairs with the example rather than it.
+//
+// GUTTER is this layout's structural default: SCHEMA.md gives page columns no
+// gap knob deliberately, so the space between strips is the layout's to pick
+// and an author never writes it. Twice the cell padding, which is the widest
+// space this target already puts between two columns of anything.
+let LEAD = 1.4;
+let PADX = 6;
+let PADY = 2;
+let BAND = 8;
+let GUTTER = 2 * PADX;
+
+/** @type {Color} */
+let BLACK = { r: 0, g: 0, b: 0 };
+
+// Horizontal placement within a given leftover width: left keeps it, right
+// takes all of it, center takes half. Own-key so an authored `constructor`
+// cannot resolve an inherited member.
+/** @type {Record<string, number>} */
+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;
+
+// A declared colour as a `Color`, or null when the value is not one.
+/** @type {(value: any) => Color | null} */
+let col = (value) => {
+  let match = typeof value === "string" && HEX.exec(value);
+  if (!match) return null;
+  // `#abc` is `#aabbcc`.
+  let digits = match[1].length === 3 ? match[1].replace(/./g, (d) => d + d) : match[1];
+  let [r, g, b] = [0, 2, 4].map((i) => parseInt(digits.slice(i, i + 2), 16) / 255);
+  return { r, g, b };
+};
+
+/** @type {(style: any, base: number) => number} */
+let sizeOf = (style, base) => (Number.isFinite(style.size) && style.size > 0 ? style.size : base);
+
+// 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.
+/** @type {(under: any, over: any) => any} */
+let merge = (under, over) => (under ? (over ? { ...under, ...over } : under) : over || {});
+
+// Band-role omakase defaults — the third of those four layers, over the report
+// default and under the author's own, which therefore always wins. Only the
+// headline roles carry one; the XLSX target carries the same two,
+// byte-identical, in `packages/xlsx/lib/index.js`, and they move together
+// (SCHEMA.md states the pair for both). A target can only import public engine helpers, so there is
+// nowhere to share this from and the two copies are synced by hand.
+//
+// `@quario/html` deliberately carries none of this, nor the leading, padding
+// and band gap below: its consumer has a stylesheet and the `q-*` classes are
+// the seam. The rule is docs/adr/0014-a-target-supplies-defaults-only-where-its-consumer-has-no-seam.md —
+// a target supplies defaults only where its consumer has no seam to supply
+// them. `@quario/html/style.css` is what supplies them there; keep the three in
+// agreement.
+/** @type {Record<string, any>} */
+let ROLES = { "report-header": { bold: true, size: 14 }, "group-header": { bold: true } };
+
+// One item event wearing its role's defaults. Events reach layout as events,
+// so the default is folded into a copy rather than passed alongside.
+/** @type {(event: any) => any} */
+let roled = (event) =>
+  Object.hasOwn(ROLES, event.role)
+    ? { ...event, style: merge(ROLES[event.role], event.style) }
+    : event;
+
+// Whether a resolved style asks for either text decoration -- one reading for
+// the wrapper that stamps it on a line and the canvas that draws it.
+/** @type {(style: any) => boolean} */
+let dressed = (style) => !!(style && (style.underline || style.strikethrough));
+
+// Whether a resolved style asks for capitals. This target has no
+// text-transform to defer to, so the reading is here beside the rest of the
+// vocabulary and `text.js` applies it before measuring.
+/** @type {(style: any) => boolean} */
+let upper = (style) => !!(style && style.uppercase);
+
+export { BAND, BLACK, GUTTER, LEAD, PADX, PADY, col, dressed, merge, roled, shift, sizeOf, upper };