quario 0.4.0 → 0.6.0

package/lib/index.d.ts

@@ -87,8 +87,26 @@ export interface StyleDeclarations extends BoxDeclarations {
   background?: ExpressionValue<string>;
   /** Horizontal alignment within the cell. */
   align?: ExpressionValue<Align>;
-  /** How a number or date is presented. Locale stays on the instance. */
-  format?: ExpressionValue<FormatKind>;
+  /**
+   * Vertical alignment within a box taller than its content: a table cell or
+   * row, a split slot (text or image). A definition error on a stacked item
+   * and on a band image, whose boxes have no such slack.
+   */
+  valign?: ExpressionValue<VAlign>;
+  /**
+   * How a number or date is presented: a kind, or an object naming one and
+   * carrying the single modifier that kind understands — `digits` for the
+   * three number kinds, `form` for `date`. Locale stays on the instance.
+   */
+  format?: ExpressionValue<FormatDeclaration>;
+  /**
+   * What this cell's money is denominated in, under `format: "currency"`:
+   * a three-letter ISO 4217 code, beating the instance's default. A literal
+   * that is not one is a definition error; an `=` result that is not one is
+   * the cell's own answer still, so the cell presents as display text rather
+   * than falling back to the instance's currency. Unread without the kind.
+   */
+  currency?: ExpressionValue<string>;
   /** Blank space before this item, in points. */
   spaceBefore?: ExpressionValue<number>;
   /** Blank space after this item, in points. */
@@ -104,8 +122,35 @@ export interface SortKey {
 export type CellValue = string;
 
 export type Align = "left" | "center" | "right";
+export type VAlign = "top" | "middle" | "bottom";
 export type FormatKind = "number" | "currency" | "percent" | "date";
 
+/** The four named date forms, Intl's own `dateStyle`. A `date` that names
+ * none is `"medium"`. */
+export type DateForm = "short" | "medium" | "long" | "full";
+
+/**
+ * How an author writes `format`: the kind alone, or the kind carrying its one
+ * modifier. `digits` is a whole number from 0 to 20 — the range both a
+ * presenting target and a worksheet number format can honour — and it beats
+ * the count the kind would otherwise present, a currency's minor units
+ * included. A modifier on a kind that does not take it is a definition error.
+ */
+export type FormatDeclaration =
+  | FormatKind
+  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | { kind: "date"; form?: DateForm };
+
+/**
+ * What `format` resolves to on the event stream: never the shorthand, always
+ * the kind with the answer it presents. A number kind carries `digits` unless
+ * it has no count at all — a `currency` whose code cannot be read — and a
+ * `date` always carries its `form`.
+ */
+export type ResolvedFormat =
+  | { kind: "number" | "currency" | "percent"; digits?: number }
+  | { kind: "date"; form: DateForm };
+
 export interface Cell {
   value: CellValue;
   visible?: ExpressionValue<boolean>;
@@ -155,12 +200,32 @@ export interface ImageItem {
   style?: ImageStyleDeclarations;
 }
 
+/**
+ * What a text slot declares: the vocabulary less flow spacing, which is a
+ * band-item pad and does not apply inside a split.
+ */
+export type SlotStyleDeclarations = Omit<StyleDeclarations, "spaceBefore" | "spaceAfter">;
+
+/**
+ * What an image slot declares: an image item's names less flow spacing, plus
+ * `valign` — the one name an image accepts in a slot and nowhere else, because
+ * a slot's box is the split's height rather than the picture's own.
+ */
+export type SlotImageStyleDeclarations = Omit<
+  ImageStyleDeclarations,
+  "spaceBefore" | "spaceAfter"
+> &
+  Pick<StyleDeclarations, "valign">;
+
 /**
  * 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) & {
+export type SplitSlot = (
+  | (Omit<TextItem, "style"> & { style?: SlotStyleDeclarations })
+  | (Omit<ImageItem, "style"> & { style?: SlotImageStyleDeclarations })
+) & {
   /** Slot width as a percentage of the content width (0 < width <= 100). */
   width?: number;
 };
@@ -185,10 +250,19 @@ export interface TableHeader {
   value: CellValue;
   /** Literal only — never an expression. */
   style?: StyleDeclarations;
+  /**
+   * How many columns this header covers — a literal integer >= 1, never an
+   * expression; absent is 1. The columns it covers omit their own `header`.
+   */
+  span?: number;
 }
 
 export interface TableColumn extends Cell {
-  header: string | TableHeader;
+  /**
+   * Absent exactly when a neighbour's header `span` covers this column: every
+   * column's header slot is filled once, by its own or by a span.
+   */
+  header?: string | TableHeader;
   /** Column width as a percentage of the table width (0 < width <= 100). */
   width?: number;
 }
@@ -198,12 +272,34 @@ export interface TableRow {
   style?: StyleDeclarations;
 }
 
+/**
+ * One cell of a total row: an ordinary cell, plus the columns it covers. The
+ * spans in a row must sum to the column count exactly.
+ */
+export type TotalCell = Cell & {
+  /**
+   * How many columns this cell covers — a literal integer >= 1, never an
+   * expression; absent is 1.
+   */
+  span?: number;
+};
+
 export interface TotalRow {
-  cells: [Cell, ...Cell[]];
+  cells: [TotalCell, ...TotalCell[]];
   visible?: ExpressionValue<boolean>;
   style?: StyleDeclarations;
 }
 
+/**
+ * The table's summary block: the rows, plus what belongs to the block rather
+ * than to any one of them. Its `style` is the layer below each row's — box
+ * under box, everything else under everything else — and exact `false` on its
+ * `visible` omits the block whole, its rows never evaluated.
+ */
+export interface TotalBlock extends TableRow {
+  rows: [TotalRow, ...TotalRow[]];
+}
+
 /**
  * The header row's own box — distinct from `TableHeader`, which is one
  * column's header cell. This is the box the row wears, replayed with the
@@ -217,7 +313,7 @@ export interface TableDetail {
   header?: TableHeaderBox;
   row?: TableRow;
   columns: [TableColumn, ...TableColumn[]];
-  total?: [TotalRow, ...TotalRow[]];
+  total?: TotalBlock;
 }
 
 export interface Group {
@@ -323,7 +419,10 @@ export interface QuarioOptions {
   license?: string;
   /** Locale for `format`. Defaults to `"en-US"` when a kind is presented. */
   locale?: string;
-  /** Currency code for `format: "currency"`. Absent, that kind contributes nothing. */
+  /**
+   * Default currency code for `format: "currency"`, overridden by a cell's own
+   * `style.currency`. Absent from both, that kind contributes nothing.
+   */
   currency?: string;
   /** Timezone for `format: "date"`. Defaults to `"UTC"`. */
   timeZone?: string;
@@ -357,10 +456,15 @@ export type Token = LiteralToken | ValueToken;
 export interface EventCell {
   tokens: Token[];
   style?: Record<string, unknown>;
+  /**
+   * How many columns this cell covers, present only when more than one: a
+   * span of 1 is the absence of one and never reaches the stream.
+   */
+  span?: number;
   /**
    * 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[r].cells[i]` entry. Absent on page-band cells reached by closure.
+   * `detail.total.rows[r].cells[i]` entry. Absent on page-band cells reached by closure.
    */
   path?: string;
 }
@@ -373,14 +477,21 @@ export interface PageInfo {
   total: number;
 }
 
+/**
+ * What a page band closure hands back: the band's items as the walk would
+ * emit them, wearing the `page-header`/`page-footer` role — a text item, an
+ * image, or a split's bracket with one item per slot between it.
+ */
+export type PageBandEvent = ItemEvent | ImageEvent | SplitStartEvent | SplitEndEvent;
+
 /**
  * Per-render page band closures on `report-start` (present only when the
  * schema declares page bands). A paginated target calls them once per page;
- * each call returns resolved `page-header`/`page-footer` item events.
+ * each call returns that page's resolved band events.
  */
 export interface PageBandRenderers {
-  header?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
-  footer?: (page: PageInfo) => (ItemEvent | ImageEvent)[];
+  header?: (page: PageInfo) => PageBandEvent[];
+  footer?: (page: PageInfo) => PageBandEvent[];
 }
 
 export interface ReportStartEvent {
@@ -490,9 +601,15 @@ export interface TableStartEvent {
   type: "table-start";
   /** Always `detail` — the table definition's schema path. */
   path: string;
-  columns: { header: EventCell; path: string; width?: number }[];
-  /** The header-row box from `detail.header`, when declared. */
-  style?: Record<string, unknown>;
+  /**
+   * The header row: one cell per column a neighbour's span does not cover,
+   * so fewer cells than columns whenever one spans. Shaped like a `row`
+   * payload, `style` being what is left of `detail.header`'s block once its
+   * box has landed on these cells.
+   */
+  header: { cells: EventCell[]; style?: Record<string, unknown> };
+  /** The column geometry, one entry per column. */
+  columns: { width?: number }[];
 }
 
 export interface RowEvent {
@@ -672,6 +789,22 @@ export function validate(schema: unknown, functions?: FunctionRegistry): string[
  */
 export function isDiagnostic(e: unknown): e is QuarioDiagnostic;
 
+/**
+ * Mint an image failure named on the item that asked for the bytes — for a
+ * **render target**, which is where every image failure past the magic
+ * numbers happens: the engine vouches for those and no further.
+ *
+ * `path` is the image item's, from a stream event or a display-list op;
+ * `.source` is appended, that being the key an author would change. `said` is
+ * what failed in your own words, and a library's own message belongs after it
+ * rather than instead of it. The result is `cause`'s class, so an embedder's
+ * `RangeError` stays a `RangeError`, with `cause` set.
+ *
+ * Not a diagnostic: `isDiagnostic` does not answer for it, a decoder that
+ * refused a file being nobody's delegated engine.
+ */
+export function imageError(path: string | undefined, said: string, cause?: unknown): Error;
+
 /**
  * Join a token stream to display text: literals verbatim, values through
  * `display()`. Re-exported from sjabloon.
@@ -688,29 +821,62 @@ export function text(tokens: readonly Token[]): string;
 export function display(value: unknown): string;
 
 /**
- * Present a token for a resolved `format` kind. Returns nothing when the kind
- * does not apply, so the caller falls back to `display()`. Locale defaults to
- * `"en-US"`, dates to UTC.
+ * Which currency code a cell wears under `format: "currency"`: its own
+ * `style.currency` when it declares one — the gate's `null` included, which is
+ * why an unusable code presents nothing rather than the instance's currency —
+ * else the instance default. Exported for a target that needs the code itself
+ * rather than the presented text, as the XLSX one does.
+ */
+export function currencyOf(
+  style?: { currency?: unknown } | null,
+  options?: { currency?: string } | null,
+): string | null;
+
+/**
+ * Present a token for a cell's resolved `style`. Reads the `format` kind and,
+ * under `"currency"`, the cell's own `currency` code; returns nothing when the
+ * kind does not apply, so the caller falls back to `display()`. Locale
+ * defaults to `"en-US"`, dates to UTC.
  */
 export function format(
   value: unknown,
-  kind: unknown,
+  style?: { format?: unknown; currency?: unknown } | null,
   options?: { locale?: string; currency?: string; timeZone?: string } | null,
 ): string | undefined;
 
+/**
+ * How many fraction digits a cell presents. Takes the whole style, as
+ * `format()` and `currencyOf()` do. `number` and `percent` present a fixed
+ * count, `currency` its currency's minor units, and a declared `digits` beats
+ * either — so the digits converge wherever the cell is rendered.
+ *
+ * A resolved style carries the answer on `style.format.digits` and a target
+ * reads it there; this is for a host holding a style the stream has not
+ * resolved, and the shorthand is widened here first.
+ *
+ * Returns nothing when the cell presents no count: `date`, no `format`, an
+ * unknown kind, and a `currency` with no code or one Intl will not read. A
+ * caller that gets nothing presents some other way — `format()` falls back to
+ * `display()`, and a worksheet writes no number format.
+ */
+export function fractionDigits(
+  style?: { format?: unknown; currency?: unknown } | null,
+  options?: { currency?: string } | null,
+): number | undefined;
+
 /**
  * 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 —
  * including a lone null — reports `undefined` and joins to display text.
  *
- * Passing the cell's resolved `format` kind opts into the seam's one
- * coercion: under `"date"`, a string in either accepted RFC 3339 form —
+ * Passing the cell's resolved `format` declaration opts into the seam's one
+ * coercion: under the `date` kind, a string in either accepted RFC 3339 form —
  * `YYYY-MM-DD`, or a timestamp naming its offset — revives to the Date it
  * names. Omitting the argument leaves the seam as it was.
  */
 export function typed(
   tokens: readonly Token[],
-  kind?: unknown,
+  decl?: ResolvedFormat | FormatKind,
 ): number | boolean | Date | undefined;
 
 /**
@@ -721,3 +887,25 @@ export function typed(
  * one: the question is whose band a role names, not what a walk can hand over.
  */
 export function isReportBand(role: string | undefined): boolean;
+
+/**
+ * Every name in the closed style vocabulary, in the order SCHEMA.md's table
+ * lists them. A tool that offers the vocabulary imports this rather than
+ * keeping a copy.
+ */
+export const STYLE_NAMES: readonly string[];
+
+/**
+ * The `format` vocabulary as data, for a tool that offers it rather than
+ * checks it — a style rail's kind picker and its modifier control — so no
+ * surface keeps a copy that has to be told about a change.
+ */
+export const FORMAT_VOCABULARY: {
+  readonly kinds: readonly FormatKind[];
+  readonly forms: readonly DateForm[];
+  /** Which modifier each kind takes, so a surface offering the pair need not
+   * know that three kinds share `digits` and `date` does not. */
+  readonly modifiers: Readonly<Record<FormatKind, "digits" | "form">>;
+  readonly defaultForm: DateForm;
+  readonly maxDigits: number;
+};

package/lib/index.js

@@ -13,6 +13,7 @@
  * siblings beside it, one seam each. See SCHEMA.md for the document shape.
  */
 import { relocate as relocateQuery } from "padvinder";
+import { LEAD_REFUSED, isLead, leadPath } from "./band-height.js";
 import { MARKING, verify } from "./license.js";
 import { err, fault, locate } from "./locate.js";
 import { BLOCKED, NAME, record } from "./names.js";
@@ -25,7 +26,8 @@ import { opt } from "./stream.js";
 // imports them from the package, not from a file inside it.
 export { breathe, display, isReportBand, text, typed, walk } from "./stream.js";
 export { format } from "./format.js";
-export { isDiagnostic } from "./locate.js";
+export { currencyOf, FORMAT_VOCABULARY, fractionDigits, STYLE_NAMES } from "./style.js";
+export { imageError, isDiagnostic } from "./locate.js";
 
 /** @typedef {import("./scope.js").Scope} Scope */
 
@@ -133,16 +135,19 @@ function events(schema, funcs, options, marking) {
 /** @type {(event: any) => boolean} */
 let occupying = (event) =>
   event.type === "item" || event.type === "image" || event.type === "split-start";
-/** @type {(n: any) => boolean} */
-let nonzeroLead = (n) => Number.isFinite(n) && n !== 0;
-/** @type {(event: any) => string} */
-let eventPath = (event) => event.path || "header";
 /** @type {(event: any) => void} */
 let refuseLead = (event) => {
-  if (nonzeroLead(event.style?.spaceBefore))
-    fault(eventPath(event) + ".style.spaceBefore", "must be 0 after a height-declared header");
+  if (isLead(event.style?.spaceBefore)) fault(leadPath(event.path), LEAD_REFUSED);
 };
-/** @type {(events: Iterable<any>) => Generator<any>} */
+/**
+ * Refuse the lead the document could not settle. `plan()` has already refused
+ * every candidate the document itself decides (./band-height.js); what reaches
+ * here is the rest — a lead that is an expression, or an item whose occupancy
+ * only the data knows — so the first occupying event of the band under the
+ * pinned box is the one this sees, whichever band that turned out to be.
+ *
+ * @type {(events: Iterable<any>) => Generator<any>}
+ */
 function* guardPin(events) {
   let pending = true;
   for (let event of events) {

package/lib/license.js

@@ -11,7 +11,7 @@
 // reassigns them. A key is valid for every version released inside its window
 // (LICENSE section 7), so validity compares ISO date strings and never reads
 // a clock — accepted output stays accepted.
-let RELEASE = "2026-09-03"; // x-release-please-date
+let RELEASE = "2026-09-07"; // x-release-please-date
 // The verifying half of the signing pair: the 65-byte uncompressed P-256
 // point, base64url. The private half never enters the repo;
 // scripts/license/sign.mjs mints keys against it.

package/lib/locate.js

@@ -37,6 +37,38 @@ export let fault = (path, msg) => {
   throw Object.assign(Error(path + ": " + msg), { [LOCATION]: { path } });
 };
 
+/**
+ * An image failure a **target** raises, named on the item that asked for the
+ * bytes. The engine vouches for an image's magic numbers and no further
+ * (SCHEMA.md, "Image item"), so every failure past that point belongs to
+ * whichever target was sizing or embedding the file — and each of them was
+ * inventing its own wording, down to a corrupt PNG reaching a host as
+ * pdf-lib's bare "Invalid typed array length: 0" (quario-e0bz).
+ *
+ * Here rather than in a target because three of them raise it and no two of
+ * them may depend on each other; the engine is what they all already have.
+ * Minted rather than thrown, unlike `fault` beside it, so a caller can raise
+ * it from a `catch` or a rejection in whichever style its own code is.
+ *
+ * The shape is the one every render error has: the path prefixes the message
+ * and the failing class survives behind it. It carries no `LOCATION` and is no
+ * `isDiagnostic` diagnostic — the traversal never sees it, and a decoder that
+ * refused a file is not a delegated engine.
+ *
+ * @type {(path: string | undefined, said: string, cause?: unknown) => Error}
+ */
+export let imageError = (path, said, cause) => {
+  let error = TypeError((path ? path + ".source: " : "") + said, { cause });
+  // Wear the failing class rather than construct it. Keeping
+  // `e instanceof RangeError` true matters — a host may already be catching
+  // one — but the class is a library's and its constructor need not take
+  // `(message, options)` at all: one taking other arguments would mangle the
+  // message and swallow `cause`, turning a located failure back into the
+  // stray throw this exists to replace. Reparenting asks the class for
+  // nothing, so there is no call to check and nothing it can refuse.
+  if (cause instanceof Error) Object.setPrototypeOf(error, Object.getPrototypeOf(cause));
+  return error;
+};
 /**
  * Re-throw `error` located at `path`, with `src` — the offending author
  * source — in the message.

package/lib/math.js

@@ -0,0 +1,71 @@
+/**
+ * The scalar built-ins: quario's half of an expression's function scope that
+ * folds nothing. They live beside the reducers in SCHEMA.md ("Built-in
+ * functions") and apart from them here, because the reducers are also the
+ * declared-aggregate vocabulary and these can never be one -- `reducers.js`
+ * names no function in this file, so `"total": "round:=..."` stays a definition
+ * error.
+ *
+ * `round`, `floor` and `ceil` round the DECIMAL the author wrote, not the
+ * binary double it is stored as, and `Intl.NumberFormat` is how they reach it:
+ * its rounding starts from the shortest decimal that round-trips, so
+ * `round(2.675, 2)` is 2.68 where `Math.round(2.675 * 100) / 100` is 2.67 and
+ * `Number((2.675).toFixed(2))` is also 2.67. Those two disagree with each other
+ * as well as with us, on different inputs -- the whole argument, with the
+ * table, is in docs/adr/0050. The locale is hardcoded `en-US` rather than the
+ * instance's: this is arithmetic, not presentation, and a locale with
+ * non-ASCII digits or its own grouping would not parse back through `Number`.
+ * Formatters are built per call, deliberately -- see the ADR.
+ */
+/** @type {(x: number, n: number, mode: string) => number} */
+let decimal = (x, n, mode) =>
+  Number(
+    new Intl.NumberFormat("en-US", {
+      minimumFractionDigits: n,
+      maximumFractionDigits: n,
+      useGrouping: false,
+      roundingMode: /** @type {any} */ (mode),
+    }).format(x),
+  );
+// The one test both halves make of `x`. Named because the rule it stands for
+// is the interesting part: rounding a value that is not a finite number would
+// have to invent one, so it passes through instead. The reducers coerce
+// quietly because a fold must produce a total; a scalar has no such
+// obligation, and coercing here would turn a data error into a confident 0
+// where passing through leaves the cell as display text -- a failure the
+// author can see.
+/** @type {(x: any) => boolean} */
+let finite = (x) => typeof x === "number" && Number.isFinite(x);
+
+// Split from `places` rather than inlined: the three tests plus the coercion
+// and the throw put one function at cyclomatic 5, and the health gate's CRAP
+// ceiling lands at 4 (docs/agents/commands.md).
+/** @type {(digits: number) => boolean} */
+let honourable = (digits) => Number.isFinite(digits) && digits >= 0 && digits <= 100;
+// `n` is authored, so a bad one is a mistake worth failing on -- unlike `x`,
+// which is data. Intl would throw its own RangeError naming
+// `maximumFractionDigits`, an option the author never wrote, so the message is
+// ours. Fractional `n` truncates rather than throwing, which is what Intl does
+// with it and is not worth a second rule for an author to hold.
+/** @type {(n: any) => number} */
+let places = (n) => {
+  let digits = Math.trunc(+(n ?? 0));
+  if (!honourable(digits)) throw new RangeError("n must be a number from 0 to 100");
+  return digits;
+};
+
+/** @type {(mode: string) => (x: any, n: any) => any} */
+let rounder = (mode) => (x, n) => {
+  let digits = places(n);
+  return finite(x) ? decimal(x, digits, mode) : x;
+};
+/** @type {Record<string, (...args: any[]) => any>} */
+export let MATH = {
+  // Written `(x, n)` rather than `(x, n = 0)` on purpose: xprsn's signatures()
+  // reports arity from `fn.length`, and a default parameter would describe
+  // these to an editor as taking one argument.
+  round: rounder("halfExpand"),
+  floor: rounder("floor"),
+  ceil: rounder("ceil"),
+  abs: (x) => (finite(x) ? Math.abs(x) : x),
+};