quario 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -7,6 +7,144 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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/index.d.ts

@@ -1,4 +1,5 @@
-import type { PadvinderErrorCode, QueryOptions, QueryPath } from "padvinder";
+import type { PadvinderErrorCode, QueryOptions, QueryPath, TrefferErrorCode } from "padvinder";
+import type { XprsnErrorCode, XprsnSignature } from "xprsn";
 import type {
   LiteralToken as SjabloonLiteralToken,
   SjabloonBlock,
@@ -44,6 +45,8 @@ export interface StyleDeclarations {
   italic?: ExpressionValue<boolean>;
   underline?: ExpressionValue<boolean>;
   strikethrough?: ExpressionValue<boolean>;
+  /** Render the text in capitals. Capitals, not small caps. */
+  uppercase?: ExpressionValue<boolean>;
   /** Text color, `#rgb`/`#rrggbb`. */
   color?: ExpressionValue<string>;
   /** Background color, `#rgb`/`#rrggbb`. */
@@ -84,6 +87,12 @@ export type ImageFit = "natural" | "width";
  */
 export type ImageStyleDeclarations = Pick<StyleDeclarations, "background" | "align">;
 
+/**
+ * What a report default declares: the two declarations a typeface is made of.
+ * Anything else is a definition error, as on an image item.
+ */
+export type ReportStyleDeclarations = Pick<StyleDeclarations, "family" | "size">;
+
 /**
  * A host-supplied raster graphic in the band flow. `source` is an expression
  * (never a literal — JSON has no way to write bytes) yielding the complete
@@ -101,8 +110,31 @@ export interface ImageItem {
   style?: ImageStyleDeclarations;
 }
 
-/** One item in a band: text, or an image. Future types may be additive. */
-export type Item = TextItem | ImageItem;
+/**
+ * One slot of a split: an ordinary item, plus the width share that is a slot
+ * property rather than an item one. A split may not stand in a slot —
+ * placement inside placement is the coordinate system quario does not have.
+ */
+export type SplitSlot = (TextItem | ImageItem) & {
+  /** Slot width as a percentage of the content width (0 < width <= 100). */
+  width?: number;
+};
+
+/**
+ * Items placed across the content width rather than stacked down the band —
+ * the invoice header's "seller left, customer right". A split is always the
+ * full content width and never nests; a slot that renders nothing keeps its
+ * width, so the line's geometry does not move with the data.
+ */
+export interface SplitItem {
+  type: "split";
+  slots: [SplitSlot, SplitSlot, ...SplitSlot[]];
+  visible?: ExpressionValue<boolean>;
+  style?: StyleDeclarations;
+}
+
+/** One item in a band: text, an image, or a split. Future types may be additive. */
+export type Item = TextItem | ImageItem | SplitItem;
 
 export interface TableHeader {
   value: CellValue;
@@ -178,6 +210,12 @@ export interface ReportSchema {
   aggregates?: Record<string, ReducerSpec>;
   /** Running accumulators, read as `run.<name>` on detail rows. */
   run?: Record<string, ReducerSpec>;
+  /**
+   * The report default: the typeface this document is set in. It sits under
+   * the targets' band-role defaults and under every item's own `style`, so a
+   * declared `size` does not change a report header's headline size.
+   */
+  style?: ReportStyleDeclarations;
   header?: Item[];
   empty?: Item[];
   /**
@@ -246,6 +284,12 @@ export type Token = LiteralToken | ValueToken;
 export interface EventCell {
   tokens: Token[];
   style?: Record<string, unknown>;
+  /**
+   * The definition's schema path, on cells that belong to one: a `row` cell
+   * carries its column's (`detail.columns[i]`), a `total-row` cell its
+   * `detail.total[i]` entry. Absent on page-band cells reached by closure.
+   */
+  path?: string;
 }
 
 /** The page anchor a paginated target passes to page band closures. */
@@ -273,6 +317,15 @@ export interface ReportStartEvent {
   page?: PageBandRenderers;
   /** The declared page column count, present when the root declares one. */
   columns?: number;
+  /**
+   * The resolved report default, present when the report declares one. It is
+   * a report-level fact rather than something merged into each item's style,
+   * so a consumer composes it once — under its own band-role defaults, and
+   * under every event's own `style`. Ignoring it renders the report in the
+   * consumer's own baseline, which is what a consumer written before this
+   * field already does.
+   */
+  style?: Record<string, unknown>;
   /**
    * The marking wording, present when this render is not covered by a valid
    * license key — including while verification is still settling (await the
@@ -286,6 +339,8 @@ export interface ReportStartEvent {
 export interface ItemEvent {
   type: "item";
   role: ItemRole;
+  /** The item definition's schema path, e.g. `detail[0]`. */
+  path: string;
   tokens: Token[];
   style?: Record<string, unknown>;
   run?: Record<string, unknown>;
@@ -297,6 +352,8 @@ export type ImageFormat = "png" | "jpeg";
 export interface ImageEvent {
   type: "image";
   role: ItemRole;
+  /** The image definition's schema path. */
+  path: string;
   /** The bytes exactly as the `source` expression yielded them. */
   bytes: Uint8Array;
   /** Sniffed from the bytes' magic numbers, so no consumer repeats it. */
@@ -308,9 +365,28 @@ export interface ImageEvent {
   run?: Record<string, unknown>;
 }
 
+/**
+ * Opens a split: the slot geometry, then one ordinary `item` or `image` event
+ * per slot in order, then `split-end`. A consumer with no handler for the
+ * bracket still receives the slot items and renders them stacked.
+ */
+export interface SplitStartEvent {
+  type: "split-start";
+  role: ItemRole;
+  /** One entry per slot, in order; `width` is absent on a width-less slot. */
+  slots: { width?: number }[];
+  style?: Record<string, unknown>;
+}
+
+export interface SplitEndEvent {
+  type: "split-end";
+}
+
 export interface GroupStartEvent {
   type: "group-start";
   name: string;
+  /** The group definition's schema path, e.g. `groups[0]`. */
+  path: string;
   depth: number;
   key: unknown;
   aggregates: Record<string, unknown>;
@@ -329,7 +405,9 @@ export interface GroupEndEvent {
 
 export interface TableStartEvent {
   type: "table-start";
-  columns: { header: EventCell; width?: number }[];
+  /** Always `detail` — the table definition's schema path. */
+  path: string;
+  columns: { header: EventCell; path: string; width?: number }[];
 }
 
 export interface RowEvent {
@@ -356,6 +434,8 @@ export type ReportEvent =
   | ReportStartEvent
   | ItemEvent
   | ImageEvent
+  | SplitStartEvent
+  | SplitEndEvent
   | GroupStartEvent
   | GroupEndEvent
   | TableStartEvent
@@ -364,10 +444,19 @@ export type ReportEvent =
   | TableEndEvent
   | ReportEndEvent;
 
+/**
+ * One registry function a compiled report calls: its arity (the function's
+ * declared parameter count, or its own numeric `arity` where `length`
+ * misleads) and its own `doc` string when it carries one — xprsn's
+ * `signatures()` convention, in call-first-seen order. Aliased so hosts type
+ * the metadata from 'quario' alone, without their own xprsn dependency.
+ */
+export type FunctionSignature = XprsnSignature;
+
 export interface ReportEventStream {
   (data?: unknown): Generator<ReportEvent, void, undefined>;
   readonly names: readonly string[];
-  readonly functions: readonly string[];
+  readonly functions: readonly FunctionSignature[];
   readonly paths: readonly QueryPath[];
 }
 
@@ -397,10 +486,23 @@ export function walk(events: Iterable<ReportEvent>, handlers: WalkHandlers): Pro
  */
 export function breathe(): Promise<void>;
 
-export type QuarioErrorCode = SjabloonErrorCode | PadvinderErrorCode;
+/**
+ * Every code a located diagnostic can carry, which is a code from whichever
+ * engine decided the fault: quario relocates xprsn's directly, sjabloon
+ * carries xprsn's on a fault inside an expression, and padvinder carries
+ * treffer's on a pattern literal rejected when the query compiles.
+ *
+ * `TrefferErrorCode` reaches this union through padvinder, which re-exports
+ * it, so quario needs no treffer dependency to name it here.
+ */
+export type QuarioErrorCode =
+  | SjabloonErrorCode
+  | XprsnErrorCode
+  | PadvinderErrorCode
+  | TrefferErrorCode;
 
 export interface QuarioDiagnostic extends Error {
-  /** Absent on padvinder path-syntax errors; present on every other diagnostic. */
+  /** Absent on option and target-definition faults; present on every other diagnostic. */
   readonly code?: QuarioErrorCode;
   readonly start?: number;
   readonly end?: number;
@@ -414,7 +516,7 @@ export interface CompiledReport {
   /** The raw event seam: one generator of report events per call. */
   stream(data?: unknown): Generator<ReportEvent, void, undefined>;
   readonly names: readonly string[];
-  readonly functions: readonly string[];
+  readonly functions: readonly FunctionSignature[];
   readonly paths: readonly QueryPath[];
   /**
    * Render this compiled report through one target. Resolves the target's
@@ -424,6 +526,33 @@ export interface CompiledReport {
   render<Out>(target: Target<string, Out>, data?: unknown): Promise<Awaited<Out>>;
 }
 
+/**
+ * One definition problem, structurally: the schema path it sits at, the
+ * offending author source when the problem came from compiling one, the whole
+ * located message (`validate()`'s string is exactly this field), and the
+ * engine's located diagnostic when one authenticated the fault — every
+ * problem keeps its own, offsets included, not only the first.
+ */
+export interface Problem {
+  readonly path: string;
+  readonly source?: string;
+  readonly message: string;
+  readonly diagnostic?: QuarioDiagnostic;
+}
+
+/**
+ * The plan: both readings of the one traversal, kept. `report` is the
+ * compiled report, or null while the document has problems; `problems` is the
+ * structured list `validate()` flattens to strings; `anchors` maps each
+ * compiled source's schema path to the anchors and group handles it reads —
+ * the unfiltered complement of `names`, which excludes them.
+ */
+export interface Plan {
+  readonly report: CompiledReport | null;
+  readonly problems: readonly Problem[];
+  readonly anchors: Readonly<Record<string, readonly string[]>>;
+}
+
 export interface Quario {
   /**
    * Settles when this instance's license key verification completes;
@@ -432,6 +561,12 @@ export interface Quario {
   readonly license: Promise<LicenseInfo>;
   /** Compile a definition once; every target renders from it. */
   report(schema: ReportSchema, functions?: FunctionRegistry): CompiledReport;
+  /**
+   * The one traversal, whole: compiled report (null on problems), structured
+   * problems, and per-node anchor sets — one descent per edit for a host that
+   * validates and renders in a loop.
+   */
+  plan(schema: unknown, functions?: FunctionRegistry): Plan;
 }
 
 /**
@@ -451,11 +586,20 @@ export function validate(schema: unknown, functions?: FunctionRegistry): string[
 export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
 
 /**
- * Join a token stream to display text: literals verbatim, values as
- * `String(value ?? '')`. Re-exported from sjabloon.
+ * Join a token stream to display text: literals verbatim, values through
+ * `display()`. Re-exported from sjabloon.
  */
 export function text(tokens: readonly Token[]): string;
 
+/**
+ * Display text for one token value — the scalar rule `text()` joins with,
+ * re-exported from sjabloon so targets stringify exactly as the stream does.
+ * A valid `Date` renders as ISO 8601 UTC (`toISOString()`), deterministically
+ * across machines; an invalid `Date` stays `"Invalid Date"`; nullish displays
+ * empty; everything else is `String(value)`.
+ */
+export function display(value: unknown): string;
+
 /**
  * The typed-cell seam: exactly one value token holding a finite number, a
  * boolean, or a valid Date keeps its pre-stringify value; anything else —