quario 0.4.0 → 0.6.0

package/lib/band-height.js

@@ -0,0 +1,123 @@
+/**
+ * The band-height rule: what a report header's declared `height` forbids of
+ * whatever follows its box (docs/adr/0038, docs/adr/0052).
+ *
+ * A pinned header ends at a fixed offset from the page top, so the band under
+ * it starts there and an authored lead would push it off the pin. The rule is
+ * therefore about one item — the first occupying item of the band that follows
+ * — and it is enforced twice, because which item that is can be a fact about
+ * the document or a fact about the render. `plan.js` refuses the ones the
+ * document settles; `index.js` refuses the rest as the stream produces them.
+ * Both read this file, so the two never disagree about what a lead is or which
+ * node a fault names.
+ *
+ * The traversal half is a guard the descent carries rather than a second walk
+ * of the schema: `plan.js` offers it each band as it compiles it, in the order
+ * it already visits them, so a fault lands in the documented key order beside
+ * every other problem and the group chain is read once
+ * (docs/agents/semantics.md, "One traversal, read two ways").
+ */
+
+import { isExpr, positivePts } from "./style.js";
+
+/**
+ * A lead: authored flow spacing before an item that a target would actually
+ * paint. A positive number of points — the style vocabulary's own shape, less
+ * the zero it admits, which is the value the pin asks for. `spaceOf` in
+ * @quario/layout applies the same test; @quario/html's `isPad` is deliberately
+ * wider, admitting the `0` that is harmless to emit as CSS. They are restated
+ * per package on purpose: the engine is their peer dependency, so it cannot
+ * import either.
+ *
+ * @type {(n: any) => boolean}
+ */
+export let isLead = positivePts;
+
+/** The one wording, so both enforcement sites report the same sentence. */
+export let LEAD_REFUSED = "must be 0 after a height-declared header";
+
+/**
+ * The path of the key a lead fault names: the offending item's own
+ * `style.spaceBefore`.
+ *
+ * @param {string} path The item definition's schema path.
+ * @returns {string} The located key.
+ */
+export let leadPath = (path) => path + ".style.spaceBefore";
+
+/**
+ * An occupancy the document leaves to the data: a `visible` written as an
+ * expression, or an image, whose bytes are expression-only and whose event is
+ * absent when its `source` yields nothing (SCHEMA.md, "Event stream"). Neither
+ * is a defect — they are how an author writes an optional item — but they mean
+ * the traversal cannot say which item comes first, so it says nothing rather
+ * than guessing (docs/adr/0052).
+ *
+ * @type {(def: any) => boolean}
+ */
+let dataDecides = (def) => isExpr(def?.visible) || def?.type === "image";
+
+/**
+ * The first item of a band the document settles as occupying, `undefined` when
+ * only the render settles it, and null for a band settled to occupy nothing.
+ *
+ * @type {(list: any, path: string) => { def: any, path: string } | undefined | null}
+ */
+let firstOccupying = (list, path) => {
+  if (!Array.isArray(list)) return null;
+  let i = list.findIndex((def) => def?.visible !== false);
+  if (i < 0) return null;
+  return dataDecides(list[i]) ? undefined : { def: list[i], path: path + "[" + i + "]" };
+};
+
+/**
+ * The guard the traversal carries while it descends.
+ *
+ * Which band sits under the pinned box is partly the document's answer and
+ * partly the data's. With rows, every group level opens nested before any
+ * detail row, so the first group header carrying an occupying item is that
+ * band, and `detail` is it only when no group header has one — which is the
+ * order `bandOf` already compiles them in, so `body` takes the first band that
+ * says anything and ignores the rest. With no rows the `empty` band replaces
+ * all of it, so it is an independent candidate that `instead` judges on its
+ * own. Both outcomes are reachable for any report declaring both, and the
+ * author declared each, so a lead on either is refused.
+ *
+ * A table `detail` reaches neither, and needs no case of its own:
+ * `table-start` and `row` are not occupying events, and the style vocabulary
+ * refuses `spaceBefore` on a table, a table row and a table cell alike, so
+ * there is no lead a table could carry.
+ *
+ * @param {(path: string, message: string) => void} bad The traversal's collector.
+ * @returns {{ arm: (height: number | null) => void,
+ *   instead: (list: any, path: string) => void,
+ *   body: (list: any, path: string) => void }} The guard.
+ */
+export let pinGuard = (bad) => {
+  let pinned = false;
+  let settled = true;
+  /** @type {(found: { def: any, path: string } | undefined | null) => void} */
+  let refuse = (found) => {
+    if (found && isLead(found.def.style?.spaceBefore)) bad(leadPath(found.path), LEAD_REFUSED);
+  };
+  return {
+    arm: (/** @type {number | null} */ height) => {
+      pinned = height != null;
+      settled = !pinned;
+    },
+    instead: (/** @type {any} */ list, /** @type {string} */ path) => {
+      if (pinned) refuse(firstOccupying(list, path));
+    },
+    body: (/** @type {any} */ list, /** @type {string} */ path) => {
+      if (settled) return;
+      let found = firstOccupying(list, path);
+      // A band settled to occupy nothing is not the one under the box, so the
+      // descent keeps looking; one only the render settles ends the search
+      // without a verdict, because whether the band below is next is exactly
+      // what it left open.
+      if (found === null) return;
+      settled = true;
+      refuse(found);
+    },
+  };
+};

package/lib/format.js

@@ -1,66 +1,174 @@
 /**
  * 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.
+ * Targets import this instead of each other: the stream keeps the resolved
+ * declaration 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. Under the `currency` kind a cell's own `style.currency` names the
+ * denomination and beats the instance's default code.
  *
  * 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).
+ *
+ * The kind, its digit count, and a date's form all come off the one resolved
+ * declaration `formatOf` answers — the same object the stream carries and the
+ * XLSX target builds its number formats from — so a cell shows the same
+ * digits wherever it is rendered (docs/adr/0054, docs/adr/0056). A kind that
+ * carries no count presents nothing here and the caller falls back to
+ * `display()`.
  */
+import { currencyOf, formatOf } from "./style.js";
 import { finiteDate, finiteNum, reviveDate } 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;
+// Building an `Intl` formatter costs about 22 µs; using one costs 0.3 µs. A
+// report presents cell after cell from a handful of distinct formats, so
+// constructing per token spent 3.2 s on a hundred thousand presented cells
+// where 0.2 s does (a report of mixed currencies rendered to HTML), and the
+// formatters are memoised.
+//
+// **The key is everything the formatter is made from**, and it is values
+// rather than an object identity because no identity survives both paths: a
+// literal style block folds to one frozen declaration every cell shares, while
+// a block holding an `=` expression resolves a fresh one per cell (`plan.js`).
+// Keying on values hits in both. Get a piece of it wrong and one cell presents
+// under another's formatter -- a USD row reading as EUR -- which is the
+// failure `test/semantics.test.js` pins a pair for, one piece at a time. Each
+// pair must differ in **only** the piece it is there for: EUR against JPY
+// would prove nothing about the code, because their digit counts already
+// differ and that piece would separate them on its own.
+//
+// **The cap is the part to read**, because the key space is not the host's to
+// bound. A currency code reaches this from author data through
+// `currency: "=@.ccy"`, gated only to three uppercase letters, and `digits`
+// can be an `=` result too: 17,576 codes times 21 counts is 369,000 keys for a
+// single locale. Measured at 244 bytes retained per entry, that is about 90 MB
+// held for the life of the process on data nobody vetted.
+//
+// So the map is bounded, and past the bound it is emptied rather than grown.
+// A workload presenting more distinct formats than the cap pays what it paid
+// before any of this and never more, which is the one cost that needs no
+// argument -- and it can never hand back a formatter built for another cell,
+// because clearing forgets rather than reuses.
+//
+// 2048 leaves the margin a threshold like this wants on both sides: about
+// 500 KB at the cap, against a real report reaching a small multiple of the
+// ISO codes actually in circulation, which is under two hundred. Raising it
+// costs bytes and lowering it costs rebuilt formatters; neither is a
+// correctness knob.
+//
+// Memoising a fact that cannot change within an ICU version, like
+// `fractionDigits`' own minor-units map (docs/adr/0025).
+let CAP = 2048;
+/** @type {Map<string, any>} */
+let formatters = new Map();
+// A construction that throws -- an unreadable locale, zone, or currency code
+// -- caches nothing: it reaches `format()`'s own catch, and a later cell asks
+// again rather than finding nothing sitting in the map under a good key.
+// Missing on `undefined` rather than `has()`, which is what `precision.js`
+// needs because *it* caches an absent answer; a formatter is never one.
+/** @type {(key: string, make: () => any) => any} */
+let memo = (key, make) => {
+  let formatter = formatters.get(key);
+  if (formatter !== undefined) return formatter;
+  formatter = make();
+  if (formatters.size >= CAP) formatters.clear();
+  formatters.set(key, formatter);
+  return formatter;
 };
-/** @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);
+
+// The kind leads, so a number's key can never read as a date's; the currency
+// is empty for the two kinds that wear none.
+/** @type {(locale: string, decl: any, rest?: any) => string} */
+let numberKey = (locale, decl, rest) =>
+  decl.kind + "|" + locale + "|" + decl.digits + "|" + (rest?.currency || "");
+
+/** @type {(value: any, locale: string, decl: any, rest?: any) => string | undefined} */
+let asFixed = (value, locale, decl, rest) => {
+  if (!finiteNum(value) || decl.digits === undefined) return;
+  return memo(
+    numberKey(locale, decl, rest),
+    () =>
+      new Intl.NumberFormat(locale, {
+        ...rest,
+        minimumFractionDigits: decl.digits,
+        maximumFractionDigits: decl.digits,
+      }),
+  ).format(value);
+};
+
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asNumber = (value, locale, decl) => asFixed(value, locale, decl);
+/** @type {(value: any, locale: string, decl: any) => string | undefined} */
+let asPercent = (value, locale, decl) =>
+  // `style: "percent"` multiplies by 100 and the digits count the *displayed*
+  // places, which is what Excel's `0.00%` already means too — so the count
+  // crosses to the sheet with no translation (docs/adr/0056).
+  asFixed(value, locale, decl, { style: "percent" });
+// The code the cell actually wears is what the digit count was asked about, not
+// the instance's: minor units are a property of the currency, so a row that
+// names JPY presents no decimals beside one naming EUR that presents two
+// (docs/adr/0041, docs/adr/0054).
+/** @type {(value: any, locale: string, decl: any, options: any, style: any) => string | undefined} */
+let asMoney = (value, locale, decl, options, style) => {
+  let currency = currencyOf(style, options);
+  return currency ? asFixed(value, locale, decl, { style: "currency", currency }) : undefined;
 };
 // 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) => {
+//
+// The form is Intl's own `dateStyle`, and it is always present: a declaration
+// that named none resolved to `medium` (docs/adr/0056). This is the half that
+// does not converge — the worksheet approximates it (CONTEXT.md, "Form").
+// `date` leads for the same reason the number kinds do, so the two key shapes
+// live beside each other and "one piece at a time" is auditable in one place.
+/** @type {(locale: string, decl: any, zone: string) => string} */
+let dateKey = (locale, decl, zone) => "date|" + locale + "|" + decl.form + "|" + zone;
+
+/** @type {(value: any, locale: string, decl: any, options: any) => string | undefined} */
+let asDate = (value, locale, decl, options) => {
   let date = finiteDate(value) ? value : reviveDate(value);
-  return date
-    ? new Intl.DateTimeFormat(locale, { timeZone: zoneOf(options) }).format(date)
-    : undefined;
+  if (!date) return;
+  let zone = zoneOf(options);
+  return memo(
+    dateKey(locale, decl, zone),
+    () => new Intl.DateTimeFormat(locale, { timeZone: zone, dateStyle: decl.form }),
+  ).format(date);
 };
 
-/** @type {Record<string, (value: any, locale: string, options: any) => string | undefined>} */
+/** @type {Record<string, (value: any, locale: string, decl: any, options: any, style: any) => string | undefined>} */
 let KINDS = { number: asNumber, currency: asMoney, percent: asPercent, date: asDate };
 
 /**
+ * The helper takes the whole resolved `style`, not just the declaration, so
+ * the question "which declarations does presentation read?" is answered here
+ * once rather than once per target (docs/adr/0014).
+ *
  * @param {unknown} value The interpolation's pre-stringify token.
- * @param {unknown} kind A resolved `format` declaration.
+ * @param {{ format?: unknown, currency?: unknown } | null} [style] The cell's
+ *   resolved style block: its `format` declaration, and its own `currency`
+ *   code when it declares one.
  * @param {{ locale?: string, currency?: string, timeZone?: string } | null} [options]
- *   The instance's locale, currency code, and timezone.
+ *   The instance's locale, default 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;
+export function format(value, style, options) {
+  // A style the stream resolved already carries its declaration whole; one a
+  // host built by hand may still hold the shorthand, so it is widened here
+  // rather than refused. No own-key guard on the lookup: `formatOf` answers a
+  // kind only from the closed vocabulary, which is exactly `KINDS`' own keys,
+  // so nothing an `=` expression resolved to can reach this table.
+  let decl = formatOf(style, options);
+  if (!decl) return;
   try {
-    return present(value, localeOf(options), options);
+    return KINDS[decl.kind](value, localeOf(options), decl, options, style);
   } catch {
     return;
   }