quario 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,59 @@ 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

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;
+  }
+}

package/lib/index.d.ts

@@ -53,6 +53,12 @@ export interface StyleDeclarations {
   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>;
+  /** Blank space before this item, in points. */
+  spaceBefore?: ExpressionValue<number>;
+  /** Blank space after this item, in points. */
+  spaceAfter?: ExpressionValue<number>;
 }
 
 export interface SortKey {
@@ -64,6 +70,7 @@ export interface SortKey {
 export type CellValue = string;
 
 export type Align = "left" | "center" | "right";
+export type FormatKind = "number" | "currency" | "percent" | "date";
 
 export interface Cell {
   value: CellValue;
@@ -85,7 +92,10 @@ export type ImageFit = "natural" | "width";
  * error. A narrowing of the one vocabulary rather than a second list of its
  * own, so the two cannot drift.
  */
-export type ImageStyleDeclarations = Pick<StyleDeclarations, "background" | "align">;
+export type ImageStyleDeclarations = Pick<
+  StyleDeclarations,
+  "background" | "align" | "spaceBefore" | "spaceAfter"
+>;
 
 /**
  * What a report default declares: the two declarations a typeface is made of.
@@ -153,10 +163,16 @@ export interface TableRow {
   style?: StyleDeclarations;
 }
 
+export interface TotalRow {
+  cells: [Cell, ...Cell[]];
+  visible?: ExpressionValue<boolean>;
+  style?: StyleDeclarations;
+}
+
 export interface TableDetail {
   row?: TableRow;
   columns: [TableColumn, ...TableColumn[]];
-  total?: Cell[];
+  total?: [TotalRow, ...TotalRow[]];
 }
 
 export interface Group {
@@ -195,6 +211,8 @@ export interface Group {
 export interface PageBands {
   header?: Item[];
   footer?: Item[];
+  /** Inset on all four sides, in points. Required when the report header declares `height`. */
+  margin?: number;
 }
 
 export interface ReportSchema {
@@ -216,7 +234,11 @@ export interface ReportSchema {
    * declared `size` does not change a report header's headline size.
    */
   style?: ReportStyleDeclarations;
-  header?: Item[];
+  /**
+   * Dual-shaped like `detail`: an item array, or `{ height, items }` when the
+   * header pins a flow box from the page top.
+   */
+  header?: Item[] | { height: number; items: Item[] };
   empty?: Item[];
   /**
    * Flow the report body in this many page columns (integer >= 2). Columned
@@ -254,6 +276,12 @@ export interface QuarioOptions {
    * report this instance compiles marks its output as unlicensed.
    */
   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. */
+  currency?: string;
+  /** Timezone for `format: "date"`. Defaults to `"UTC"`. */
+  timeZone?: string;
 }
 
 /** The settled result of an instance's license key verification. */
@@ -287,7 +315,7 @@ export interface EventCell {
   /**
    * 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.
+   * `detail.total[r].cells[i]` entry. Absent on page-band cells reached by closure.
    */
   path?: string;
 }
@@ -334,6 +362,16 @@ export interface ReportStartEvent {
    * states it so no target has to know it.
    */
   marking?: string;
+  /** The document's `page.margin`, when declared. */
+  margin?: number;
+  /** The report header's authored `height`, when the object form is used. */
+  headerHeight?: number;
+  /** Present when the instance was constructed with `locale`. */
+  locale?: string;
+  /** Present when the instance was constructed with `currency`. */
+  currency?: string;
+  /** Present when the instance was constructed with `timeZone`. */
+  timeZone?: string;
 }
 
 export interface ItemEvent {
@@ -408,6 +446,8 @@ export interface TableStartEvent {
   /** 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>;
 }
 
 export interface RowEvent {
@@ -420,6 +460,8 @@ export interface RowEvent {
 export interface TotalRowEvent {
   type: "total-row";
   cells: EventCell[];
+  /** The total-row box from that row's `style`, when declared. */
+  style?: Record<string, unknown>;
 }
 
 export interface TableEndEvent {
@@ -600,6 +642,17 @@ 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.
+ */
+export function format(
+  value: unknown,
+  kind: unknown,
+  options?: { locale?: string; currency?: string; timeZone?: string } | null,
+): string | 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 —

package/lib/index.js

@@ -14,7 +14,7 @@
  */
 import { relocate as relocateQuery } from "padvinder";
 import { MARKING, verify } from "./license.js";
-import { err, locate } from "./locate.js";
+import { err, fault, locate } from "./locate.js";
 import { BLOCKED, NAME, record } from "./names.js";
 import { plan } from "./plan.js";
 import { aggregateValue, startRunners, withPage, withRow } from "./scope.js";
@@ -24,6 +24,7 @@ import { opt } from "./stream.js";
 // diagnostic predicate in ./locate.js. Re-exported here because a consumer
 // 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";
 
 /** @typedef {import("./scope.js").Scope} Scope */
@@ -126,7 +127,31 @@ function events(schema, funcs, options, marking) {
   let planned = plan(schema, funcs, options);
   if (planned.problems.length)
     throw planned.diagnostic() || SyntaxError(planned.problems[0].message);
-  return assemble(planned, schema, marking);
+  return assemble(planned, schema, marking, options);
+}
+
+/** @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");
+};
+/** @type {(events: Iterable<any>) => Generator<any>} */
+function* guardPin(events) {
+  let pending = true;
+  for (let event of events) {
+    if (pending && occupying(event)) {
+      pending = false;
+      refuseLead(event);
+    }
+    yield event;
+  }
 }
 
 /**
@@ -137,11 +162,14 @@ function events(schema, funcs, options, marking) {
  * @param {ReturnType<typeof plan>} planned The finished traversal.
  * @param {any} schema The report document, for locating `data` faults.
  * @param {() => string | false} marking This render's unlicensed marking.
+ * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
+ *   locale?: string, currency?: string, timeZone?: string} | undefined} options
+ *   Host controls closed over this compile.
  * @returns {{(data?: any): Generator<object, void, undefined>, names: string[],
  *   functions: { name: string, arity: number, doc?: string }[],
  *   paths: readonly any[]}} Event stream factory.
  */
-function assemble(planned, schema, marking) {
+function assemble(planned, schema, marking, options) {
   // Null only for a non-object schema, which is itself a collected problem.
   // `select` and `params` come from the traversal too: it checked them, so
   // nothing here compiles or clones a second time.
@@ -161,6 +189,8 @@ function assemble(planned, schema, marking) {
     band,
     pageHeader,
     pageFooter,
+    headerHeight,
+    margin,
   } = /** @type {NonNullable<typeof planned.compiled>} */ (planned.compiled);
 
   // The runner's own faults are located per render: a budget is spent while
@@ -203,15 +233,29 @@ function assemble(planned, schema, marking) {
     // only where it goes. Read as the event is yielded, so a render drained
     // before verification settles counts as unlicensed (SCHEMA.md, "License
     // keys").
+    /** @type {(options: any) => { locale?: string, currency?: string, timeZone?: string }} */
+    let intlOf = (host) => ({
+      locale: host?.locale,
+      currency: host?.currency,
+      timeZone: host?.timeZone,
+    });
     /** @type {() => Generator<object, void, undefined>} */
     function* walked() {
       yield opt(
         { type: "report-start", params: root.params, aggregates },
-        { page, columns, style: style(base), marking: marking() },
+        {
+          page,
+          columns,
+          style: style(base),
+          marking: marking(),
+          ...intlOf(options),
+          margin,
+          headerHeight,
+        },
       );
       yield* header(base);
-      if (!rows.length && empty) yield* empty(base);
-      else yield* band(rows, base, runners);
+      let body = !rows.length && empty ? empty(base) : band(rows, base, runners);
+      yield* headerHeight != null ? guardPin(body) : body;
       yield* footer(base);
       yield { type: "report-end" };
     }
@@ -236,8 +280,10 @@ function assemble(planned, schema, marking) {
  * ("Instances and targets").
  *
  * @param {{query?: {maxNodes?: number, maxDepth?: number, maxResults?: number},
- *   license?: string, trust?: {publicKey?: string, release?: string}}} [options]
+ *   license?: string, trust?: {publicKey?: string, release?: string},
+ *   locale?: string, currency?: string, timeZone?: string}} [options]
  *   Host configuration. `trust` is internal, not API — see ./license.js.
+ *   `locale` / `currency` / `timeZone` present `format` (docs/adr/0041).
  * @returns {{license: Promise<LicenseInfo>,
  *   report: (schema: any, funcs?: Record<string, Function>) => any,
  *   plan: (schema: any, funcs?: Record<string, Function>) => any}} The instance.
@@ -281,7 +327,7 @@ export function quario(options) {
     plan(schema, funcs) {
       let planned = plan(schema, funcs, options);
       return {
-        report: planned.problems.length ? null : wrap(assemble(planned, schema, marking)),
+        report: planned.problems.length ? null : wrap(assemble(planned, schema, marking, options)),
         problems: freezeProblems(planned.problems),
         anchors: freezeAnchors(planned.anchors),
       };

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-01"; // x-release-please-date
+let RELEASE = "2026-09-02"; // 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/plan.js

@@ -47,7 +47,16 @@ import { LOCATION, fault, isDiagnostic, locate } from "./locate.js";
 import { ANCHORS, BLOCKED, NAME, RESERVED, record } from "./names.js";
 import { AGG, REDUCERS, RUN, aggregateValue, withRow } from "./scope.js";
 import { opt, sniff } from "./stream.js";
-import { checkImageStyle, checkReportStyle, checkStyle } from "./style.js";
+import {
+  checkBorderSides,
+  checkCellStyle,
+  checkImageStyle,
+  checkReportStyle,
+  checkRowStyle,
+  checkSlotImageStyle,
+  checkSlotStyle,
+  checkStyle,
+} from "./style.js";
 
 // Tolerance on the column-width sum. Widths are literal numbers an author may
 // write as thirds, so an exact comparison rejects 33.3 x 3 for a rounding error
@@ -563,6 +572,7 @@ let readers = ({ bad, attempt }, { prop, cell, parseFold }) => {
    */
   let compileStyles = (block, path, check) => {
     let entries = readStyles(block, path, check);
+    for (let [name, msg] of checkBorderSides(block, check)) bad(path + "." + name, msg);
     if (!entries.length) return NIL;
     let resolve = styleFn(entries);
     if (isComputed(block)) return resolve;
@@ -725,7 +735,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
   let cellOf = (def, path, valuePath = path + ".value") => {
     let tpl = cellValue(def.value, valuePath);
     let visible = visibleOf(def, path);
-    return cellShape(tpl, visible, stylesOf(def, path));
+    return cellShape(tpl, visible, stylesOf(def, path, checkCellStyle));
   };
 
   // A cell without a row, so `@` stays unbound. A bare string is shorthand for
@@ -756,7 +766,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     let header = headerOf(def.header, path + ".header");
     let tpl = cellValue(def.value, path + ".value");
     let visible = visibleOf(def, path);
-    let styles = stylesOf(def, path);
+    let styles = stylesOf(def, path, checkCellStyle);
     // A width is a percentage of the table width, resolved by every target.
     // The range verdict is owned here: an unreadable width comes back as NaN,
     // so the total check below reads the verdict instead of re-deciding it.
@@ -780,7 +790,11 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     checkTextType(def.type, path);
     let tpl = cellValue(def.value, path + ".value");
     let visible = visibleOf(def, path);
-    let shape = cellShape(tpl, inSlot ? visible : null, stylesOf(def, path));
+    let shape = cellShape(
+      tpl,
+      inSlot ? visible : null,
+      stylesOf(def, path, inSlot ? checkSlotStyle : checkStyle),
+    );
     // The cell shape first, then the item's own fields, so a cell reads
     // the same wherever it appears in the stream.
     return (scope) => {
@@ -845,6 +859,8 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
   // An image item: bytes an `=` expression yields, sized by `fit`, with an
   // optional textual stand-in. JSON has no way to write bytes, so `source` is
   // expression-only; the vocabulary an image accepts is `style.js`'s to narrow.
+  /** @type {(inSlot: boolean) => (name: string, value: any) => string | null} */
+  let imageLook = (inSlot) => (inSlot ? checkSlotImageStyle : checkImageStyle);
   /** @type {(def: any, path: string, role: string, inSlot?: boolean) => (scope: Scope) => any} */
   let imageOf = (def, path, role, inSlot = false) => {
     keys(def, inSlot ? IMAGE_SLOT_KEYS : IMAGE_KEYS, path);
@@ -855,7 +871,7 @@ let nodes = ({ bad }, { arr, obj, keys, expression, cellValue, visibleOf, styles
     // problems twice, and reading it early would report them out of order.
     let alt = altOf(def, path);
     let visible = visibleOf(def, path);
-    let styles = stylesOf(def, path, checkImageStyle);
+    let styles = stylesOf(def, path, imageLook(inSlot));
     let render = renderImage({
       source,
       fit: def.fit ?? "natural",
@@ -1005,9 +1021,17 @@ let bands = (
     keys(value.row, ["visible", "style"], "detail.row");
     return {
       rowVisible: visibleOf(value.row, "detail.row"),
-      rowStyles: stylesOf(value.row, "detail.row"),
+      rowStyles: stylesOf(value.row, "detail.row", checkRowStyle),
     };
   };
+  // The header-row box: `style` only, a different path from each column's
+  // `header` cell. Absent when the table declares none.
+  /** @type {(value: any) => (scope: Scope) => any} */
+  let headerLook = (value) => {
+    if (value.header == null || !obj(value.header, "detail.header")) return NIL;
+    keys(value.header, ["style"], "detail.header");
+    return stylesOf(value.header, "detail.header", checkRowStyle);
+  };
   /** @type {(value: any) => { defs: any[] | null, columns: any[] }} */
   let tableColumns = (value) => {
     let defs = arr(value.columns, "detail.columns", true);
@@ -1018,24 +1042,51 @@ let bands = (
     checkShares(bad, columns, "detail.columns", "column");
     return { defs, columns };
   };
-  /** @type {(totals: any[] | null, defs: any[] | null) => void} */
-  let checkTotalCount = (totals, defs) => {
-    if (totals && defs && totals.length !== defs.length)
-      bad("detail.total", "expected one cell per column");
-  };
-  /** @type {(totals: any[]) => any[]} */
-  let mapTotals = (totals) =>
+  /** @type {(totals: any[], prefix: string) => any[]} */
+  let mapTotals = (totals, prefix) =>
     totals
       .map((def, i) => {
-        let cell = totalOf(def, "detail.total[" + i + "]");
-        return cell && { cell, path: "detail.total[" + i + "]" };
+        let path = prefix + "[" + i + "]";
+        let cell = totalOf(def, path);
+        return cell && { cell, path };
       })
       .filter((entry) => entry != null);
-  /** @type {(value: any, defs: any[] | null) => any[] | null} */
-  let tableTotals = (value, defs) => {
-    let totals = arr(value.total, "detail.total");
-    checkTotalCount(totals, defs);
-    return totals ? mapTotals(totals) : null;
+  /** @type {(rows: any[] | null) => any[]} */
+  let nonempty = (rows) => {
+    if (rows && !rows.length) bad("detail.total", "expected at least one total row");
+    return rows || [];
+  };
+  /**
+   * @type {(value: any, defs: any[] | null) =>
+   *   { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null}
+   */
+  let tableTotals = (value, defs) =>
+    value.total == null
+      ? null
+      : nonempty(arr(value.total, "detail.total", true)).map((def, r) =>
+          totalRowOf(def, "detail.total[" + r + "]", defs),
+        );
+  /** @type {(cells: any[], defs: any[] | null) => boolean} */
+  let aligned = (cells, defs) => !defs || cells.length === defs.length;
+  /** @type {(cells: any[] | null, defs: any[] | null, path: string) => any[]} */
+  let counted = (cells, defs, path) => {
+    if (!cells) return [];
+    if (!aligned(cells, defs)) bad(path + ".cells", "expected one cell per column");
+    return cells;
+  };
+  /**
+   * @type {(def: any, path: string, defs: any[] | null) =>
+   *   { styles: (scope: Scope) => any, visible: any, cells: any[] }}
+   */
+  let totalRowOf = (def, path, defs) => {
+    if (!obj(def, path)) return { styles: NIL, visible: null, cells: [] };
+    keys(def, ["cells", "style", "visible"], path);
+    let cells = counted(arr(def.cells, path + ".cells", true), defs, path);
+    return {
+      styles: stylesOf(def, path, checkRowStyle),
+      visible: visibleOf(def, path),
+      cells: mapTotals(cells, path + ".cells"),
+    };
   };
   /**
    * @type {(rows: any[], scope: Scope, runners: RunnerSet, columns: any[],
@@ -1056,30 +1107,47 @@ let bands = (
         );
     }
   }
-  /** @type {(columns: any[], total: any[] | null, rowVisible: Eval | null, rowStyles: (scope: Scope) => any) => Band} */
-  let tableBand = (columns, total, rowVisible, rowStyles) =>
+  /**
+   * @type {(total: { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null,
+   *   scope: Scope) => Generator<any>}
+   */
+  function* emitTotals(total, scope) {
+    if (!total) return;
+    for (let row of total) {
+      if (hidden(row.visible, scope)) continue;
+      yield opt(
+        {
+          type: "total-row",
+          cells: row.cells.map(({ cell, path }) => Object.assign(cell(scope), { path })),
+        },
+        { style: row.styles(scope) },
+      );
+    }
+  }
+  /** @type {(columns: any[], total: { styles: (scope: Scope) => any, visible: any, cells: any[] }[] | null, rowVisible: Eval | null, rowStyles: (scope: Scope) => any, headerStyles: (scope: Scope) => any) => Band} */
+  let tableBand = (columns, total, rowVisible, rowStyles, headerStyles) =>
     function* (rows, scope, runners) {
-      yield {
-        type: "table-start",
-        path: "detail",
-        columns: columns.map((column) =>
-          opt({ header: column.header(scope), path: column.path }, { width: column.width }),
-        ),
-      };
+      yield opt(
+        {
+          type: "table-start",
+          path: "detail",
+          columns: columns.map((column) =>
+            opt({ header: column.header(scope), path: column.path }, { width: column.width }),
+          ),
+        },
+        { style: headerStyles(scope) },
+      );
       yield* tableRows(rows, scope, runners, columns, rowVisible, rowStyles);
-      if (total)
-        yield {
-          type: "total-row",
-          cells: total.map(({ cell, path }) => Object.assign(cell(scope), { path })),
-        };
+      yield* emitTotals(total, scope);
       yield { type: "table-end" };
     };
   /** @type {(value: any) => Band} */
   let tableOf = (value) => {
-    keys(value, ["row", "columns", "total"], "detail");
+    keys(value, ["header", "row", "columns", "total"], "detail");
+    let headerStyles = headerLook(value);
     let { rowVisible, rowStyles } = rowLook(value);
     let { defs, columns } = tableColumns(value);
-    return tableBand(columns, tableTotals(value, defs), rowVisible, rowStyles);
+    return tableBand(columns, tableTotals(value, defs), rowVisible, rowStyles, headerStyles);
   };
 
   // The detail band is polymorphic: an array of items stacks them per row, a
@@ -1251,17 +1319,87 @@ let selectOf = (schema, bad, attempt, options) => {
 };
 /** @type {(value: any, path: string, expression: any) => any} */
 let maybeExpr = (value, path, expression) => (value != null ? expression(value, path) : null);
-/** @type {(schema: any, obj: any, keys: any, itemsOf: any) => { pageHeader: any, pageFooter: any }} */
-let pageBands = (schema, obj, keys, itemsOf) => {
+/** @type {(n: any) => boolean} */
+let posPts = (n) => typeof n === "number" && Number.isFinite(n) && n > 0;
+/** @type {(n: any) => boolean} */
+let padPts = (n) => typeof n === "number" && Number.isFinite(n) && n >= 0;
+/** @type {(height: any, bad: any) => number | null} */
+let headerHeightOf = (height, bad) => {
+  if (height == null) bad("header.height", "required");
+  else if (!posPts(height)) bad("header.height", "expected a positive number of points");
+  return posPts(height) ? height : null;
+};
+/** @type {(itemsOf: any) => { items: any, height: number | null }} */
+let emptyHeader = (itemsOf) => ({ items: itemsOf(null, "header", "report-header"), height: null });
+/** @type {(value: any, keys: any, itemsOf: any, bad: any) => { items: any, height: number | null }} */
+let reportHeaderOf = (value, keys, itemsOf, bad) => {
+  if (value == null || Array.isArray(value))
+    return { items: itemsOf(value, "header", "report-header"), height: null };
+  if (!record(value)) {
+    bad("header", "expected an array of items or { height, items }");
+    return emptyHeader(itemsOf);
+  }
+  keys(value, ["height", "items"], "header");
+  return {
+    items: itemsOf(value.items, "header.items", "report-header"),
+    height: headerHeightOf(value.height, bad),
+  };
+};
+
+/** @type {(margin: any, bad: any) => number | null} */
+let pageMarginOf = (margin, bad) => {
+  if (margin != null && !padPts(margin))
+    bad("page.margin", "expected a non-negative number of points");
+  return padPts(margin) ? margin : null;
+};
+/** @type {(schema: any, obj: any, keys: any, itemsOf: any, bad: any) => { pageHeader: any, pageFooter: any, margin: number | null }} */
+let pageBands = (schema, obj, keys, itemsOf, bad) => {
   if (schema.page == null || !obj(schema.page, "page"))
-    return { pageHeader: null, pageFooter: null };
-  keys(schema.page, ["header", "footer"], "page");
+    return { pageHeader: null, pageFooter: null, margin: null };
+  keys(schema.page, ["header", "footer", "margin"], "page");
   return {
     pageHeader: maybeItems(schema.page.header, "page.header", "page-header", itemsOf),
     pageFooter: maybeItems(schema.page.footer, "page.footer", "page-footer", itemsOf),
+    margin: pageMarginOf(schema.page.margin, bad),
   };
 };
 
+/** @type {(def: any) => boolean} */
+let shown = (def) => !(def && def.visible === false);
+/** @type {(list: any, path: string) => [any, string] | null} */
+let firstOccupying = (list, path) => {
+  if (!Array.isArray(list)) return null;
+  let i = list.findIndex(shown);
+  return i < 0 ? null : [list[i], path + "[" + i + "]"];
+};
+/** @type {(schema: any) => any} */
+let firstGroupHeader = (schema) => {
+  let groups = schema.groups;
+  return Array.isArray(groups) && groups[0] ? groups[0].header : null;
+};
+/** @type {(schema: any) => [any, string] | null} */
+let nextAfterHeader = (schema) =>
+  firstOccupying(firstGroupHeader(schema), "groups[0].header") ||
+  firstOccupying(schema.detail, "detail");
+/** @type {(n: any) => boolean} */
+let nonzeroLead = (n) => typeof n === "number" && n !== 0;
+/** @type {(next: [any, string], bad: any) => void} */
+let refuseLiteralLead = (next, bad) => {
+  if (nonzeroLead(next[0].style?.spaceBefore))
+    bad(next[1] + ".style.spaceBefore", "must be 0 after a height-declared header");
+};
+/** @type {(schema: any, headerHeight: number | null, bad: any) => void} */
+let refusePinnedLead = (schema, headerHeight, bad) => {
+  if (headerHeight == null) return;
+  let next = nextAfterHeader(schema);
+  if (next) refuseLiteralLead(next, bad);
+};
+/** @type {(headerHeight: number | null, schema: any, bad: any) => void} */
+let needPinnedMargin = (headerHeight, schema, bad) => {
+  if (headerHeight != null && schema.page?.margin == null)
+    bad("page.margin", "required when header declares height");
+};
+
 /**
  * The root descent, in the schema's documented key order. `params` and `data`
  * are checked here the way every other key is — by compiling what they declare
@@ -1326,7 +1464,8 @@ let traverse = (
   // `report-start` field instead of being merged into every item's style --
   // nothing here allocates per cell (docs/adr/0033).
   let style = stylesOf(schema, "", checkReportStyle);
-  let header = itemsOf(schema.header, "header", "report-header");
+  let { items: header, height: headerHeight } = reportHeaderOf(schema.header, keys, itemsOf, bad);
+  refusePinnedLead(schema, headerHeight, bad);
   // Null when undeclared, so the render decides on the compiled band rather
   // than reading `schema.empty` a second time from outside the traversal.
   let empty = maybeItems(schema.empty, "empty", "empty", itemsOf);
@@ -1335,7 +1474,8 @@ let traverse = (
   let footer = itemsOf(schema.footer, "footer", "report-footer");
   // Page bands compile like any other band, but render per page, so the
   // stream hands paginated targets closures instead of events.
-  let { pageHeader, pageFooter } = pageBands(schema, obj, keys, itemsOf);
+  let { pageHeader, pageFooter, margin } = pageBands(schema, obj, keys, itemsOf, bad);
+  needPinnedMargin(headerHeight, schema, bad);
   return {
     select,
     params,
@@ -1346,12 +1486,14 @@ let traverse = (
     running,
     style,
     header,
+    headerHeight,
     empty,
     columns,
     footer,
     band,
     pageHeader,
     pageFooter,
+    margin,
   };
 };
 

package/lib/stream.js

@@ -14,9 +14,9 @@
 export { display, text } from "sjabloon";
 
 /** @type {(value: any) => boolean} */
-let finiteNum = (value) => typeof value === "number" && Number.isFinite(value);
+export let finiteNum = (value) => typeof value === "number" && Number.isFinite(value);
 /** @type {(value: any) => boolean} */
-let finiteDate = (value) => value instanceof Date && Number.isFinite(value.getTime());
+export let finiteDate = (value) => value instanceof Date && Number.isFinite(value.getTime());
 /** @type {(value: any) => number | boolean | Date | undefined} */
 let asTyped = (value) => {
   if (finiteNum(value)) return value;

package/lib/style.js

@@ -19,11 +19,14 @@ let spec = (msg, ok) => ({ ok, msg });
 let COLOR = spec("expected a #rgb or #rrggbb color", isHex);
 let FLAG = spec("expected a boolean", (value) => typeof value === "boolean");
 let ALIGNMENTS = ["left", "center", "right"];
-// The declarations an image item accepts. The rest of the vocabulary describes
-// text, which an image does not have, so anything else on one is a definition
-// error rather than a silent no-op (SCHEMA.md, "Image item"). The subset lives
-// beside the vocabulary it narrows, and `checkImageStyle` below is how the
-// traversal asks for it -- it keeps no second list of its own.
+let LINES = ["solid", "dashed", "dotted"];
+let SIDES = ["Top", "Right", "Bottom", "Left"];
+let BORDER_PARTS = ["Width", "Style", "Color"];
+// The declarations an image item accepts. Text names are refused; the box and
+// flow spacing are legal, because a band image has a box and sits in the flow
+// the way a text item does (SCHEMA.md, "Image item"). The subset lives beside
+// the vocabulary it narrows, and `checkImageStyle` below is how the traversal
+// asks for it -- it keeps no second list of its own.
 let IMAGE_STYLES = ["align", "background"];
 // The declarations a report default accepts. A report default states what the
 // document is set in, so it carries only the two declarations that describe a
@@ -46,7 +49,30 @@ let STYLES = {
   color: COLOR,
   background: COLOR,
   align: spec("expected left, center, or right", (value) => ALIGNMENTS.includes(value)),
+  format: spec("expected number, currency, percent, or date", (value) => FORMATS.includes(value)),
 };
+let FORMATS = ["number", "currency", "percent", "date"];
+let POINTS = spec(
+  "expected a non-negative number of points",
+  (value) => finite(value) && value >= 0,
+);
+let LINE = spec("expected solid, dashed, or dotted", (value) => LINES.includes(value));
+/** @type {Record<string, StyleSpec>} */
+let BORDER = { Width: POINTS, Style: LINE, Color: COLOR };
+for (let side of SIDES) {
+  STYLES["padding" + side] = POINTS;
+  IMAGE_STYLES.push("padding" + side);
+  for (let part of BORDER_PARTS) {
+    let name = "border" + side + part;
+    STYLES[name] = BORDER[part];
+    IMAGE_STYLES.push(name);
+  }
+}
+let FLOW = ["spaceBefore", "spaceAfter"];
+for (let name of FLOW) {
+  STYLES[name] = POINTS;
+  IMAGE_STYLES.push(name);
+}
 // One check for both the validating traversal and the compile path: an error
 // message for a declaration, or null when it is acceptable (expressions defer
 // to render).
@@ -62,6 +88,29 @@ export let checkStyle = (name, value) => {
   return rule.ok(value) ? null : rule.msg;
 };
 
+// A border side is width, style, and colour together, or none. Incomplete
+// literals are a definition error; a side that still has an expression defers
+// to render, where an incomplete result contributes nothing rather than
+// becoming a solid black stroke. Per-name checks run first; a side that
+// already has a located problem is left alone so the author sees one cause.
+/** @type {(present: string[]) => boolean} */
+let incomplete = (present) => present.length > 0 && present.length < 3;
+/** @type {(block: any, check: (name: string, value: any) => string | null, name: string) => boolean} */
+let deferred = (block, check, name) => isExpr(block[name]) || !!check(name, block[name]);
+
+/** @type {(block: any, check?: (name: string, value: any) => string | null) => [string, string][]} */
+export let checkBorderSides = (block, check = checkStyle) => {
+  /** @type {[string, string][]} */
+  let out = [];
+  for (let side of SIDES) {
+    let names = BORDER_PARTS.map((part) => "border" + side + part);
+    let present = names.filter((name) => Object.hasOwn(block, name));
+    if (incomplete(present) && !present.some((name) => deferred(block, check, name)))
+      out.push([present[0], "border" + side + " needs width, style, and color together"]);
+  }
+  return out;
+};
+
 // The same check narrowed to a subset of the vocabulary, so a declaration a
 // node cannot wear is refused as pointedly as an unknown name rather than
 // silently doing nothing. A node that takes part of the vocabulary names the
@@ -79,3 +128,31 @@ export let checkImageStyle = narrowed(IMAGE_STYLES, "an image");
 // "a report default" rather than the key's name: the key is `style` like every
 // other one, so the message has to say which `style` refused it.
 export let checkReportStyle = narrowed(REPORT_STYLES, "a report default");
+
+// Flow spacing is a band-item pad. A table cell, a row box, and a split slot
+// have no flow, so the names are refused there the way a text declaration is
+// on an image (docs/adr/0037).
+/** @type {Record<string, true>} */
+let FLOW_NAMES = Object.fromEntries(FLOW.map((name) => [name, true]));
+/**
+ * @type {(names: Record<string, true>, check: (name: string, value: any) => string | null, subject: string) =>
+ *   (name: string, value: any) => string | null}
+ */
+let withoutNames = (names, check, subject) => (name, value) =>
+  Object.hasOwn(names, name)
+    ? 'style "' + name + '" does not apply to ' + subject
+    : check(name, value);
+/**
+ * @type {(check: (name: string, value: any) => string | null, subject: string) =>
+ *   (name: string, value: any) => string | null}
+ */
+let withoutFlow = (check, subject) => withoutNames(FLOW_NAMES, check, subject);
+
+export let checkCellStyle = withoutFlow(checkStyle, "a table cell");
+export let checkSlotStyle = withoutFlow(checkStyle, "a split slot");
+export let checkSlotImageStyle = withoutFlow(checkImageStyle, "a split slot");
+// A row box has no cell value, so `format` is refused there the way flow
+// spacing is — it is a presentation of a value, not of a band of cells.
+/** @type {Record<string, true>} */
+let ROW_NAMES = { ...FLOW_NAMES, format: true };
+export let checkRowStyle = withoutNames(ROW_NAMES, checkStyle, "a table row");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -51,7 +51,7 @@
         "sjabloon",
         "padvinder"
       ],
-      "limit": "9 kB"
+      "limit": "10 kB"
     }
   ],
   "engines": {