quario 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -7,6 +7,515 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-09-07
+
+### Added
+
+- **Styled runs.** Bold a word, colour a phrase, or format one value inside a
+  sentence, and have it survive into the PDF and the spreadsheet — not only the
+  HTML, which was the only place `<b>` in a template ever meant anything. A run
+  carries the inline declarations only: no padding, borders or spacing, which
+  belong to a whole line or block.
+
+  A cell's tokens carry a run's resolved style on the tokens it covers, and
+  `styledRuns(tokens)` groups them back out — the same rule every built-in
+  target reads them through, so a custom target cannot drift from them.
+  `RUN_STYLE_NAMES` is the inline half of the vocabulary as a list, beside
+  `STYLE_NAMES`, for a tool that offers an author what a run may wear.
+
+- **`plan()` now reports declarations that nothing will read.** A definition can
+  be perfectly valid and still say something the engine quietly drops, and
+  until now the only way to find out was to notice the output was wrong.
+  `plan()` returns a `warnings` list beside `problems` — same shape, same
+  document order, one entry per declaration — and it currently catches three:
+
+  - a `format` on a cell whose value can never present a single interpolation —
+    `"Due {{ due }}"` under `format: "date"` — which the engine leaves unread;
+  - a `currency` on a cell whose `format` is not `"currency"`, which the engine
+    reads only under that kind and otherwise ignores, so the cell renders in
+    the instance's currency and the code you wrote does nothing;
+  - a table where every column declares a `width` and the widths total under
+    100, which leaves the trailing share of the table unused — usually a column
+    edited down without its neighbours being adjusted.
+
+  `problems` is unchanged and still fatal: a definition with problems compiles
+  to nothing, while one carrying only warnings compiles and renders exactly as
+  before. Hosts that ignore the new field are unaffected, and `validate()` is
+  untouched.
+
+  Warnings are advisory and deliberately incomplete — they catch what can be
+  seen in the definition alone, without data, so a quiet `warnings` list is not
+  a promise that every declaration will be read.
+
+### Changed
+
+- **A `format` declaration now needs one value to speak about, and a cell can
+  give it one.** Previously a `format` on a cell reached every interpolation in
+  it and skipped the literal text between them, which meant
+  `"{{ amount }} of {{ quantity }}"` under `format: "currency"` rendered the
+  quantity as money too — and the page and the spreadsheet disagreed about it,
+  the page formatting inside a sentence where the sheet did not.
+
+  A cell `value` may now be a list of **styled runs** —
+  `{ "value": "…", "style": { … } }` — each with its own declarations, and
+  `format` applies to a run holding a single interpolation.
+
+  **What changes in an existing report:** a cell that mixes text and an
+  interpolation under a `format` stops presenting that value and renders it
+  plainly, in every target. `"Due {{ due }}"` with `format: "date"` was
+  `Due 14 Aug 2026` on the page and `Due 2026-08-14` in the sheet; it is now
+  the plain form in both. To restore it, split the value and leave the
+  declaration where it is:
+
+  ```jsonc
+  {
+    "value": [{ "value": "Due " }, { "value": "{{ due }}" }],
+    "style": { "format": "date" }
+  }
+  ```
+
+  A cell's `format` reaches its runs, so nothing moves and nothing is declared
+  twice. `plan()` reports the cells this affects wherever it can see them
+  without data.
+
+### Fixed
+
+- **`round`, `floor` and `ceil` reuse their formatters instead of rebuilding
+  one per call.** The three reach the decimal you wrote through `Intl`, and
+  each call built a fresh formatter to do it — so a detail column of
+  `{{ round(@.qty * @.price, 2) }}` paid for one per row. A hundred-thousand
+  row report with two such columns drained in 3.5 s; it now drains in 0.2 s.
+  Every answer is the value it was before: the rounding mode and the digit
+  count are both part of what a reused formatter is found by, so no call can
+  be handed one built for another.
+
+- **`round`, `floor` and `ceil` name themselves when they refuse an `n`.** All
+  three threw `n must be a number from 0 to 100`, so a cell calling more than
+  one was told how it failed and never which call; the message now opens with
+  the function, as a reducer's already did. The located path still names the
+  cell — one cell holds as many calls as you write, which is the whole reason
+  the name is worth having.
+
+  **An `n` that cannot be read as a number at all now gets the same answer.**
+  A `BigInt` or a `Symbol` reaching `n` from render data used to surface the
+  runtime's own `Cannot convert a BigInt value to a number`, and an object
+  carrying a throwing `valueOf` surfaced whatever it threw — each located at
+  the cell but naming neither the function nor anything an author could act
+  on. All of them are now the same refusal.
+
+- **`isDiagnostic` is documented for what it actually answers.** The README
+  said it was true for "one of the stack's located errors: quario's own, or one
+  thrown directly by xprsn, sjabloon, or padvinder", and its example read a
+  `false` as "one of your own functions failed". Only an engine's own error is
+  a diagnostic: quario's verdicts on a document — an unknown reducer, a
+  misused inline reducer, image bytes it will not vouch for — are located just
+  the same and are not diagnostics, so a host following that example rethrew
+  report faults as its own. Nothing about the guard changes; it never behaved
+  the way the page described.
+
+- **A misused inline reducer says what it is, instead of how it folds.**
+  `{{ min(1, 2) }}` — the two-argument scalar `min` quario does not have —
+  failed at the cell with `(rows || []).map is not a function`, the fold's own
+  internals, naming neither the reducer nor the mistake. It now reads
+  `min is a reducer over an array, not a scalar function; got a number`, and a
+  second argument that is not a lambda says so in the same words rather than
+  reaching a host as `of is not a function`. Register a function of your own to
+  shadow a built-in reducer when a report needs the scalar.
+
+  **Two reducers used to answer instead of failing**, each reading a `length`
+  off a value that is not a collection: `count('ab')` presented `2` — a
+  string's own length, folded as if it were a count of rows — while `count(1)`
+  and `avg(1, 2)` presented nothing at all. All three are now the same located
+  error. A reducer over an **absent** array is unchanged and still not a
+  mistake: `sum(@.lines)` on a row carrying no lines is `0`, exactly as an
+  empty array gives.
+
+## [0.6.0] - 2026-09-07
+
+### Added
+
+- **`imageError(path, said, cause)`**, the mint a render target raises an image
+  failure through. The engine vouches for an image's magic numbers and no
+  further, so every failure past them belongs to whichever target was sizing or
+  embedding the file — and each was wording it its own way. This names the item
+  that asked for the bytes and keeps the failing class and message behind it,
+  so one report reads the same however it is rendered. It is not a diagnostic:
+  `isDiagnostic` does not answer for one.
+
+- **Formatted cells render dramatically faster.** The engine built a fresh
+  `Intl` formatter for every presented cell and now keeps them, keyed on
+  everything a formatter is built from — the kind, the locale, the digit count,
+  the currency code, and for a date its form and timezone. A report of a
+  hundred thousand formatted cells in mixed currencies went from 3.2 s to
+  0.2 s rendering to HTML. Nothing about what a cell presents changes.
+
+  The store is bounded and empties past its bound rather than growing, so a
+  report presenting an unusual number of distinct formats costs what it always
+  did and never a formatter belonging to another cell.
+
+- **`format` takes a digit count, and a date takes a form.** The declaration is
+  still a closed kind, and now the kind may carry the one modifier it
+  understands: `number`, `percent` and `currency` take `digits`, and `date`
+  takes `form`.
+
+  ```jsonc
+  { "header": "Rate",  "value": "{{ @.rate }}",
+    "style": { "format": { "kind": "percent", "digits": 3 } } }
+  { "header": "Total", "value": "{{ @.amt }}",
+    "style": { "format": { "kind": "currency", "digits": 0 }, "currency": "EUR" } }
+  { "header": "Due",   "value": "{{ @.due }}",
+    "style": { "format": { "kind": "date", "form": "long" } } }
+  ```
+
+  The bare kind stays the shorthand — `"number"` means
+  `{ "kind": "number" }` — so no existing declaration has to change.
+
+  `digits` is a whole number from 0 to 20 and overrides the count the kind
+  would otherwise present, **a currency's minor units included**: the example
+  above shows `€1,235` on the page and builds `"EUR"#,##0` in the worksheet.
+  The minor units remain the default, so a JPY cell still shows no decimals
+  beside a EUR one that shows two.
+
+  On `percent`, `digits` counts the places of the **presented percentage**, not
+  of the stored fraction: `digits: 2` on `0.12345` gives `12.35%`. Making the
+  stored value agree still takes `round(x, 4)` — the two count different
+  things, a factor of 100 apart.
+
+  `form` is one of `short`, `medium`, `long`, `full`. It is honoured exactly in
+  HTML and PDF, and **approximated in the worksheet**: a sheet date is a real
+  typed date its reader re-presents, so the shape is yours while the language a
+  month or weekday name is spelled in follows whoever opens the file. Pinning
+  that would stop the sheet reading naturally for its reader.
+
+  A modifier a kind does not understand is a definition error naming the cell —
+  `{ "kind": "date", "digits": 2 }` fails, as does a `digits` outside 0 to 20.
+  `format` layers whole: a cell that names it restates the whole declaration, so
+  naming a kind again resets the modifier. Only the whole declaration may be an
+  `=` expression; a computed count is written
+  `"={'kind':'number','digits':@.dp}"`. Custom `#,##0.00` patterns still belong
+  in `funcs`, and a fraction-digit count no longer needs one.
+
+- **`sort` is stable**: rows whose keys compare equal keep the order they
+  arrived in. The engine has always sorted this way; the promise is new.
+
+- `currencyOf(style, options)` joins the package's exports beside `format()`.
+  It answers which currency code a cell wears — its own when it declares one,
+  else the instance default — for a target that needs the code itself rather
+  than presented text. A cell that declared a code the engine could not accept
+  carries `style.currency` as `null`, so `style.currency ?? yourDefault` is the
+  wrong spelling and this helper is the right one.
+
+- **A cell may name its own currency.** `currency` is a new style declaration
+  beside `format` — a three-letter ISO 4217 code saying what a money cell is
+  denominated in.
+
+  ```jsonc
+  { "header": "Amount", "value": "{{ @.amt }}",
+    "style": { "format": "currency", "currency": "=@.ccy" } }
+  ```
+
+  Until now the code lived only on the instance, so a report whose rows arrive
+  in different currencies — a revenue listing, a statement, an outstanding-
+  invoices table — had to format through `funcs`, and that costs the value: a
+  formatter returns a string, so the cell leaves the typed seam and the
+  worksheet gets text with no number format. A declared code keeps the number.
+
+  The cell's own code beats the instance's, which stays the default for
+  documents that only ever hold one denomination. Locale and timezone do not
+  follow it into the document: a locale describes the reader, while a currency
+  code describes the value. The declaration takes an expression like any other,
+  so a total under a group keyed by currency reads `"=byCcy.key"`. It shares
+  `format`'s sites exactly — text items, column cells, headers and totals, and
+  a column's own `style.currency` declares an amount column once — and, like
+  `format`, it is refused on an image, on `row.style` and on the report
+  default. It is unread without `format: "currency"`.
+
+  A literal that is not three uppercase letters is a definition error. An
+  expression that resolves to something else stays lenient, and the cell then
+  renders as plain display text: it does **not** fall back to the instance's
+  currency, because labelling a figure in a denomination nobody named is worse
+  than not formatting it.
+
+- **`round`, `floor`, `ceil` and `abs` are callable from any expression**,
+  without registering anything. `round(x, n)` gives `x` to `n` decimal places;
+  `n` defaults to 0 and must be a number from 0 to 100; a fraction in it
+  truncates. This is the lever a report needs when arithmetic across exact values lands on an inexact one:
+  a receipt whose `{{ $.subtotal + $.vatLow + $.vatHigh }}` computes
+  `83.75999999999999` writes `83.76` once the sum is wrapped in `round(…, 2)`.
+  It matters in the two targets that keep the number rather than presenting it
+  — the workbook stores the value, and a CSV field shows it as text with no
+  number format to hide behind. A registered function of the same name still
+  wins, so nothing an existing report does changes.
+
+  They round the **decimal you wrote**, not the binary value it is stored as:
+  `round(2.675, 2)` is `2.68` and `round(0.615, 2)` is `0.62`. Note that a
+  `percent` cell presents its value multiplied by 100, so matching a
+  two-decimal percent display takes `round(x, 4)`. A value that is not a finite
+  number passes through untouched rather than becoming zero; an `n` outside the
+  range is an error naming the cell it came from.
+
+- `split-start` events carry `path`, the split definition's schema path, as
+  `item` and `image` events already do. A consumer can now name the definition
+  behind a split without tracking position.
+
+- `fractionDigits(kind, options)` is exported beside `format()`: how many
+  fraction digits a kind presents, or nothing for a kind that carries no
+  count. It is the table the official targets read, and it is public so a
+  consumer writing its own target presents the same digits they do.
+
+### Changed
+
+- **A `date` cell with no `form` now presents `medium`, not the runtime's own
+  default.** A `date` that names no form used to render whatever the platform's
+  default date format was — under `en-US`, `8/14/2026` — which matched none of
+  the four forms you can now ask for. It renders `Aug 14, 2026` instead, and
+  `14 Aug 2026` under `en-IE`. In the worksheet the number format moves from
+  `yyyy-mm-dd` to `dd mmm yyyy`.
+
+  If you want the old shape back, say so: `{ "kind": "date", "form": "short" }`
+  is the nearest of the four. This is the one change here that moves output
+  under an existing report.
+
+- **`style.format` crosses the event stream resolved, not as authored.** A
+  custom target reading `style.format` now sees `{ kind, digits }` or
+  `{ kind, form }` where it saw a bare string: `"number"` arrives as
+  `{ kind: "number", digits: 2 }` and `"date"` as
+  `{ kind: "date", form: "medium" }`. A `currency` whose code cannot be read
+  arrives as `{ kind: "currency" }` with no count at all, which is the signal
+  to write no number format. Read `style.format.kind` where you read
+  `style.format`, and take the digit count off the declaration rather than
+  computing one.
+
+- **`fractionDigits` takes the whole style.** Its first argument was the kind
+  and is now the style, matching `format()` and `currencyOf()`.
+  `fractionDigits("number")` becomes
+  `fractionDigits({ format: "number" })`. Targets no longer need it at all —
+  the count rides on the declaration the stream carries.
+
+- **`typed()`'s second argument is the resolved declaration.** Pass
+  `style.format` as it arrives on the stream; it reads the kind from the
+  object. The shorthand string is still accepted, and omitting the argument is
+  unchanged.
+
+- **A rejected box value is now dropped from the resolved style rather than
+  carried on it.** A `border*` or `padding*` declaration written as an `=`
+  expression used to cross the render stream with whatever the expression
+  answered, even a value the vocabulary rejects; every other name was already
+  dropped. It is now dropped too, so one rule covers the whole vocabulary and
+  `currency` is its only exception.
+
+  Nothing a report renders changes. A border side is still won whole by the
+  node that names any of its three parts — that is now settled from the
+  declarations rather than from what they resolve to, so a rejected part still
+  cannot hand the node its row's other two. A side left incomplete still
+  contributes nothing rather than becoming a solid black stroke, and a rejected
+  padding still falls to the target's own inset.
+
+  What changes is what a consumer reading the stream itself sees. Where a cell
+  had `style.borderTopColor` holding an unusable value, the key is now absent:
+
+  ```js
+  // before
+  cell.style; // { borderTopWidth: 1, borderTopColor: "2-6-A-2-2" }
+  // after
+  cell.style; // { borderTopWidth: 1 }
+  ```
+
+  Every target in this release already checked such values before reading them
+  and is unaffected. A consumer that inferred border-side ownership from which
+  keys were present should read the declarations instead; one that validates
+  what it reads needs no change.
+
+- **`format()` now takes the cell's resolved `style` instead of its `format`
+  kind.** The signature is `format(value, style, options)`, where it was
+  `format(value, kind, options)`. This is what lets the helper read a cell's own
+  `currency` code alongside the kind. Callers pass one property less:
+
+  ```js
+  // before
+  format(token.value, style?.format, intl);
+  // after
+  format(token.value, style, intl);
+  ```
+
+  A caller holding only a kind wraps it as `{ format: kind }`.
+
+- **A table's `total` is now a block holding its rows**, so what belongs to the
+  totals as a whole can be said once. Before, `total` was the array of rows
+  itself:
+
+  ```jsonc
+  "total": [{ "cells": [...] }, { "cells": [...] }]
+  ```
+
+  Now it is an object whose `rows` is that same array, plus a `style` and a
+  `visible` of its own:
+
+  ```jsonc
+  "total": {
+    "style": { "paddingTop": 0, "paddingBottom": 0 },
+    "rows": [{ "cells": [...] }, { "cells": [...] }]
+  }
+  ```
+
+  The rows themselves are unchanged — still `{ "cells", "style?", "visible?" }`,
+  still covering every column exactly once. A `total` that is still an array is
+  a definition error reading `detail.total: expected an object`, and a `total`
+  with no `rows` reads `detail.total.rows: expected an array`. Total cell paths
+  gain the one segment: `detail.total.rows[r].cells[i]`, which is what a
+  `total-row` cell now carries as its `path` and what a located problem names.
+
+  The block's `style` is the layer below each row's — box under box, every
+  other declaration under the row's own — and takes a total row's vocabulary,
+  the whole style set less flow spacing and `format`. Where the block, a row
+  and a cell all speak, the innermost one that names any of a border side's
+  three keys takes that side whole, exactly as a cell already did over a row;
+  padding layers per name. Exact `false` on the block's `visible` omits the
+  totals entirely: the rows are never evaluated, none of them votes on a
+  width-less column, and the output is what leaving `total` out gives.
+
+  This is why the change earns a break: a table's header row has `detail.header`
+  and its data rows have `detail.row`, but the totals — the one kind whose rows
+  a document writes out one by one — had no level above them, so "these sit at
+  the band's line pitch, not the table's row pitch" had to be spelled on every
+  row. `columns` is unaffected and needs no such block: a declaration reaching
+  every column reaches every data cell, which is what `detail.row`'s style
+  already says from the other side.
+
+- **`table-start` now carries the header row**, instead of a `header` cell on
+  each column that a custom target had to collect for itself. The event's
+  `header` is `{ cells, style? }` — the same shape a `row` or `total-row`
+  event has — where `cells` holds one cell per column no neighbour's `span`
+  covers, so it is shorter than `columns` whenever a header spans. Each header
+  cell carries its column's `path`, as a row cell does; a spanning header takes
+  the first column it covers. What is left on `columns` is the geometry: one
+  entry per column, holding a `width` percentage when the document authored
+  one. Nothing an existing report produces changes in any of the shipped
+  targets — this is the seam between the engine and a target, not the document.
+
+  ```js
+  // before
+  const headers = event.columns
+    .filter((column) => column.header)
+    .map((column) => Object.assign({}, column.header, { path: column.path }));
+  const headerStyle = event.style;
+
+  // after
+  const headers = event.header.cells;
+  const headerStyle = event.header.style;
+  ```
+
+  `columns[i].header`, `columns[i].path` and `table-start.style` are gone. A
+  target that reads only `columns[i].width` is unaffected.
+
+- **`format` now presents a fixed number of fraction digits, and every target
+  presents the same number.** Until now the digits were whatever each edge
+  happened to default to: `format: "number"` showed up to three decimals in
+  HTML and PDF and exactly two in a worksheet, and `format: "percent"` showed
+  none in HTML and PDF against the worksheet's two — so one cell in one
+  document read `12%` in the PDF and `12.35%` in the workbook beside it.
+
+  `number` and `percent` are now **two places, always**, in every target that
+  presents. `currency` is its currency's own minor units, so a JPY amount has
+  none and a BHD amount has three, where every currency previously got two.
+  Author-visible, with no document change:
+
+  | value              | before      | now        |
+  | ------------------ | ----------- | ---------- |
+  | `number` `1000`    | `1,000`     | `1,000.00` |
+  | `number` `0.12345` | `0.123`     | `0.12`     |
+  | `percent` `0.21`   | `21%`       | `21.00%`   |
+  | `currency` JPY     | `¥1,234.57` | `¥1,235`   |
+
+  Only the digit count converges. Grouping separators, a currency symbol's
+  position and a date's shape still follow each target's own conventions, and
+  in a worksheet they follow whoever opens the file. `date` is unchanged.
+  A report that needs different digits formats through `funcs`, as before.
+
+- A `currency` code that is not a readable currency now presents nothing in
+  every target, rather than the worksheet inventing a number format from it
+  while the other targets fell back to the unformatted value.
+
+### Fixed
+
+- **A split slot is typed with the declarations the traversal accepts.**
+  `SplitSlot` reused the band items' style types, so TypeScript refused
+  `valign` on an image slot — legal there, and only there — and admitted
+  `spaceBefore`/`spaceAfter` on a slot, which the engine rejects. Two new
+  exported types, `SlotStyleDeclarations` and `SlotImageStyleDeclarations`,
+  now say what a slot may declare.
+
+- **A page band closure is typed as what it returns.** `PageBandRenderers`
+  declared `header`/`footer` as returning item and image events only, while a
+  split in a page band has always come back as its bracket — `split-start`,
+  one event per slot, `split-end`. The closures now return `PageBandEvent[]`,
+  a new exported union naming all four, so a TypeScript host reading a page
+  band no longer types `role` onto a `split-end` that carries none.
+
+- **A computed style value the schema does not accept now leaves the layer
+  below in place**, which is what the schema has always said it does —
+  "contributes nothing, same as omit". The name is dropped from the resolved
+  style rather than passed on, so no target has to decide what an unreadable
+  value means.
+
+  Before, the value reached each target and they disagreed. A detail item with
+  `"bold": "=@.flag"` over a `1` rendered bold in a PDF and a worksheet but not
+  in HTML. On a report header, where those two targets carry a heavier default
+  of their own, a `0` rendered _not_ bold in both while HTML left the header
+  bold. The same held for every other declaration: a report header whose
+  `"size": "=@.pt"` resolved to `"big"` rendered at 14pt in HTML, at the body
+  size in a PDF, and at no size at all in a worksheet. Now all three keep the
+  layer below in every case, and only a real `false` turns a flag off.
+
+  This covers `family`, `size`, the five flags, `color`, `background`, `align`,
+  `valign`, `format`, `spaceBefore` and `spaceAfter`, and only where the value
+  comes from an `=` expression — a literal has always been checked when the
+  report was compiled. It reaches inside a split too: a slot whose `format`
+  expression resolves to something other than the four kinds now keeps the
+  split's own kind instead of overwriting it.
+
+  Two declarations are deliberately unchanged. A border or padding name is kept
+  rather than dropped, because a node that names any part of a border side
+  takes that side whole from its row — dropping the name would hand the node
+  the row's other two and draw an edge nobody declared. And a `currency` code
+  that is not a code still crosses as `null` rather than disappearing, so a
+  cell that named a denomination is never presented under another one.
+
+- A `format` kind that an `=` expression resolved to the name of a built-in
+  object member — `"toString"`, `"constructor"` — now contributes nothing and
+  the cell falls back to display text, as the documented rule says any
+  unrecognised kind does. Before, such a cell could render `[object Undefined]`.
+  A literal was never affected: it is checked against the four kinds.
+
+- **A pinned report header now refuses a lead on every band that can sit under
+  its box, and only where the document settles which one that is.** When
+  `header` declares a `height`, an authored `spaceBefore` on the first item of
+  the band below the box would push that band off the pin, so it is refused.
+  Which band is below the box was read too narrowly, and which item leads it
+  too eagerly.
+
+  Reports that used to validate and now do not: a lead on the `empty` band's
+  first item, and a lead on a group header below the first one. Both were
+  already refused at render, but only on the render that reached them — an
+  `empty` band's lead detonated the first time a filter emptied the row set,
+  on a report that had validated clean for months. Both are definition errors
+  now, on every render.
+
+  Reports that used to be refused and now validate: a lead on an item that may
+  not appear at all — one whose `visible` is an expression, or an image whose
+  `source` yields nothing. Such an item was blamed as though it always
+  occupied, so a document that renders correctly could not be compiled. The
+  check now stays silent wherever only the data decides which item comes first,
+  and the render refuses it at the moment the answer exists.
+
+  Two smaller repairs come with it. A `spaceBefore` that is not a paintable
+  number — negative, `NaN`, infinite — no longer produces two problems on one
+  key, one telling you to make it `0` and one telling you it is not a valid
+  measurement; only the second is reported, because it is the one that is
+  wrong. And a `split` that leads a band now names itself in the error rather
+  than reporting against the report header, which is a band this rule never
+  covers.
+
 ## [0.5.0] - 2026-09-05
 
 ### Added