@quario/layout 0.1.0

package/lib/canvas.js

@@ -0,0 +1,335 @@
+/**
+ * The drawing surface. Every mark the band flow makes goes through here, so
+ * nothing above this module knows what a page is made of.
+ *
+ * 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
+ * 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.
+ *
+ * The band flow works in the page's own coordinates — the origin at the
+ * bottom-left, `y` climbing, the convention the PDF target writes in. The
+ * list is the format-neutral half, so the recorder turns every mark over as
+ * 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";
+
+/** @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.
+/**
+ * `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,
+ *   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,
+ *   drawLine: (line: Line, x: number, yTop: number, avail: number,
+ *     align: any) => void,
+ *   box: (path: string | undefined, x: number, yTop: number, w: number,
+ *     h: number) => void }} Canvas
+ */
+
+// The page passes on top of the interface: re-visiting finished pages and
+// stamping them. Deliberately not on `Canvas` — the layout may not re-target a
+// page mid-walk, and a measurement has no business doing any of it.
+/**
+ * @typedef {Canvas & { select: (i: number) => void, pages: Page[],
+ *   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.
+/**
+ * @type {(box: Frame, fonts: import('./fonts.js').Fonts) =>
+ *   Frame & Metrics & { y: number, fresh: boolean }}
+ */
+let blank = (box, fonts) => ({ ...box, fonts, 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).
+// Empty lines (no width) draw nothing. Shared by the listing adapter and the
+// layout suite's recorder so both exercise the same path.
+/** @type {(line: Line) => Color} */
+let ink = (line) => (line.pieces[0] && line.pieces[0].color) || BLACK;
+
+/** @type {(line: Line) => boolean} */
+let wantsDeco = (line) => !!line.w && dressed(line);
+
+/**
+ * @type {(stroke: (x1: number, x2: number, y: number, thickness: number, color: Color) => void,
+ *   line: Line, left: number, baseline: number) => void}
+ */
+let decorateLine = (stroke, line, left, baseline) => {
+  if (!wantsDeco(line)) return;
+  let thickness = Math.max(line.asc / 12, 0.5);
+  let right = left + line.w;
+  let color = ink(line);
+  if (line.underline) stroke(left, right, baseline - line.asc * 0.12, thickness, color);
+  if (line.strikethrough) stroke(left, right, baseline + line.asc * 0.35, thickness, color);
+};
+
+/**
+ * The adapter that records: a canvas whose marks become the display list.
+ *
+ * @type {(box: Frame, fonts: import('./fonts.js').Fonts) => Listing}
+ */
+let listing = (box, fonts) => {
+  // A page under construction: its `number`/`total` are the target's to add
+  // once the count is known.
+  /** @type {any} */
+  let page;
+  /** @type {any[]} */
+  let pages = [];
+  // A page coordinate turned over: the list reads down from the top.
+  /** @type {(y: number) => number} */
+  let down = (y) => canvas.height - y;
+
+  // Open a fresh page and put the cursor at its top.
+  let newPage = () => {
+    page = { width: canvas.width, height: canvas.height, ops: [], boxes: [] };
+    pages.push(page);
+    canvas.y = canvas.top;
+    canvas.fresh = true;
+  };
+
+  /** @type {Canvas['rect']} */
+  let rect = (color, x, y, w, h) => page.ops.push({ kind: "rect", x, y: down(y + h), w, h, color });
+
+  /** @type {Canvas['stroke']} */
+  let stroke = (x1, y1, x2, y2, thickness, color, dash) =>
+    page.ops.push({
+      kind: "line",
+      x1,
+      y1: down(y1),
+      x2,
+      y2: down(y2),
+      width: thickness,
+      color,
+      dash,
+    });
+
+  /** @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 });
+
+  // `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
+  // corrected glyph by glyph. A host's own face has no `shape`, so the op
+  // carries none and a painter draws the run whole.
+  /** @type {(piece: Line['pieces'][number], line: Line, x: number, yTop: number) => void} */
+  let writePiece = (piece, line, x, yTop) => {
+    if (!piece.text) return;
+    page.ops.push({
+      kind: "text",
+      x,
+      y: down(yTop),
+      w: piece.w,
+      h: line.h,
+      asc: line.asc,
+      size: piece.size,
+      font: piece.font.ref,
+      color: piece.color || BLACK,
+      text: piece.text,
+      ...(piece.font.shape ? { advances: piece.font.shape(piece.text, piece.size).advances } : {}),
+    });
+  };
+
+  /** @type {(left: number, right: number, y: number, thickness: number, color: Color) => void} */
+  let strokeAt = (left, right, y, thickness, color) =>
+    stroke(left, y, right, y, thickness, color, null);
+
+  // Record one wrapped line with its baseline the line's ascender under
+  // `yTop`, horizontally placed by `align` within `avail` starting at `x`.
+  /** @type {Canvas['drawLine']} */
+  let drawLine = (line, x, yTop, avail, align) => {
+    let left = x + shift(align, avail - line.w);
+    let cursor = left;
+    for (let piece of line.pieces) {
+      writePiece(piece, line, cursor, yTop);
+      cursor += piece.w;
+    }
+    decorateLine(strokeAt, line, left, yTop - line.asc);
+  };
+
+  // A node's rectangle. Only a node with a path is a hit box: a split minted
+  // by the folder has none, and its slots carry their own.
+  /** @type {Canvas['box']} */
+  let box_ = (path, x, yTop, w, h) => {
+    if (path) page.boxes.push({ path, x, y: down(yTop), w, h });
+  };
+
+  /** @type {Listing['watermark']} */
+  let watermark = (mark) =>
+    page.ops.push({
+      kind: "mark",
+      x: mark.x,
+      y: down(mark.y),
+      angle: mark.angle,
+      size: mark.size,
+      font: mark.font.ref,
+      text: mark.text,
+    });
+
+  /** @type {Listing} */
+  let canvas = {
+    ...blank(box, fonts),
+    get count() {
+      return pages.length;
+    },
+    newPage,
+    rect,
+    stroke,
+    picture,
+    drawLine,
+    box: box_,
+    // Re-open a finished page, for the passes that run over them all.
+    select: (i) => {
+      page = pages[i];
+    },
+    pages,
+    watermark,
+  };
+  return canvas;
+};
+
+// Nothing at all — what every primitive does when the canvas only measures.
+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}
+ */
+let measuring = (box, fonts) => ({
+  ...blank(box, fonts),
+  count: 0,
+  newPage: () => {
+    throw new Error("probe reached newPage: the measuring path must not paginate");
+  },
+  rect: MARKS_NOTHING,
+  stroke: MARKS_NOTHING,
+  picture: MARKS_NOTHING,
+  drawLine: MARKS_NOTHING,
+  box: MARKS_NOTHING,
+});
+
+/**
+ * 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.
+ *
+ * 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
+ * empty. `fresh` alone would not say that: a page turn makes it true again on
+ * page five, where narrowing would silently mix two geometries in one document.
+ *
+ * @param {Canvas} canvas The canvas to narrow.
+ * @param {Frame} box The frame it takes its content box from.
+ */
+let adopt = (canvas, box) => {
+  if (canvas.count > 1 || !canvas.fresh) throw Error("adopt: the content box is fixed");
+  canvas.top = box.top;
+  canvas.bottom = box.bottom;
+  // The open page has drawn nothing, so its cursor moves with the box — the
+  // same statement `newPage` makes, and nothing on the page can be lost by it.
+  canvas.y = canvas.top;
+};
+
+// 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.
+// The wording comes from the engine, on `report-start`; the layout owns the
+// geometry, which depends only on the page size and never on key contents,
+// so document bytes stay deterministic in both licensed states.
+
+/**
+ * The per-render half of the marking, computed once: page geometry, the face
+ * and the wording are all fixed for a whole render, so the trig and the
+ * glyph-width walk never repeat per page. `x`/`y` are the baseline's start in
+ * page coordinates and `angle` the turn in degrees, counter-clockwise.
+ * @typedef {{ font: import('./fonts.js').Face, text: string, size: number,
+ *   x: number, y: number, angle: number }} Mark
+ */
+/**
+ * The marking is the licence boundary, not report content, so it takes the
+ * base-14 sans and never the host's mapping of that name: an author never
+ * styled it, and it must fail open (docs/adr/0002). Its size is solved from a
+ * face's widths, so inheriting a host family would size it against bytes a
+ * painter may fail to load and draw it in whatever the fallback is.
+ * @type {(canvas: Canvas, text: string) => Mark}
+ */
+let stamp = (canvas, text) => {
+  let font = baseSans();
+  let angle = Math.atan2(canvas.height, canvas.width);
+  // Scale the line to three quarters of the page diagonal, whatever the size.
+  let span = Math.hypot(canvas.width, canvas.height) * 0.75;
+  return {
+    font,
+    text,
+    size: (54 * span) / font.widthOfTextAtSize(text, 54),
+    x: canvas.width / 2 - (span / 2) * Math.cos(angle),
+    y: canvas.height / 2 - (span / 2) * Math.sin(angle),
+    angle: (angle * 180) / Math.PI,
+  };
+};
+
+export { adopt, decorateLine, frame, listing, measuring, stamp };