@quario/layout 0.1.0

package/lib/index.js

@@ -0,0 +1,114 @@
+/**
+ * @quario/layout — the paged layout of a report, as a display list. Not a
+ * document format: `layout(options)` is a target whose output is pages of
+ * boxes, text runs, rules and images in points, and two painters consume
+ * that list — `@quario/pdf` writes it through pdf-lib, and `paint` here draws
+ * it on a Canvas 2D context for the viewer and the editor
+ * (docs/adr/0039-preview-pages-from-a-shared-layout-list.md).
+ *
+ * The algorithm is the PDF target's typesetter — wrapped paragraphs,
+ * keep-together, repeated table headers, page bands, `break: "page"`,
+ * `reset: "page"` — with its home moved so pdf-lib does not follow the
+ * preview. Node-safe: nothing here reaches pdf-lib or a browser canvas, and
+ * measurement is this package's own (`fonts.js`), so a preview and a PDF
+ * given the same `page` and the same font bytes break their lines in the same
+ * places.
+ *
+ * This file is the target's options, the walk itself, and the passes that
+ * follow it over the finished pages — page furniture and the marking, neither
+ * of which can be drawn until the page count is known. Every handler the
+ * driver dispatches to is the band flow's, next door in `layout.js`; this
+ * file adds none. The package publishes `lib/` verbatim.
+ */
+import { breathe, walk } from "quario";
+import { listing, stamp } from "./canvas.js";
+import { checkFonts, loadFonts } from "./fonts.js";
+import { flow, furniture } from "./layout.js";
+import { geometry } from "./page.js";
+
+export { PX_PER_POINT, hit, paint } from "./paint.js";
+export { pageBox } from "./page.js";
+
+// The options are described once, in the hand-written public declarations, and
+// read back here — a second copy in JSDoc is a copy that drifts.
+/** @import { Layout, LayoutOptions } from './index.d.ts' */
+
+/** @type {(canvas: import('./canvas.js').Listing, draw: (i: number) => void) => Promise<void>} */
+let overPages = async (canvas, draw) => {
+  for (let i = 0; i < canvas.count; i++) {
+    canvas.select(i);
+    draw(i);
+    if (i % 50 === 49) await breathe();
+  }
+};
+
+/** @type {(canvas: import('./canvas.js').Listing, bands: any,
+ *   pages: { number: number, total: number }[]) => Promise<void>} */
+let furnish = async (canvas, bands, pages) => {
+  if (!bands) return;
+  await overPages(canvas, (i) => furniture(canvas, bands, pages[i]));
+};
+
+/** @type {(canvas: import('./canvas.js').Listing, marking: any) => Promise<void>} */
+let markPages = async (canvas, marking) => {
+  if (!marking) return;
+  let mark = stamp(canvas, marking);
+  await overPages(canvas, () => canvas.watermark(mark));
+};
+
+/**
+ * The layout target:
+ * `quario().report(schema).render(layout({ page }), data)` resolves the
+ * display list — every page of the document, with its `{ number, total }`,
+ * its ops and its hit boxes. Geometry and the font mapping's shape are
+ * validated here, at the factory call.
+ *
+ * @param {LayoutOptions} [options] Host controls (see SCHEMA.md, "The PDF target").
+ * @returns {{name: "layout", compile: (stream: any) => (data?: any) => Promise<Layout>}}
+ *   The target (see SCHEMA.md, "Instances and targets").
+ */
+export function layout(options) {
+  geometry(options?.page);
+  checkFonts(options?.fonts);
+  let custom = options?.fonts;
+  /** @type {(stream: any) => (data?: any) => Promise<Layout>} */
+  let compile = (stream) => async (data) => {
+    // Every face is loaded before the walk, so resolving a style to a face
+    // during layout stays synchronous.
+    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 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);
+    function* events() {
+      if (!first.done) yield first.value;
+      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 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);
+    // 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);
+    return /** @type {Layout} */ ({
+      width: geo.width,
+      height: geo.height,
+      pages: canvas.pages.map((page, i) => ({ ...page, ...pages[i] })),
+      marks,
+    });
+  };
+  return { name: "layout", compile };
+}