quario 0.1.0 → 0.3.0

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,12 +45,20 @@ 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`. */
   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 {
@@ -61,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;
@@ -82,7 +92,16 @@ 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.
+ * 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
@@ -101,8 +120,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;
@@ -121,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 {
@@ -163,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 {
@@ -178,7 +228,17 @@ export interface ReportSchema {
   aggregates?: Record<string, ReducerSpec>;
   /** Running accumulators, read as `run.<name>` on detail rows. */
   run?: Record<string, ReducerSpec>;
-  header?: Item[];
+  /**
+   * 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;
+  /**
+   * 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
@@ -216,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. */
@@ -246,6 +312,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[r].cells[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 +345,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
@@ -281,11 +362,23 @@ 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 {
   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 +390,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 +403,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 +443,11 @@ 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 }[];
+  /** The header-row box from `detail.header`, when declared. */
+  style?: Record<string, unknown>;
 }
 
 export interface RowEvent {
@@ -342,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 {
@@ -356,6 +476,8 @@ export type ReportEvent =
   | ReportStartEvent
   | ItemEvent
   | ImageEvent
+  | SplitStartEvent
+  | SplitEndEvent
   | GroupStartEvent
   | GroupEndEvent
   | TableStartEvent
@@ -364,10 +486,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 +528,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 +558,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 +568,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 +603,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 +628,31 @@ 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;
+
+/**
+ * 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 —