quario 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-03
+
+### Changed
+
+- **`format: "date"` now reads a date string, not only a `Date`.** A JSON
+  document has no date type, so the kind could not be reached from parsed
+  data without reviving every date field by hand first. It now revives two
+  forms itself: a calendar date `2026-08-14`, and a timestamp naming its
+  offset (`2026-08-14T12:30:00Z` or `+02:00`). **This changes existing
+  output**: a cell declaring the kind over `"2026-08-14"` rendered
+  `2026-08-14` and now renders `14/8/2026` under an `en-IE` instance. A
+  zoneless `2026-08-14T00:00:00` is not read — it means local time, so it
+  would present a different day per machine — and neither is a loose
+  `14/8/2026`, a partial `2026-08`, a lowercase `t`/`z`, or a day that does
+  not exist. Anything unread renders as authored, as before.
+
+  The revival is the `Date` a host would have injected, timezone included: a
+  calendar date is UTC midnight, so under a western instance timezone it
+  presents as the previous day, exactly as `new Date("2026-08-14")` does.
+  Only `date` revives — `number`, `currency` and `percent` never read a
+  string, because JSON already carries numbers — and epoch milliseconds stay
+  a number under every kind.
+
+- **`typed(tokens, kind?)` takes the cell's `format` kind.** Passing `"date"`
+  opts into the same revival, for consumers that write typed cells. The
+  one-argument call is unchanged.
+
+### Fixed
+
+- **The TypeScript declarations accept the box.** The per-side `padding*` and
+  `border*` names, and the table's `detail.header`, were validated by the
+  engine from 0.3.0 but were missing from the shipped declarations, so a
+  report declaring the padding or the border sides that release introduced
+  was rejected by the compiler as an unknown property and needed a cast to
+  get past it. They now type exactly as the engine reads them, on a band
+  image's `style` as well. Four names come with them, for annotating your own
+  helpers: `LineStyle` (`"solid" | "dashed" | "dotted"`), beside `Align` and
+  `FormatKind`; `TableHeaderBox`, the type of `detail.header`; and
+  `BoxDeclarations` with `Side`, the per-side names as one type, which
+  `StyleDeclarations` was built from without being nameable. Nothing
+  about rendering changes: a report that compiled through a cast produces the
+  same output without one.
+
 ## [0.3.0] - 2026-09-02
 
 ### Added
@@ -16,20 +59,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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`).
+  nothing.
 
 - **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`).
+  next band is refused.
 
 - **`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`).
+  or strip top; page-band items keep it. Leading and inset stay cut.
 
 - **Per-side padding and border on the closed style vocabulary.**
   `paddingTop` / `Right` / `Bottom` / `Left` (points, ≥ 0) and, per side,
@@ -50,7 +92,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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`).
+  The stream yields one `total-row` per emitted row.
 
 - **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;

package/lib/format.js

@@ -8,7 +8,7 @@
  * 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";
+import { finiteDate, finiteNum, reviveDate } from "./stream.js";
 /** @type {(options: any) => string} */
 let localeOf = (options) => options?.locale || "en-US";
 /** @type {(options: any) => string} */
@@ -31,11 +31,18 @@ let asMoney = (value, locale, options) => {
   if (!finiteNum(value) || !currency) return;
   return new Intl.NumberFormat(locale, { style: "currency", currency }).format(value);
 };
+// A string in an accepted RFC 3339 form revives to the Date a host would have
+// injected, then presents like any other Date — including in the instance's
+// timezone, so a calendar date under a western zone presents as the day
+// before, exactly as an injected `new Date("2026-08-14")` does today. The two
+// spellings never disagree, which is the point (ADR 0041).
 /** @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)
+let asDate = (value, locale, options) => {
+  let date = finiteDate(value) ? value : reviveDate(value);
+  return date
+    ? new Intl.DateTimeFormat(locale, { timeZone: zoneOf(options) }).format(date)
     : undefined;
+};
 
 /** @type {Record<string, (value: any, locale: string, options: any) => string | undefined>} */
 let KINDS = { number: asNumber, currency: asMoney, percent: asPercent, date: asDate };

package/lib/index.d.ts

@@ -28,6 +28,40 @@ export type JsonValue =
   | JsonValue[]
   | { [key: string]: JsonValue };
 
+/**
+ * The four sides, as the key fragments the names are built from. Not a value an
+ * author ever writes: only the pieces `padding<Side>` and `border<Side><Part>`
+ * are spelled out of it, and it is exported so the box below can be named.
+ */
+export type Side = "Top" | "Right" | "Bottom" | "Left";
+
+/** The line a border side is drawn with. */
+export type LineStyle = "solid" | "dashed" | "dotted";
+
+/**
+ * The box: padding and border per side. Written as a mapping over the four
+ * sides, the way the runtime builds the names, so a side can never be spelled
+ * out in one place and forgotten in another.
+ *
+ * A border side is width, style, and colour together, or none — an incomplete
+ * literal side is a definition error the traversal reports, which no type can
+ * state. Padding is not flow spacing: `spaceBefore` / `spaceAfter` are blank
+ * space *between* items, and live on the vocabulary below.
+ */
+export type BoxDeclarations = {
+  /** Inset on that side, in points (>= 0). */
+  [S in Side as `padding${S}`]?: ExpressionValue<number>;
+} & {
+  /** Stroke width on that side, in points (>= 0). `0` is a complete side that draws nothing. */
+  [S in Side as `border${S}Width`]?: ExpressionValue<number>;
+} & {
+  /** Line style of that side. */
+  [S in Side as `border${S}Style`]?: ExpressionValue<LineStyle>;
+} & {
+  /** Stroke color of that side, `#rgb`/`#rrggbb`. */
+  [S in Side as `border${S}Color`]?: ExpressionValue<string>;
+};
+
 /**
  * The closed, target-neutral style vocabulary. Literal values are validated
  * strictly (unknown names and mistyped literals are definition errors);
@@ -36,7 +70,7 @@ export type JsonValue =
  * its own formatting model (the HTML target to inline CSS, the PDF target to
  * faces, points, and rects).
  */
-export interface StyleDeclarations {
+export interface StyleDeclarations extends BoxDeclarations {
   /** `'sans'` | `'serif'` | `'mono'`, or an embedded font family name. */
   family?: ExpressionValue<string>;
   /** Font size in points. */
@@ -87,14 +121,15 @@ export interface TextItem extends Cell {
 export type ImageFit = "natural" | "width";
 
 /**
- * The declarations an image item accepts. The rest of the vocabulary describes
- * text, which an image does not have, so any other name on one is a definition
- * error. A narrowing of the one vocabulary rather than a second list of its
- * own, so the two cannot drift.
+ * The declarations an image item accepts: the box, plus the four names that
+ * are not about text. The rest of the vocabulary describes text, which an
+ * image does not have, so any other name on one is a definition 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" | "spaceBefore" | "spaceAfter"
+  "background" | "align" | "spaceBefore" | "spaceAfter" | keyof BoxDeclarations
 >;
 
 /**
@@ -169,7 +204,17 @@ export interface TotalRow {
   style?: StyleDeclarations;
 }
 
+/**
+ * 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
+ * header cells on every page continuation.
+ */
+export interface TableHeaderBox {
+  style?: StyleDeclarations;
+}
+
 export interface TableDetail {
+  header?: TableHeaderBox;
   row?: TableRow;
   columns: [TableColumn, ...TableColumn[]];
   total?: [TotalRow, ...TotalRow[]];
@@ -657,8 +702,16 @@ export function format(
  * 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 —
+ * `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[]): number | boolean | Date | undefined;
+export function typed(
+  tokens: readonly Token[],
+  kind?: unknown,
+): number | boolean | Date | undefined;
 
 /**
  * Whether a band item's `role` names one of the report's own bands — its

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

@@ -24,6 +24,61 @@ let asTyped = (value) => {
   if (finiteDate(value)) return value;
   return undefined;
 };
+// The seam's one coercion, kept behind the declared kind (ADR 0041).
+/** @type {(value: any, kind: unknown) => Date | undefined} */
+let asDeclared = (value, kind) => (kind === "date" ? reviveDate(value) : undefined);
+
+// The two RFC 3339 forms a JSON document conventionally carries a date in:
+// a calendar date, and a timestamp that names its offset. A zoneless
+// `2026-08-14T00:00:00` is deliberately absent — ECMAScript reads it as local
+// time, so the same document would present a different day per machine, which
+// ADR 0025 rules out. Uppercase `T`/`Z` only, for the same reason: the lower
+// case RFC 3339 permits is outside the ECMAScript format and parses at the
+// engine's discretion.
+let RFC3339 =
+  /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2})))?$/;
+
+/** @type {(year: string, month: string) => number} */
+let monthLength = (year, month) => new Date(Date.UTC(+year, +month, 0)).getUTCDate();
+// An absent group is the timestamp half of an optional match, not a breach.
+/** @type {(bound: [string | undefined, number, number]) => boolean} */
+let within = ([n, lo, hi]) => n === undefined || (+n >= lo && +n <= hi);
+// A non-string never matches: `exec` would coerce one, and a single-element
+// array stringifies to its element, which would revive an array as a date.
+/** @type {(value: any) => RegExpExecArray | null} */
+let rfc3339 = (value) => (typeof value === "string" ? RFC3339.exec(value) : null);
+
+/**
+ * Revive a date string the way a host would have revived it — the accepted
+ * forms are exactly those `new Date(string)` reads identically on every
+ * machine, so declaring `format: "date"` and injecting `Date` values into the
+ * render data are two spellings of one document (ADR 0041).
+ *
+ * The components are range-checked here rather than left to the parser:
+ * ECMAScript rolls an out-of-range day over (`2026-02-30` becomes 2 March)
+ * where a date that does not exist should revive nothing at all. A leap
+ * second (`:60`) is refused on the same ground — RFC 3339 admits it and
+ * ECMAScript does not, so it would be a second rollover.
+ *
+ * @type {(value: any) => Date | undefined}
+ */
+export let reviveDate = (value) => {
+  let parts = rfc3339(value);
+  if (!parts) return undefined;
+  let [, year, month, day, hour, minute, second, offsetHour, offsetMinute] = parts;
+  /** @type {[string | undefined, number, number][]} */
+  let bounds = [
+    [month, 1, 12],
+    [day, 1, monthLength(year, month)],
+    [hour, 0, 23],
+    [minute, 0, 59],
+    [second, 0, 59],
+    [offsetHour, 0, 23],
+    [offsetMinute, 0, 59],
+  ];
+  let date = bounds.every(within) ? new Date(value) : new Date(NaN);
+  return finiteDate(date) ? date : undefined;
+};
 
 /**
  * The typed-cell seam: exactly one value token holding a finite number, a
@@ -31,13 +86,23 @@ let asTyped = (value) => {
  * including a lone null, matching the display-text treatment everywhere
  * else — reports `undefined` and joins to text.
  *
+ * Passing the cell's declared `format` kind opts into the one coercion the
+ * seam performs: under `"date"`, a string in either accepted RFC 3339 form
+ * revives to the `Date` it names. The gate is the declaration, and the kind
+ * is `date` alone, because a date is the one type a JSON document cannot
+ * carry — a number arrives as a number, so no other kind has anything to
+ * revive (ADR 0041). Callers that read no style omit the argument and see
+ * the seam exactly as it was.
+ *
  * @param {any[]} tokens A cell's tokens.
+ * @param {unknown} [kind] The cell's resolved `format` declaration.
  * @returns {number | boolean | Date | undefined} The native value, if any.
  */
-export function typed(tokens) {
+export function typed(tokens, kind) {
   let [token] = tokens;
   if (tokens.length !== 1 || !("value" in token)) return undefined;
-  return asTyped(token.value);
+  // `??` and not `||`: a boolean cell's own `false` is a typed value.
+  return asTyped(token.value) ?? asDeclared(token.value, kind);
 }
 
 // The report's own bands, by the role their items wear (CONTEXT.md, "Band").

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A tiny, runtime-neutral report engine — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",