quario 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,197 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- **`format` is a closed style name.** `number` / `currency` / `percent` /
+  `date` on text items, column cells, headers, and totals. Not images, not
+  `row.style`, not the report default. Locale, currency code, and timezone
+  live on `quario({ locale, currency, timeZone })`. The public `format()`
+  helper is how targets present a kind; a kind on the wrong type contributes
+  nothing (`docs/adr/0041`).
+
+- **The report header may pin a `height` from the page top.** Dual-shaped
+  like `detail`: an item array, or `{ height, items }`. `page.margin` is a
+  document field (one number, all four sides), required with `height` and
+  legal without. Authored `spaceBefore` on the first occupying item of the
+  next band is refused (`docs/adr/0038`).
+
+- **`spaceBefore` / `spaceAfter` return as item flow spacing.** Blank space
+  before or after a band item, in points, including band images and splits as
+  band items. Adjacent gaps add. Table cells, `row.style`, headers, totals,
+  and split slots refuse the names. `spaceBefore` drops at a fresh body page
+  or strip top; page-band items keep it. Leading and inset stay cut
+  (`docs/adr/0037`).
+
+- **Per-side padding and border on the closed style vocabulary.**
+  `paddingTop` / `Right` / `Bottom` / `Left` (points, ≥ 0) and, per side,
+  `border*Width`, `border*Style` (`solid` | `dashed` | `dotted`),
+  `border*Color` (`#rgb` / `#rrggbb`). A border side is all three names or
+  none; width `0` is no stroke; an incomplete literal is a definition error,
+  and an incomplete expression result at render contributes nothing rather
+  than a solid black stroke. The names are legal wherever `background` is,
+  including images, plus `row.style`. The report default still takes only
+  `family` and `size`. Column `%` widths are border-box.
+
+- **`detail.header` is the header-row box.** `{ style }` only, a different
+  path from `columns[i].header`. It crosses the seam as `table-start.style`.
+
+### Changed
+
+- **A table total is N rows.** Before, `total` was one row: a flat cell
+  array or `{ style, cells }`. After, it is absent or a non-empty array of
+  `{ cells, style?, visible? }`. A one-row total is `[{ cells: [...] }]`.
+  `total: []` is a definition error. Paths are `detail.total[r].cells[i]`.
+  The stream yields one `total-row` per emitted row (`docs/adr/0042`).
+
+- **A visible text item occupies a line at its own `size`.** Empty display
+  used to take the report default's leading in PDF and collapse in HTML;
+  `"a\n\nb"` broke in PDF and collapsed to a space in HTML. A visible item
+  now occupies at least one line set in that item's `size`, and a literal
+  newline is a line break, on every target that can show a line. Empty
+  table cells stay contentless for height. This is not a spacing primitive;
+  `visible: false` is still how an item leaves the layout.
+
+## [0.2.0] - 2026-09-01
+
+### Added
+
+- **A report default: one `style` block for the whole document.** A top-level
+  `style` beside `header`/`detail`/`footer` states the typeface a report is set
+  in, so a document with one face names it once instead of on every item, every
+  table column, every header and every total cell. It takes `family` and
+  `size`; any other declaration there is a located definition error, exactly as
+  a text declaration on an image item is. Values are literals or `=`
+  expressions like any other style block's, resolved once per render in report
+  scope.
+
+- **`report-start` carries the resolved report default as `style`.** A
+  report-level fact, never merged into an item's own `style`: an event's
+  `style` stays what the author wrote on that node, and a consumer composes the
+  default itself, once — under its own band-role defaults and under every
+  event's own style. Absent when the report declares none, so a consumer
+  written before this field renders in its own baseline exactly as it did.
+
+- **An `uppercase` style declaration.** A boolean beside `bold` and `italic`,
+  literal or an `=` expression, for the capitalised column labels business
+  forms are usually set with. It is capitals, not small caps — real small caps
+  need a font feature the PDF target's built-in faces cannot supply, so the
+  declaration promises only what every target can draw. Image items keep
+  refusing it, as they refuse every text declaration.
+
+- **A `split` item places values across the line instead of down the band.**
+  The invoice header's "seller left, customer right", which a band could not
+  say before. `{ "type": "split", "slots": [...] }` takes two or more slots,
+  each an ordinary `text` or `image` item plus an optional `width` percentage
+  under the same rules a table column's obeys; width-less slots divide what
+  the sized ones leave, evenly. A split is always the full content width and
+  never nests — it says what sits beside what, never where anything is — and
+  a slot that renders nothing keeps its width, so a line's geometry never
+  moves with the data. Splits may appear in every item array except table and
+  total cells.
+
+- **`split-start` / `split-end` bracket a split's slots on the event stream.**
+  `split-start` carries the slot geometry, then one ordinary `item` or `image`
+  event per slot in order, then `split-end`. Existing consumers need no
+  change: the walk driver's missing-handler rule means a target that ignores
+  the bracket still receives the slot items and renders them stacked.
+
+- **`quario().plan(schema, funcs?)` hands the whole traversal over at once.**
+  Returns `{ report, problems, anchors }` from one descent: the compiled
+  report (`null` while the document has problems), every problem as
+  `{ path, source?, message, diagnostic? }`, and a map from each compiled
+  source's schema path to the anchors and group handles it reads. A host that
+  validates and renders per edit — an editor — pays one traversal instead of
+  two, can point at a problem in its own UI without parsing a message apart,
+  and can tell where a node may safely move. `validate()` is unchanged: its
+  strings are those problems' `message` fields.
+- **Every problem keeps its own located diagnostic.** `validate()` retained
+  `start`/`end` offsets on at most one problem per document; the structured
+  list carries each problem's own, so a consumer can underline the offending
+  character in every faulty expression rather than only the first.
+- **Events name the definition behind them.** `item`, `image` and
+  `group-start` events carry `path`, the schema path of the node that
+  produced them; `table-start` carries `detail` and its columns their own,
+  and every table cell carries its column definition's path (a total cell its
+  `detail.total[i]` entry). Rows carry no identity — a row is data, not
+  schema. Additive: a consumer that ignores the field is unaffected.
+- **`display(value)` joins one value the way `text()` does.** The scalar
+  display rule behind the token join, re-exported beside `text()` so a stream
+  consumer that stringifies token values itself renders exactly what the
+  official targets render — Dates included.
+
+- **`maxDepth: Infinity` opts a query budget out.** The data query's traversal
+  budgets accept an explicit `Infinity` per key for "this budget, unbounded".
+  The 500-deep default is unchanged — it is now padvinder's own, applied for
+  every consumer rather than added by quario at the seam.
+
+- **Located data-query errors carry padvinder's code and span.** A `data`
+  query that does not parse now surfaces with padvinder's `code` and
+  `start`/`end` offsets into the query you wrote — filter faults included —
+  alongside the band/item path quario already attached. The code names the
+  category of mistake: `PADVINDER_MISSING_ROOT`, `PADVINDER_BAD_SELECTOR`,
+  `PADVINDER_UNCLOSED_BRACKET`, `PADVINDER_BAD_STRING`,
+  `PADVINDER_UNKNOWN_FUNCTION`, or `PADVINDER_SYNTAX` for a path character or
+  filter body that is open-endedly not a query. Traversal budgets exceeded at
+  render time keep `limit`/`actual` and carry no span.
+
+### Changed
+
+- **Cells render straight over the engine scope chain.** A text cell no longer
+  allocates a wrapper scope and an anchor pair per cell per row — quario's
+  chain already binds `$` at the render base and `@` on the detail row, and
+  sjabloon now renders over it as-is. A 4-column stream over a million rows
+  went from 1.7s to 0.5s. No report changes what it renders. Requires
+  sjabloon 0.11.
+
+- **A compiled report's `functions` carry signatures.** Each entry is now
+  `{ name, arity, doc? }` instead of a bare name — `arity` from the function's
+  declared parameter count (or its own numeric `arity` where rest parameters
+  mislead `length`), `doc` from an own `doc` string when it carries one — in
+  the same call-first-seen order. `names` is unchanged. Requires xprsn 0.11
+  and sjabloon 0.11.
+
+- **A bare `Date` renders as ISO 8601 UTC, the same on every machine.**
+  Display text for a `Date` value was `String(date)`, which bakes the
+  rendering host's timezone and locale into the output — so one report
+  produced different bytes on different machines. Every target now renders a
+  valid `Date` as its `toISOString()` form through the one shared display
+  rule; an invalid `Date` keeps its deterministic `Invalid Date` text.
+  Reports that want a formatted date keep using a registered function,
+  exactly as before.
+
+- **A bad literal pattern in the data query is a definition error.** A typo'd
+  I-Regexp written as a string literal in `match()`/`search()` used to
+  produce a plausible empty report with no signal; `report()` and
+  `validate()` now surface it at compile time as a located error, with
+  offsets at the pattern literal in the query. The class and `code` are
+  treffer's — a malformed pattern is a `SyntaxError` with `TREFFER_SYNTAX`,
+  one past treffer's limits a `RangeError` with a `TREFFER_MAX_*` code and
+  `limit`/`actual` — on the same rule that already gives xprsn's codes to a
+  fault in an expression: the engine that decided the fault names it. A
+  pattern that arrives from render data keeps RFC 9535 semantics and still
+  matches nothing at render time. Requires padvinder 0.8.
+
+- **Each engine relocates its own diagnostic.** A located error is now a copy
+  made by the engine that raised it (xprsn, sjabloon, or padvinder), so it
+  carries every field that engine puts on a diagnostic — nothing is lost in
+  quario's re-throw, today or when an engine adds a field — and it still
+  passes that engine's own `isDiagnostic`. Host errors are wrapped as plain
+  errors with no diagnostic metadata, exactly as before. Requires xprsn 0.10,
+  sjabloon 0.9, and padvinder 0.5. No report changes what it renders.
+
+### Fixed
+
+- **A host error cannot pose as the report's diagnostic.** `report()` rethrows
+  the first definition problem's located engine error; it chose that error by
+  probing for a `code` property, so a host error class that stamps `code` on
+  itself in its constructor was rethrown as if the engines had raised it. The
+  choice now goes through the same identity-based authentication as
+  `isDiagnostic`; everything else falls back to a plain `SyntaxError` naming
+  the first problem, as before.
+
 ## [0.1.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -84,11 +84,11 @@ row, an optional `total-row`, and `table-end`.
 | Event          | Carries                                                                                     |
 | -------------- | ------------------------------------------------------------------------------------------- |
 | `report-start` | `params`, resolved report `aggregates`, optional `page` band closures, `columns`, `marking` |
-| `item`         | `role`, `tokens`, optional `style`, `run`                                                   |
-| `image`        | `role`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`          |
-| `group-start`  | `name`, `depth`, `key`, `aggregates`, optional `break`, `reset`, `columns`                  |
+| `item`         | `role`, `path`, `tokens`, optional `style`, `run`                                           |
+| `image`        | `role`, `path`, `bytes`, `format` (`png` \| `jpeg`), `fit`, optional `alt`, `style`, `run`  |
+| `group-start`  | `name`, `depth`, `key`, `aggregates`, `path`, optional `break`, `reset`, `columns`          |
 | `group-end`    | `name`, `depth`                                                                             |
-| `table-start`  | `columns` (each `header`, optional `width`)                                                 |
+| `table-start`  | `path`, `columns` (each `header`, `path`, optional `width`)                                 |
 | `row`          | `cells`, optional `style`, `run`                                                            |
 | `total-row`    | `cells`                                                                                     |
 | `table-end`    | -                                                                                           |
@@ -145,6 +145,21 @@ 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.
 
+### `quario().plan(schema, functions?)`
+
+The one traversal, whole — for hosts that validate and render in a loop, like an editor. Returns
+`{ report, problems, anchors }`: the compiled report (`null` while the document has problems),
+every problem structurally as `{ path, source?, message, diagnostic? }` (the `message` is exactly
+`validate()`'s string, and every problem keeps its own located diagnostic with `start`/`end`
+offsets, not only the first), and `anchors`, mapping each compiled source's schema path to the
+anchors and group handles it reads — the unfiltered complement of `names`.
+
+```js
+const { report, problems, anchors } = quario().plan(schema);
+if (report) await report.render(html(), data);
+else console.error(problems[0].path, problems[0].message);
+```
+
 ### `isDiagnostic(error)`
 
 True when a caught value is one of the stack's located errors: quario's own, or one thrown

package/lib/format.js

@@ -0,0 +1,60 @@
+/**
+ * Present a cell's raw token as `number` / `currency` / `percent` / `date`.
+ * Targets import this instead of each other: the stream keeps the kind on
+ * `style` and the token raw, and HTML/PDF stringify at the edge. A kind on
+ * the wrong type, or on null, contributes nothing — the caller falls back to
+ * `display()`. Invalid locale or currency codes fail the same way.
+ *
+ * Defaults (`en-US`, UTC) are pinned so a PDF without a host locale still
+ * renders the same bytes on every machine (docs/adr/0041, docs/adr/0025).
+ */
+import { finiteDate, finiteNum } from "./stream.js";
+/** @type {(options: any) => string} */
+let localeOf = (options) => options?.locale || "en-US";
+/** @type {(options: any) => string} */
+let zoneOf = (options) => options?.timeZone || "UTC";
+
+/** @type {(value: any, locale: string) => string | undefined} */
+let asNumber = (value, locale) =>
+  finiteNum(value) ? new Intl.NumberFormat(locale).format(value) : undefined;
+/** @type {(value: any, locale: string) => string | undefined} */
+let asPercent = (value, locale) =>
+  finiteNum(value) ? new Intl.NumberFormat(locale, { style: "percent" }).format(value) : undefined;
+/** @type {(options: any) => string | null} */
+let currencyOf = (options) => {
+  let currency = options?.currency;
+  return typeof currency === "string" && currency ? currency : null;
+};
+/** @type {(value: any, locale: string, options: any) => string | undefined} */
+let asMoney = (value, locale, options) => {
+  let currency = currencyOf(options);
+  if (!finiteNum(value) || !currency) return;
+  return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
+};
+/** @type {(value: any, locale: string, options: any) => string | undefined} */
+let asDate = (value, locale, options) =>
+  finiteDate(value)
+    ? new Intl.DateTimeFormat(locale, { timeZone: zoneOf(options) }).format(value)
+    : undefined;
+
+/** @type {Record<string, (value: any, locale: string, options: any) => string | undefined>} */
+let KINDS = { number: asNumber, currency: asMoney, percent: asPercent, date: asDate };
+
+/**
+ * @param {unknown} value The interpolation's pre-stringify token.
+ * @param {unknown} kind A resolved `format` declaration.
+ * @param {{ locale?: string, currency?: string, timeZone?: string } | null} [options]
+ *   The instance's locale, currency code, and timezone.
+ * @returns {string | undefined} The presented text, or nothing when this
+ *   kind does not apply.
+ */
+export function format(value, kind, options) {
+  if (typeof kind !== "string") return;
+  let present = KINDS[kind];
+  if (!present) return;
+  try {
+    return present(value, localeOf(options), options);
+  } catch {
+    return;
+  }
+}