@quario/html 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @quario/html
 
+## 0.9.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.8.0
 
 ### Minor Changes

package/README.md

@@ -69,7 +69,8 @@ in your own page shell and stylesheet.
 
 ### `html(options?)`
 
-The target factory returns the target you pass to `render`.
+The target factory takes this target's host options, validates them at the call, and returns
+the target you pass to `render`. The factory refuses an option it does not know. It throws a `TypeError` at the call for an unknown key. It throws one also for a key with a value of the wrong type.
 `report()` compiles once and `report.render(html(), data)` resolves the fragment. Compile at
 startup and render per request. Definition problems throw at `report()`, at compile time.
 
@@ -77,8 +78,8 @@ Two options. `{ paths: true }` stamps `data-q-path="<schema path>"` on each elem
 carries one (items, images, group containers, the table and its cells), mapping rendered output
 back to the definition behind it. Off by default. `{ fonts }` maps a declared `family` name to the
 CSS `font-family` value it should emit — a custom property, a font stack, a quoted name —
-consulted before the three built-in generics; names match case-insensitively, and a value holding
-`;` or `}` is rejected when the target is constructed:
+consulted before the three built-in generics. Names match case-insensitively, and the factory
+rejects a value holding `;` or `}` when it constructs the target:
 
 ```js
 html({ fonts: { "Instrument Sans": "var(--font-instrument-sans)", mono: "var(--font-ibm-plex-mono)" } });
@@ -95,25 +96,25 @@ report.stream(data); // the raw event generator, if you want events instead
 ```
 
 Engine-level options (`query` budgets, the license key) live on the instance
-(`quario({ query, license })`); see the [engine README](https://www.npmjs.com/package/quario).
+(`quario({ query, license })`). See the [engine README](https://www.npmjs.com/package/quario).
 
-Rendering is asynchronous and hands the loop back between batches, so a large report never blocks the
-host. Compilation stays synchronous; render-time failures reject with the same located errors.
+Rendering is asynchronous and returns the loop between batches, so a large report never blocks the
+host. Compilation stays synchronous. Render-time failures reject with the same located errors.
 
 ## Output contract
 
 These classes are the contract host CSS targets. They are stable, and changing them is a breaking
 change.
 
-| Emits                                              | For                                                                                                                                                                                                                                                                      |
-| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                                                                  |
-| `<div class="q-item q-<role>">`                    | Every item. Roles: `q-report-header`, `q-empty`, `q-group-header`, `q-detail`, `q-group-footer`, `q-report-footer`                                                                                                                                                       |
-| `<div class="q-group" data-group="name">`          | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` when the group declares `break: "page"` or `reset: "page"`                                                                                                                          |
-| `<table class="q-table">`                          | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` around the total rows the walk emits — none when `total` is absent or every row of it is hidden. A spanning cell carries `colspan`                                                                   |
-| `<div class="q-item q-image q-<role>">`            | Each image item, holding one `<img>` whose `src` is a base64 `data:` URI of the event's bytes and whose `width`/`height` are the picture's natural size; `fit` sets `max-width:100%` or `width:100%` on it, paired with `height:auto`, and the rendered `alt` is escaped |
-| `<div class="q-columns" style="column-count:<n>">` | The content between a node's own bands when it declares `columns`: on the root, the body between report header and footer; on a group, inside that instance's `q-group`                                                                                                  |
-| `<div class="q-split q-<role>">`                   | Each split, carrying inline `display:flex`; its slots are `<div class="q-slot">` carrying inline `display:grid` and their share (a slot's `valign` as `align-content`), each holding the slot item's ordinary container                                                  |
+| Emits                                              | For                                                                                                                                                                                                                                                                        |
+| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                                                                    |
+| `<div class="q-item q-<role>">`                    | Every item. Roles: `q-report-header`, `q-empty`, `q-group-header`, `q-detail`, `q-group-footer`, `q-report-footer`                                                                                                                                                         |
+| `<div class="q-group" data-group="name">`          | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` when the group declares `break: "page"` or `reset: "page"`                                                                                                                            |
+| `<table class="q-table">`                          | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` around the total rows the walk emits. No `tfoot` when `total` is absent or every row of it is hidden. A spanning cell carries `colspan`                                                                |
+| `<div class="q-item q-image q-<role>">`            | Each image item, holding one `<img>`. Its `src` is a base64 `data:` URI of the event's bytes, and its `width`/`height` are the picture's natural size. `fit` sets `max-width:100%` or `width:100%` on it, paired with `height:auto`. The target escapes the rendered `alt` |
+| `<div class="q-columns" style="column-count:<n>">` | The content between a node's own bands when it declares `columns`. On the root, that is the body between report header and footer. On a group, it is inside that instance's `q-group`                                                                                      |
+| `<div class="q-split q-<role>">`                   | Each split, carrying inline `display:flex`. Its slots are `<div class="q-slot">` carrying inline `display:grid` and their share (a slot's `valign` as `align-content`), each holding the slot item's ordinary container                                                    |
 
 A column `width` becomes an inline `width:<n>%` on its `<col>`. A row's `style` lands on its `<tr>`, except the box, which the engine has already resolved onto the cells (each `<td>` carries `box-sizing:border-box`). The classes above belong to this
 target. The schema never speaks in CSS. Displaying a fragment that contains images under a Content
@@ -123,15 +124,15 @@ Security Policy needs `img-src data:` (see
 Style declarations map to inline CSS (`bold` → `font-weight:bold` or `font-weight:normal`, `size` → `font-size:<n>pt`,
 `family: "mono"` → `font-family:monospace`, …). Occupy-a-line and newline-as-break are **not** inline: they hang off
 `.q-item` and `.q-table th, td` in [`@quario/html/style.css`](#the-reference-stylesheet), the same way `.q-break`
-honors `break: "page"`. The class is the hook; the rule is a reference default a host overrides on source order.
-A fragment without that sheet still carries the classes and the text, including newlines; it does not occupy or
+honors `break: "page"`. The class is the hook. The rule is a reference default a host overrides on source order.
+A fragment without that sheet still carries the classes and the text, including newlines. It does not occupy or
 break until some stylesheet says so. This target supplies no defaults in the markup: no weight or size per band
 role, no leading, no padding, no spacing between bands, no borders. An inline `style` attribute would beat yours
-in the cascade and force `!important` on you; the defaults and the honor rules ship as an ordinary stylesheet
+in the cascade and force `!important` on you. The defaults and the honor rules ship as an ordinary stylesheet
 instead. The PDF and XLSX targets carry theirs built in, because their consumers have no stylesheet. An empty
 row set still emits the table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
 
-This target is unpaginated: it ignores schema page bands (page furniture belongs to your print CSS)
+This target paginates nothing: it ignores schema page bands (page furniture belongs to your print CSS)
 and maps `break: "page"` and `reset: "page"` to the `q-break` class. Page columns are laid out:
 a node declaring `columns` wraps the content between its own bands in the `q-columns` container
 above, and the browser flows it.
@@ -144,17 +145,17 @@ with each declaration's fate in the
 
 An unlicensed render opens the fragment with `<div class="q-unlicensed">` holding the wording
 from `report-start.marking` as escaped text. A licensed render emits no badge. The element and its
-position are normative; visual treatment belongs to the host. The shipped stylesheet leaves the
+position are normative. Visual treatment belongs to the host. The shipped stylesheet leaves the
 badge unstyled, because a watermark would escape the fragment's box onto the host page.
 
 ## Escaping
 
-**Every interpolated value is escaped.** `{{{ }}}` is a definition error, so no schema syntax can
-exempt a data value from escaping. Every generated attribute value is escaped too — inline styles, `data-` attributes, `src`, `alt`
-and `colspan`; class names are constants the target owns and never carry data.
+**This target escapes every interpolated value.** `{{{ }}}` is a definition error, so no schema syntax
+can exempt a data value from escaping. It escapes every generated attribute value too — inline styles,
+`data-` attributes, `src`, `alt` and `colspan`. Class names are constants the target owns and never carry data.
 
 Literal template text passes through verbatim as author-controlled markup. A definition is
-trusted configuration. Its _data_ is untrusted, and data can never reach the document unescaped.
+trusted configuration. Its _data_ is not, and data can never reach the document unescaped.
 
 ## Printing to PDF
 
@@ -174,7 +175,7 @@ Host CSS targets these classes:
    `.q-break { break-before: page }` honors the schema's own break hint, and `thead` repeats per
    printed page. Yours adds the page geometry in `@page`, which only you can decide.
 3. Print with a headless browser (`page.pdf()` in Playwright or Puppeteer, page numbers via the
-   footer template) or a Paged-CSS engine (WeasyPrint, Prince; page numbers via `@page` margin
+   footer template) or a Paged-CSS engine (WeasyPrint or Prince, with page numbers via `@page` margin
    boxes).
 
 ### The reference stylesheet
@@ -194,13 +195,13 @@ const css = readFileSync(new URL(import.meta.resolve("@quario/html/style.css")),
 const page = `<!doctype html><html><head><style>${css}</style></head><body>${fragment}</body></html>`;
 ```
 
-Its **selectors** are contract; its **rules** are not. It is a reference default meant to be
+Its **selectors** are contract. Its **rules** are not. It is a reference default meant to be
 overridden. Every rule is ordinary specificity, so your own stylesheet loaded after it wins
 without `!important` anywhere. Link nothing at all and you get unstyled markup.
 
 Two things it leaves to you: `@page` geometry and body type, which only a host can decide, and
 any watermark treatment of `.q-unlicensed`, left as plain text here because `position: fixed`
-would paint over your whole page. `example/print.css` in the repository is a host's half showing
+would paint over your whole page. `example/print.css` in the repository is a host's half that does
 both, and `example/print.js` is the complete pipeline.
 
 ## Documentation
@@ -212,10 +213,10 @@ specification of what a report may declare, and
 
 ## License
 
-Commercial software with readable source. Free, unlimited, watermarked evaluation; per-developer
-licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
+Commercial software with readable source. Evaluation is free, unlimited, and watermarked.
+Per-developer licenses at [getquario.com](https://getquario.com). See the bundled LICENSE.
 
-Pass your license key once, on the instance; it is verified offline:
+Pass your license key once, on the instance. quario verifies it offline:
 
 ```js
 const q = quario({ license: "quario_..." });

package/lib/index.d.ts

@@ -1,10 +1,16 @@
 import type { Target } from "quario";
 
+/**
+ * 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 HtmlOptions {
   /**
    * Emit `data-q-path` on each element whose event carries a schema `path`,
    * mapping rendered output back to the definition behind it — the editor's
-   * selection seam. Off by default.
+   * selection seam. Off by default, and a value that is neither `true` nor
+   * `false` throws from `html()` rather than reading as on.
    */
   paths?: boolean;
   /**

package/lib/index.js

@@ -9,7 +9,7 @@
  * never carries markup-escaped text.
  */
 
-import { display, format, isReportBand, styledRuns, text, walk } from "quario";
+import { display, format, hostOptions, isReportBand, styledRuns, text, walk } from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = {
@@ -112,16 +112,30 @@ let OWN = new Set(["group-header", "group-footer"]);
 // too: one option, one message shape.
 /** @type {(path: string, value: any) => string} */
 let cssValue = (path, value) => {
-  if (typeof value !== "string" || !value) throw Error(path + ": expected a CSS font-family value");
-  if (UNSAFE.test(value)) throw Error(path + ": cannot contain ';' or '}'");
+  if (typeof value !== "string" || !value)
+    throw TypeError(path + ": expected a CSS font-family value");
+  if (UNSAFE.test(value)) throw TypeError(path + ": cannot contain ';' or '}'");
   return value;
 };
 
+// A flag rather than anything truthy: `html({ paths: "no" })` reads as yes
+// under a truthiness test, which is the opposite of what the host wrote
+// (`docs/adr/0072`).
+/** @type {(paths: any) => boolean} */
+let stamping = (paths) => {
+  if (paths != null && typeof paths !== "boolean")
+    throw TypeError("options.paths: expected true or false");
+  return Boolean(paths);
+};
+
 /** @type {(fonts: any) => Record<string, string>} */
 let mapping = (fonts) => {
   if (fonts == null) return {};
-  if (typeof fonts !== "object")
-    throw Error("options.fonts: expected an object of family names to CSS values");
+  // A record of family names, so the key set is open and `hostOptions` is the
+  // wrong tool -- but an array is a `typeof "object"` that would name families
+  // 0, 1, 2, so it is refused here.
+  if (typeof fonts !== "object" || Array.isArray(fonts))
+    throw TypeError("options.fonts: expected an object of family names to CSS values");
   return Object.fromEntries(
     Object.entries(fonts).map(([name, value]) => [
       name.toLowerCase(),
@@ -368,7 +382,8 @@ let cells = (list, tag, attrs, intl, markup) =>
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function html(options) {
-  let mark = options?.paths ? pathAttr : () => "";
+  hostOptions(options, ["paths", "fonts"], "options");
+  let mark = stamping(options?.paths) ? pathAttr : () => "";
   // The factory's verdict, like `mark`: the mapping is validated once, here.
   let { attr: styleAttr, map: fontMap } = styling(options?.fonts);
   // A cell's markup, bound to this target's font table once.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/html",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The HTML render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -39,12 +39,12 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.8.0",
+    "quario": "^0.9.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.8.0"
+    "quario": "^0.9.0"
   },
   "size-limit": [
     {