@quario/layout 0.1.0

package/lib/text.js

@@ -0,0 +1,258 @@
+/**
+ * Measuring and breaking text: tokens flatten to word and space atoms carrying
+ * their resolved typography, and a greedy breaker turns those into lines. Pure
+ * measurement against the font registry — nothing here touches the page.
+ */
+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
+ */
+
+/**
+ * @typedef {{ text: string, font: any, size: number, color: any,
+ *   space: boolean, hard: boolean }} Atom
+ */
+/**
+ * @typedef {{ pieces: { text: string, font: any, size: number, color: any,
+ *   w: number }[], w: number, h: number, size: number, asc: number,
+ *   underline?: boolean, strikethrough?: boolean }} Line
+ */
+
+/** @typedef {{ cur: Atom[], w: number, lines: Line[], base: number }} Wrap */
+
+/** @type {(token: any, style: any, metrics: Metrics) => string} */
+let rawOf = (token, style, metrics) => {
+  if ("literal" in token) return token.literal;
+  return format(token.value, style?.format, metrics) ?? display(token.value);
+};
+
+// This layout has no text-transform to defer to, so `uppercase` is applied to
+// the string before it is measured -- the widths have to be the widths of what
+// is actually drawn. `toUpperCase` rather than `toLocaleUpperCase`: the
+// PDF target's output is byte-reproducible, so the host's locale must not reach
+// the glyphs.
+/** @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))
+    out.push({ text: part, font, size, color, space: part[0] === " ", hard: false });
+};
+
+/** @type {(out: Atom[], font: any, size: number, color: any, i: number, line: string) => void} */
+let pushLine = (out, font, size, color, i, line) => {
+  if (i) out.push({ text: "", font, size, color, space: false, hard: true });
+  pushParts(out, font, size, color, line);
+};
+
+/** @type {(metrics: Metrics, style: any) => { font: any, size: number, color: any }} */
+let look = (metrics, style) => {
+  let resolved = style || {};
+  return {
+    font: face(metrics.fonts, resolved, metrics.family),
+    size: sizeOf(resolved, metrics.base),
+    color: col(resolved.color),
+  };
+};
+
+// 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) => {
+  let out = /** @type {Atom[]} */ ([]);
+  let { font, size, color } = look(metrics, style);
+  for (let token of tokens)
+    for (let [i, line] of cased(rawOf(token, style, metrics), style)
+      .split(/\r\n|\r|\n/)
+      .entries())
+      pushLine(out, font, size, color, i, line);
+  return out;
+};
+
+/** @type {(cur: Atom[]) => void} */
+let trimEnd = (cur) => {
+  while (cur.length && cur[cur.length - 1].space) cur.pop();
+};
+
+/** @type {(pieces: Line['pieces'], atom: Atom, atomWidth: number) => void} */
+let mergeAtom = (pieces, atom, atomWidth) => {
+  let last = pieces[pieces.length - 1];
+  if (last) {
+    last.text += atom.text;
+    last.w += atomWidth;
+    return;
+  }
+  pieces.push({
+    text: atom.text,
+    font: atom.font,
+    size: atom.size,
+    color: atom.color,
+    w: atomWidth,
+  });
+};
+
+/** @typedef {{ pieces: Line['pieces'], w: number, size: number, asc: number }} Run */
+
+/** @type {(run: Run, atom: Atom) => void} */
+let growPiece = (run, atom) => {
+  let atomWidth = width(atom.font, atom.text, atom.size);
+  run.w += atomWidth;
+  if (atom.size > run.size) run.size = atom.size;
+  let atomAsc = ascOf(atom.font, atom.size);
+  if (atomAsc > run.asc) run.asc = atomAsc;
+  mergeAtom(run.pieces, atom, atomWidth);
+};
+
+/** @type {(state: Wrap, run: Run) => void} */
+let finish = (state, run) => {
+  if (!run.size) run.size = state.base;
+  // No `asc` fallback: a run with no atoms is a blank line, and an ascender
+  // only places pieces. `drawLine` loops over none and `decorateLine` skips a
+  // line with no width, so a measured one would be a face lookup nothing reads.
+  state.lines.push({
+    pieces: run.pieces,
+    w: run.w,
+    h: LEAD * run.size,
+    size: run.size,
+    asc: run.asc,
+  });
+  state.cur = [];
+  state.w = 0;
+};
+
+// `force` keeps deliberately blank lines (hard breaks, an empty value);
+// a word-overflow close passes false so a line of pure trimmed spaces
+// vanishes instead of becoming a phantom line.
+/** @type {(state: Wrap, force?: boolean) => void} */
+let emit = (state, force = true) => {
+  trimEnd(state.cur);
+  if (!force && !state.cur.length) {
+    state.w = 0;
+    return;
+  }
+  /** @type {Run} */
+  let run = { pieces: [], w: 0, size: 0, asc: 0 };
+  for (let atom of state.cur) growPiece(run, atom);
+  finish(state, run);
+};
+
+/** @type {(atom: Atom, rest: string[], avail: number) => number} */
+let fitChars = (atom, rest, avail) => {
+  let n = 1;
+  while (n < rest.length) {
+    let longer = rest.slice(0, n + 1).join("");
+    if (width(atom.font, longer, atom.size) > avail) break;
+    n++;
+  }
+  return n;
+};
+
+/** @type {(state: Wrap, atom: Atom, rest: string[], avail: number) => string[]} */
+let takeChunk = (state, atom, rest, avail) => {
+  let n = fitChars(atom, rest, avail);
+  let take = rest.slice(0, n).join("");
+  state.cur.push({ ...atom, text: take });
+  state.w = width(atom.font, take, atom.size);
+  return rest.slice(n);
+};
+
+// An over-wide word alone on its line breaks by character. Both callers
+// enter with the line empty, and `emit()` empties it again between
+// chunks, so each chunk appends to a bare line. The final chunk stays in
+// `cur` (with `w` set) instead of closing, so following atoms may join its
+// line. Split by code point, so an astral character is never halved.
+/** @type {(state: Wrap, atom: Atom, avail: number) => void} */
+let chunk = (state, atom, avail) => {
+  // Slicing is per code point throughout this module — `no-misused-spread`
+  // is warning about the grapheme clusters no base-14 face can encode.
+  // oxlint-disable-next-line typescript/no-misused-spread
+  let rest = [...atom.text];
+  while (rest.length) {
+    rest = takeChunk(state, atom, rest, avail);
+    if (rest.length) emit(state);
+  }
+};
+
+/** @type {(atom: Atom, atomWidth: number, avail: number) => boolean} */
+let isWide = (atom, atomWidth, avail) => {
+  // oxlint-disable-next-line typescript/no-misused-spread
+  return atomWidth > avail && [...atom.text].length > 1 && !atom.space;
+};
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number, avail: number) => boolean} */
+let canFit = (state, atom, atomWidth, avail) =>
+  state.w + atomWidth <= avail || !state.cur.length || atom.space;
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number) => void} */
+let append = (state, atom, atomWidth) => {
+  state.cur.push(atom);
+  state.w += atomWidth;
+};
+
+/** @type {(state: Wrap, atom: Atom, atomWidth: number, avail: number, wide: boolean) => void} */
+let overflow = (state, atom, atomWidth, avail, wide) => {
+  emit(state, false);
+  if (atom.space) return;
+  if (wide) chunk(state, atom, avail);
+  else append(state, atom, atomWidth);
+};
+
+/** @type {(state: Wrap, wide: boolean) => boolean} */
+let startWide = (state, wide) => !state.cur.length && wide;
+
+/** @type {(state: Wrap, atom: Atom, avail: number) => void} */
+let placeAtom = (state, atom, avail) => {
+  if (atom.hard) return emit(state);
+  let atomWidth = width(atom.font, atom.text, atom.size);
+  let wide = isWide(atom, atomWidth, avail);
+  if (!canFit(state, atom, atomWidth, avail)) return overflow(state, atom, atomWidth, avail, wide);
+  if (startWide(state, wide)) return chunk(state, atom, avail);
+  append(state, atom, atomWidth);
+};
+
+// Greedy wrap against `avail`: spaces never start a line, an over-wide word
+// 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 {Wrap} */
+  let state = { cur: [], w: 0, lines: [], base: size };
+  for (let atom of list) placeAtom(state, atom, avail);
+  emit(state);
+  return state.lines;
+};
+
+// Stamp cell-level decorations onto every wrapped fragment. Measurement does
+// not need them; drawing does, and wrapping must not lose them.
+/** @type {(line: Line, underline: boolean, strikethrough: boolean) => void} */
+let stamp = (line, underline, strikethrough) => {
+  if (underline) line.underline = true;
+  if (strikethrough) line.strikethrough = true;
+};
+
+/** @type {(lines: Line[], style: any) => Line[]} */
+let dress = (lines, style) => {
+  if (!dressed(style)) return lines;
+  for (let line of lines) stamp(line, !!style.underline, !!style.strikethrough);
+  return lines;
+};
+
+/** @type {(lines: Line[]) => number} */
+let heightOf = (lines) => lines.reduce((total, line) => total + line.h, 0);
+
+export { atoms, dress, heightOf, wrap };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@quario/layout",
+  "version": "0.1.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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/layout"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "test:browser": "node test/browser/setup.js",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
+    "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
+  },
+  "dependencies": {
+    "@pdf-lib/standard-fonts": "^1.0.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@pdf-lib/fontkit": "^1.1.1",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "quario": "^0.4.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "@pdf-lib/fontkit": "^1.1.1",
+    "quario": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@pdf-lib/fontkit": {
+      "optional": true
+    }
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "ignore": [
+        "quario",
+        "@pdf-lib/standard-fonts"
+      ],
+      "limit": "12 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}