quario 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,170 @@
 # quario
 
+## 0.13.0
+
+### Minor Changes
+
+- A band gains a `grid` item: splits that share one column geometry.
+
+  A statement is twenty lines of a label and an amount, on the same two widths. As splits, each line restated its widths:
+
+  ```jsonc
+  { "type": "split", "slots": [
+    { "type": "text", "value": "Opening", "width": 70 },
+    { "type": "text", "value": "{{ @.opening }}", "width": 30, "style": { "align": "right" } }
+  ] }
+  ```
+
+  A grid states the widths, and each column's style, once:
+
+  ```jsonc
+  {
+    "type": "grid",
+    "columns": [{ "width": 70 }, { "width": 30, "style": { "align": "right" } }],
+    "rows": [
+      { "slots": [{ "type": "text", "value": "Opening" }, { "type": "text", "value": "{{ @.opening }}" }] },
+      {},
+      { "slots": [{ "type": "text", "value": "Total" }, { "type": "text", "value": "{{ @.total }}" }], "style": { "bold": true } }
+    ]
+  }
+  ```
+
+  A row is a split without `type`, and it keeps every rule a split has. A column's `style` is the layer under each of its slots, and a slot's own declarations win. A row that names fewer slots than there are columns leaves the rest empty, so `{}` is a spacer line and a one-slot row is a label-only line.
+
+  Each row reaches a target as the split it is, so the event stream does not change and no target needed an update. No existing report changes.
+
+- The package now ships a JSON Schema of the report document.
+
+  The file is `lib/schema.json`, and the package exports it as `quario/schema.json`. Point `$schema` at the installed copy, and an editor checks the document and shows the documentation for each key:
+
+  ```jsonc
+  { "$schema": "./node_modules/quario/lib/schema.json", "data": "$.orders[*]" }
+  ```
+
+  A report document accepts one new top-level key, `$schema`. Its value must be a string. The engine checks the type and reads nothing else, so a document keeps its `$schema` through an upgrade. Anywhere below the top level, `$schema` stays an unknown key.
+
+  The JSON Schema proves the shape of each value, and `validate()` still proves the document. A document can pass the JSON Schema and fail `validate()`: a rule across two values, a reserved name, or an expression that does not compile. The strict structured-output modes of OpenAI and Anthropic do not accept the file, because a report document leaves most of its keys out.
+
+  The TypeScript declarations are stricter in one place. A parameter's value under `params` is now typed as any JSON value except a plain object. The engine always read a plain object there as a declaration, so a document that the new type refuses was never the document it looked like.
+
+- **A license key has an end date and no start date.** A key covers every version released on or before its `to` date. Before, a key also named a `from` date, and a version released before that date stayed marked. The engine now ignores a `from` in a key. When a key ends before the release date of the installed version, the warning names both dates.
+- A value the runtime has no text form for is now a located render error rather than `[object Object]` in the document.
+
+  A cell reaches its reader through `String(value)`. A plain object, a `Map` and a `Set` have no text form of their own, so that falls back to a tag: `[object Object]`, `[object Map]`, `[object Set]`. A tag lays out, paginates and lands in a worksheet cell, and the document is wrong. A few values have no text form at all, and `String()` throws on them — an object with no prototype, a boxed symbol. The engine now refuses both kinds and names the cell:
+
+  ```
+  detail[0].value [{{ @.address }}]: a value with no text form, which would print as [object Object]
+  ```
+
+  The rule reads the value, not its source, so a registered function's result and a data field answer to it alike. A value that says what it is still prints it: a class with its own `toString`, an array (`[1, 2]` prints `1,2`), a `Date`. An absent read still prints nothing. A computed property is outside the rule, because a group's `by` is an identity rather than text — `by: "=@"` makes each row its own instance — and a `where` and a `visible` are read for truth.
+
+  Every entry in the function registry must be a function. `plan` reports one that is not at `functions.<name>`, where before it raised an unhandled `TypeError` out of `plan` itself at a caller who had only asked a question.
+
+  A report that printed `[object Object]` stops rendering. It was printing a value no reader could use.
+
+- A document may now name its paper and turn it, and its margin may name each side.
+
+  ```jsonc
+  {
+    "page": {
+      "size": "letter",
+      "orientation": "landscape",
+      "margin": { "top": 36, "right": 29, "bottom": 36, "left": 29 }
+    }
+  }
+  ```
+
+  `page.size` takes `"A4"` or `"letter"`. A `[width, height]` pair stays a target option. `page.orientation` takes `"portrait"` or `"landscape"`, and it turns whichever paper is in force. `page.margin` still takes one number for all four sides.
+
+  The rule `page.margin` already followed now covers all three keys. The document's key wins where it declares one, a target option applies where it does not, and both declaring the same key is a render error. `orientation` in a document beside a target's `size` is not both.
+
+  Each target writes the paper: the PDF and the layout draw on it, HTML writes an `@page` size and per-side margin, and DOCX writes `pgSz` with `w:orient` and `pgMar` per side. XLSX writes the paper code, the orientation and each print margin. CSV withdraws all three.
+
+  The capability descriptors gain `page.size` and `page.orientation`, and both are names a document may mark `required`.
+
+  A target's margin error now reads `expected a non-negative number, or { top, right, bottom, left }, that leaves the page room`.
+
+- `params` is now what the report declares it needs, and a render may supply one.
+
+  A bare value under `params` still **is** the parameter's value, so a document of constants reads the way it always did:
+
+  ```jsonc
+  { "params": { "year": 2025, "branded": true } }
+  ```
+
+  A plain object is a **declaration** instead, closed at `default` and `type`:
+
+  ```jsonc
+  {
+    "params": {
+      "year": { "type": "number", "default": 2025 },
+      "region": { "type": "string" }
+    }
+  }
+  ```
+
+  `type` names a JSON kind — `string`, `number`, `boolean`, `array`, `object` — because a parameter is a JSON value. There is no `date` and no `enum`.
+
+  **`default` absent makes the parameter required.** The engine rejects a render that supplies no value for it, before any expression runs. That is the main thing declaring buys: a report that states what it needs hears about it when a render does not bring it.
+
+  A host supplies values as the last argument to `render` and to `stream`:
+
+  ```js
+  await report.render(html(), data, { region: "EU" });
+  ```
+
+  Only a declared key may be supplied, a supplied value answers to the declared `type`, and values stay JSON and deep-frozen — now per render rather than once at compile.
+
+  **One kind of document changes meaning.** The engine reads an object-valued parameter as a declaration, so a document that wrote one for its value wraps it:
+
+  ```jsonc
+  { "params": { "config": { "default": { "retries": 3 } } } }
+  ```
+
+  An empty object is the sharpest case. `{ "config": {} }` now declares a parameter with no default, so every render of that document is refused until one supplies a value, or until the document wraps it.
+
+  Nothing else moves. A bare string, number, boolean or array is untouched.
+
+  A declaration may also carry a `label`, the text a person reads for the parameter. A labelled parameter is one a person supplies, so a host panel shows only those. The engine never renders a label.
+
+  A `null` default beside a `type` makes a typed parameter optional, and a render may then supply `null`:
+
+  ```jsonc
+  { "params": { "branch": { "type": "string", "default": null, "label": "Branch" } } }
+  ```
+
+  A host reads what a document declares from `report.params` and from `plan(...).params`: one frozen `{ name, required, type?, default?, label? }` per parameter, in declaration order. A plan carries them whether or not the document compiled, so an editor can render a panel beside the problems.
+
+## 0.12.0
+
+### Minor Changes
+
+- A registered function may be asynchronous. The engine resolves every such call before the banded walk, in one wave, and the walk itself stays synchronous.
+
+  Write the call as the whole value of a cell in a detail row, and take its arguments from the row:
+
+  ```jsonc
+  { "data": "$.orders[*]", "detail": [{ "type": "text", "value": "{{ customerName(@.customerId) }}" }] }
+  ```
+
+  The engine calls the function once for every row it renders, starts every call together, and waits for all of them before the first event reaches a target. A row that `where` or `take` removed is never fetched. Deduplication and any limit on how many calls run at once belong to the function itself: a report over ten thousand rows starts ten thousand calls.
+
+  Three rules hold. The call is the whole value of a cell, so `{{ lookup(@.id).name }}` and `{{ "#" + lookup(@.id) }}` are errors that name the function and the cell. The arguments come from the row, so a cell that reads no row cannot hold one. And `render()` resolves, while `stream()` reports the call it cannot wait for.
+
+  A function that rejects fails the render with an error that names the function and the cell, and keeps the class the function threw.
+
+### Patch Changes
+
+- **The declarations now refuse what the engine refuses.** Eight style declarations type-checked at nodes the engine rejects them on, so a report that compiled could still fail to render: `valign` on a stacked item, flow spacing on a table cell or a total cell, and `format`, `currency`, `href` and flow spacing on a row box. Each site now states the narrowing the engine has always applied, through four new exported types — `StackedStyleDeclarations`, `CellStyleDeclarations`, `RowStyleDeclarations`, and the `SlotStyleDeclarations` that was already there.
+
+  No document that the engine accepts has stopped type-checking. The narrowing removes only names the engine was already refusing.
+
+  **`SCHEMA.md` now states two keys it always admitted.** The document-shape block never listed `required`, and the group-definition block never listed `collapsed` — the latter while three target sections linked to that section for it, and while the section said a group is collapsible without a field for it. Both are stated now, `collapsed` with the paragraph it never had.
+
+- **The declarations now carry `required`, and a group's `label` and `collapsed`.** `ReportSchema` states `required`, and `Group` states both `label` and `collapsed`. The engine has admitted all three and `SCHEMA.md` specifies them, so a TypeScript author marking a declaration required, naming an instance for navigation, or opening a group shut was told it was an error and had to cast.
+
+  `required` is keyed by a new exported type, `RequirableName`, which spells the same names `REQUIRABLE` carries. A marking no target could answer for is therefore an error where an author writes it, rather than a `plan` problem after the fact — `{ "negative": true }` names a modifier inside `format` rather than a declaration a target answers for, and the compiler now says so. `collapsed` reads `boolean`, because the engine accepts `false` for it as plainly as `true`.
+
 ## 0.11.1
 
 ### Patch Changes

package/README.md

@@ -70,8 +70,8 @@ key verification as `{ licensed, licensee?, id? }`.
 
 ### `report(schema, functions?)`
 
-Compiles a report and returns the compiled report. `stream(data)` is the raw event generator.
-`render(target, data)` takes a self-naming `{ name, compile }` object from a target factory
+Compiles a report and returns the compiled report. `stream(data, params)` is the raw event generator, and `params` are the values this render supplies for what the document declares.
+`render(target, data, params)` takes a self-naming `{ name, compile }` object from a target factory
 (e.g. `html()` from `@quario/html`) or your own.
 
 A render is async: quario awaits key verification before the target sees its first event. A
@@ -209,6 +209,33 @@ validate({ data: "$.o[*]", sort: [{ by: "=@.a", dir: "up" }] });
 `report()` throws on the first problem instead. Validation and compilation share one traversal,
 so `validate()` can never disagree with what `report()` accepts.
 
+### JSON Schema
+
+The package ships a JSON Schema of the report document. Point `$schema` at the installed copy,
+and your editor checks the document and shows the documentation for each key:
+
+```json
+{
+  "$schema": "./node_modules/quario/lib/schema.json",
+  "data": "$.orders[*]",
+  "detail": [{ "type": "text", "value": "{{ @.product }}" }]
+}
+```
+
+The path is relative to the report file. The engine accepts the `$schema` key and does not read
+it.
+
+Code reads the same file through the package export:
+
+```js
+import schema from "quario/schema.json" with { type: "json" };
+```
+
+The JSON Schema proves the shape of each value. It does not replace `validate()`. Rules that
+join two or more values, and every expression and template, stay with `validate()`. Use the
+JSON Schema to constrain what an editor or a model writes. Use `validate()` to accept a
+document.
+
 ### `quario().plan(schema, functions?, { targets }?)`
 
 The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns