@quario/layout 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @quario/layout
 
+## 0.6.0
+
+### Minor Changes
+
+- **Every target factory now refuses an option it does not understand.** An unknown key, a key with
+  a value of the wrong type, or an `options` that is not an object throws a `TypeError` at the
+  factory call, naming the option path — `options.meta.title`, `options.page.size`. `@quario/docx`
+  already behaved this way. `@quario/pdf`, `@quario/html`, `@quario/xlsx` and `@quario/layout` read
+  the keys they knew and ignored the rest, so a typo cost you the option you meant to set with no
+  signal at any point. `csv()` takes no options, and it refuses an argument rather than discarding
+  one.
+
+  The check itself is one thing, so the engine now exports it: `hostOptions` closes a key set and
+  `hostMeta` validates the `{ title, author, subject }` contract the document targets share. A
+  fourth document property is one edit rather than three.
+
+  **What this changes for you.** One options object spread across several targets stops working if
+  any target does not know one of its keys — `const o = { page, fonts, meta }` passed to `pdf(o)`,
+  `html(o)` and `xlsx(o)` is three different key sets. An object holding only what its consumers
+  share is unaffected, so `{ page, fonts }` into both `pdf()` and `layout()` still works.
+  TypeScript does not warn about this: excess-property checking fires on an object literal and not
+  on a variable, so a bag held in a `const` compiles clean and throws when you call the factory.
+
+  Nullish is absence everywhere, at both levels, so `{ meta: config.meta ?? null }` and
+  `{ meta: { title: config.title } }` over a config that carries neither are both fine.
+  `html({ paths })` now takes `true` or `false` rather than anything truthy, so `paths: "no"` throws
+  instead of turning path stamping on. A `fonts` mapping given as an array is refused by
+  `@quario/html` and `@quario/layout` rather than read as families named `0`, `1`, `2`.
+
+  Every host-option failure is now a `TypeError` rather than a plain `Error`. A `catch` that tests
+  `instanceof Error` is unaffected. One that compares the constructor is not.
+
+  `@quario/docx` is relaxed in three places, each of them now accepting what it refused: `meta: null`
+  and `page: null` are absence rather than errors, a property written as `meta: { title: undefined }`
+  is a property you did not write rather than one of the wrong type, and an inherited enumerable key
+  is no longer reported as an option you wrote.
+
+  `@quario/pdf`, `@quario/xlsx` and `@quario/docx` now copy `meta` at the factory call. Mutating the
+  object you passed no longer changes what a configured target writes.
+
+### Patch Changes
+
+- Updated dependencies
+  - quario@0.9.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -2,8 +2,8 @@
 
 **The paged layout of a [quario](https://www.npmjs.com/package/quario) report, as a display
 list.** `layout(options)` is a render target whose output is pages of boxes, text runs, rules
-and images in points — the layout the PDF target writes and the viewer and editor paint on screen,
-so the preview breaks its pages exactly where the document does.
+and images in points. The PDF target writes that layout, and the viewer and editor paint it on
+screen, so the preview breaks its pages exactly where the document does.
 
 You install this package directly only to consume the list yourself. `@quario/pdf`, `@quario/viewer`
 and `@quario/editor` depend on it and run it for you.
@@ -39,11 +39,16 @@ list.pages[0].boxes; // which schema node was drawn where
 ```
 
 Every coordinate is in PostScript points from the page's top-left corner. `list.width` and
-`list.height` are the paper every page is drawn on — a report has one, so a page does not carry its
-own size. A page carries its `{ number, total }`, its ops — `rect`, `line`, `image`, `text` (the string to draw, the face
-it is set in, and — for a built-in family only — the per-character advances the measurer laid it
-out with) and, on an unlicensed render, one `mark` — and its `boxes`, one per schema node drawn,
-named by the node's path.
+`list.height` are the paper every page is drawn on. A report has one paper, so a page does not
+carry its own size.
+
+A page carries:
+
+- its `{ number, total }`,
+- its ops: `rect`, `line`, `image`, and `text`. A `text` op holds the string to draw, the face it
+  uses, and, for a built-in family only, the per-character advances the measurer laid it out
+  with. An unlicensed render adds one `mark` op.
+- its `boxes`, one per schema node drawn, named by the node's path.
 
 ## Options
 
@@ -52,7 +57,7 @@ named by the node's path.
 | `page`  | `{ size: "A4" \| "letter" \| [w, h], margin }` points | A4, 54pt |
 | `fonts` | A font mapping: family name to TrueType bytes         | none     |
 
-They are the pdf target's own `page` and `fonts`: pass the same object to `layout()` and to
+They are the pdf target's own `page` and `fonts`. Pass the same object to `layout()` and to
 `pdf()` and the two agree, because the pdf target runs this layout and paints its list.
 
 ## Painting on a canvas
@@ -70,26 +75,26 @@ hit(page, x, y); // -> { path, x, y, w, h } or null
 ```
 
 `paint` draws a white page and every op in order. Size the canvas to the page before you call it:
-the ops are in the page's own coordinates, so a smaller canvas clips them, and the white is filled
-over the whole canvas. Images are decoded from the bytes on the list —
-no `img-src` grant, no URLs. `hit` answers which schema node was drawn at a point: the smallest box
+the ops are in the page's own coordinates, so a smaller canvas clips them, and `paint` fills the
+white over the whole canvas. `paint` decodes images from the bytes on the list. No `img-src`
+grant, no URLs. `hit` answers which schema node was drawn at a point: the smallest box
 containing it.
 
-Text is drawn in the face the document will use. A family you pass as `fonts` is registered as a
-`FontFace` from your own bytes, and its runs are drawn as the browser shapes them — the same
-shaping the PDF gets from the same file, so ligatures, joined scripts and accents look on screen
-the way they will on paper. Text in the built-in families is drawn character by character at the
-measured advances, because the typeface a browser has for Helvetica, Times or Courier only stands
-in for the one the PDF writes, and without the correction a line would drift as it ran.
+Text is drawn in the face the document will use. `paint` registers a family you pass as `fonts` as
+a `FontFace` from your own bytes, and the browser then shapes its runs. That is the same shaping
+the PDF gets from the same file, so ligatures, joined scripts and accents look on screen the way
+they will on paper. `paint` draws text in the built-in families character by character at the
+measured advances. The typeface a browser has for Helvetica, Times or Courier only stands in for
+the one the PDF writes, and without that correction a line would drift as it ran.
 
 Inside a single run of a family you supply, the preview is not promised to place glyphs exactly
-where the PDF does: both read a glyph's own advance and neither applies the font's GPOS
+where the PDF does. Both read a glyph's own advance and neither applies the font's GPOS
 positioning, so a browser may kern by a fraction more. Where a line breaks, how wide a column is,
 and where a page ends are the layout's — one measurer, so preview and document agree.
 
-`PX_PER_POINT` is how big a point is on screen — 96 dpi over PostScript's 72 — so a surface showing
-a page at 100% sizes its canvas `list.width * PX_PER_POINT` CSS pixels wide and paints at
-`PX_PER_POINT * devicePixelRatio`. Any zoom is a factor on top of that.
+`PX_PER_POINT` is how big a point is on screen — 96 dpi over PostScript's 72. A surface that draws
+a page at 100% therefore sizes its canvas `list.width * PX_PER_POINT` CSS pixels wide and paints
+at `PX_PER_POINT * devicePixelRatio`. Any zoom is a factor on top of that.
 
 ## Documentation
 
@@ -100,5 +105,5 @@ specification of what a report may declare, and
 
 ## License
 
-quario is commercial software; evaluation is free and fully featured, with output marked as
-unlicensed. See [LICENSE](https://getquario.com/license).
+quario is commercial software. Evaluation is free and fully featured, and quario marks its output
+as unlicensed. See [LICENSE](https://getquario.com/license).

package/lib/fonts.js

@@ -165,8 +165,8 @@ let useFontkit = async () => {
 let asFamily = (name, def, at) => {
   let path = at + "." + name;
   if (!def || typeof def !== "object")
-    throw Error(path + ": expected { regular, bold?, italic?, boldItalic? }");
-  if (def.regular == null) throw Error(path + ".regular: required");
+    throw TypeError(path + ": expected { regular, bold?, italic?, boldItalic? }");
+  if (def.regular == null) throw TypeError(path + ".regular: required");
   return path;
 };
 
@@ -279,6 +279,10 @@ export async function loadFonts(custom) {
   return { families };
 }
 
+// An array is a `typeof "object"` whose families would be named 0, 1, 2.
+/** @type {(custom: any) => boolean} */
+let record = (custom) => typeof custom === "object" && !Array.isArray(custom);
+
 /**
  * Check the shape of a host's font mapping without loading a parser.
  *
@@ -295,7 +299,7 @@ export async function loadFonts(custom) {
  */
 export let checkFonts = (custom, at = "options.fonts") => {
   if (custom == null) return;
-  if (typeof custom !== "object") throw Error(at + ": expected a record of families");
+  if (!record(custom)) throw TypeError(at + ": expected a record of families");
   for (let [name, def] of Object.entries(custom)) asFamily(name, def, at);
 };
 

package/lib/index.d.ts

@@ -22,7 +22,11 @@ export interface LayoutFontFamily {
 /** The font mapping: a declared `family` name to the bytes it measures against. */
 export type LayoutFonts = Record<string, LayoutFontFamily>;
 
-/** Host controls, taken and validated at the factory call. */
+/**
+ * Host controls, taken and validated at the factory call: an option this
+ * target does not understand, or one of the wrong type, throws a `TypeError`
+ * there rather than costing the host the option in silence.
+ */
 export interface LayoutOptions {
   page?: LayoutPage;
   /**

package/lib/index.js

@@ -20,7 +20,7 @@
  * 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 { breathe, hostOptions, walk } from "quario";
 import { listing, stamp } from "./canvas.js";
 import { checkFonts, loadFonts } from "./fonts.js";
 import { flow, furniture } from "./layout.js";
@@ -58,6 +58,19 @@ let markPages = async (canvas, marking) => {
   await overPages(canvas, () => canvas.watermark(mark));
 };
 
+// This target's whole option contract, checked at the factory call: the key
+// sets, then the geometry and the font mapping's shape. The `page` key set
+// closes here rather than in `pageBox`, which the two surface elements also
+// call -- a host configures those by assigning DOM properties, and nothing can
+// refuse an unknown one (`docs/adr/0072`).
+/** @type {(options: any) => void} */
+let checkOptions = (options) => {
+  hostOptions(options, ["page", "fonts"], "options");
+  hostOptions(options?.page, ["size", "margin"], "options.page");
+  geometry(options?.page);
+  checkFonts(options?.fonts);
+};
+
 /**
  * The layout target:
  * `quario().report(schema).render(layout({ page }), data)` resolves the
@@ -70,8 +83,7 @@ let markPages = async (canvas, marking) => {
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function layout(options) {
-  geometry(options?.page);
-  checkFonts(options?.fonts);
+  checkOptions(options);
   let custom = options?.fonts;
   /** @type {(stream: any) => (data?: any) => Promise<Layout>} */
   let compile = (stream) => async (data) => {

package/lib/page.js

@@ -23,7 +23,7 @@ let SIZES = /** @type {Record<string, [number, number]>} */ ({
 
 /** @type {(msg: string) => never} */
 let err = (msg) => {
-  throw Error(msg);
+  throw TypeError(msg);
 };
 
 /** @type {(value: number) => boolean} */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/layout",
-  "version": "0.5.0",
+  "version": "0.6.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",
@@ -43,13 +43,13 @@
     "@size-limit/preset-small-lib": "^13.0.3",
     "@types/fontkit": "^2.0.9",
     "fontkit": "^2.0.4",
-    "quario": "^0.8.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
     "fontkit": "^2.0.4",
-    "quario": "^0.8.0"
+    "quario": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "fontkit": {