quario 0.4.0 → 0.6.0

package/lib/style.js

@@ -1,24 +1,61 @@
 /**
- * The closed style vocabulary, as the traversal checks it: target-neutral names
- * with typed literal values. Unknown names and mistyped literals are definition
- * errors; `=` results stay lenient at render. Each target maps these names to
- * its own formatting model, and nothing here knows about any of them.
+ * The closed style vocabulary — target-neutral names with typed literal values —
+ * and the resolutions the event stream is defined in terms of. Two things, and
+ * the split between them is the file's organising claim.
  *
- * `finite`/`HEX` are restated per target on purpose: those coercions are each
- * target's own edge, never shared engine code — unlike the stream rules
- * (`typed`), which every target reads from `./stream.js`.
+ * The **checks** are what the traversal runs: unknown names and mistyped
+ * literals are definition errors; `=` results stay lenient at render.
+ *
+ * The **resolutions** are what a declaration means before any target sees it.
+ * A row's box is the one there is (SCHEMA.md, "Style declarations"): it says
+ * what the document means rather than what a surface paints, so every target
+ * is handed the answer instead of reaching its own. That is the same line
+ * `./stream.js` sits on, and the opposite side of it from `finite`/`HEX`,
+ * which are restated per target on purpose because a coercion is each target's
+ * own edge.
+ *
+ * Past those, each target maps these names to its own formatting model, and
+ * nothing here knows about any of them.
  */
+import { record } from "./names.js";
+import { defaultDigits } from "./precision.js";
 /** @type {(value: any) => boolean} */
 let finite = (value) => typeof value === "number" && Number.isFinite(value);
+/**
+ * A positive number of points: `POINTS` below, less the zero it admits. The
+ * vocabulary's own shape rather than a second numeric test, so a future
+ * loosening of what a measurement may be reaches every reader of it.
+ *
+ * @type {(value: any) => boolean}
+ */
+export let positivePts = (value) => finite(value) && value > 0;
 let HEX = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
 /** @type {(value: any) => boolean} */
 let isHex = (value) => typeof value === "string" && HEX.test(value);
-/** @typedef {{ ok: (value: any) => boolean, msg: string }} StyleSpec */
+// A currency code's *shape*, not the ISO 4217 registry: `Intl` owns the real
+// list, so a well-formed but unknown code fails soft at presentation like any
+// other kind that does not apply. Shipping the registry would buy one
+// diagnostic at the price of a data file that goes stale (docs/adr/0041).
+let CODE = /^[A-Z]{3}$/;
+/** @type {(value: any) => boolean} */
+let isCode = (value) => typeof value === "string" && CODE.test(value);
+// A declaration checks to a message or to null, and `spec` is the sugar for
+// the ordinary case: one predicate, one wording. `format` is the one entry
+// written out longhand, because a value with structure of its own has four
+// distinct mistakes -- unknown kind, unknown option, an option the kind does
+// not take, a count out of range -- and they cannot be one wording. Same
+// bargain a border side already gets a checker of its own for, rather than
+// bending the table around it.
+/** @typedef {{ check: (value: any) => string | null }} StyleSpec */
 /** @type {(msg: string, ok: (value: any) => boolean) => StyleSpec} */
-let spec = (msg, ok) => ({ ok, msg });
+let spec = (msg, ok) => ({ check: (value) => (ok(value) ? null : msg) });
 let COLOR = spec("expected a #rgb or #rrggbb color", isHex);
-let FLAG = spec("expected a boolean", (value) => typeof value === "boolean");
+/** @type {(value: any) => boolean} */
+let isFlag = (value) => typeof value === "boolean";
+let FLAG = spec("expected a boolean", isFlag);
 let ALIGNMENTS = ["left", "center", "right"];
+// "middle", not "center": that word is already the horizontal one.
+let VALIGNMENTS = ["top", "middle", "bottom"];
 let LINES = ["solid", "dashed", "dotted"];
 let SIDES = ["Top", "Right", "Bottom", "Left"];
 let BORDER_PARTS = ["Width", "Style", "Color"];
@@ -40,7 +77,7 @@ let STYLES = {
     "expected a font family name",
     (value) => typeof value === "string" && value.length > 0,
   ),
-  size: spec("expected a positive number of points", (value) => finite(value) && value > 0),
+  size: spec("expected a positive number of points", positivePts),
   bold: FLAG,
   italic: FLAG,
   underline: FLAG,
@@ -49,9 +86,127 @@ 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)),
+  valign: spec("expected top, middle, or bottom", (value) => VALIGNMENTS.includes(value)),
+  format: { check: (value) => checkFormat(value) },
+  currency: spec("expected a three-letter ISO 4217 code", isCode),
 };
 let FORMATS = ["number", "currency", "percent", "date"];
+
+// --- the format declaration ---------------------------------------------------
+//
+// `format` is a kind, optionally carrying one modifier that kind understands
+// (docs/adr/0056). The kinds that present a number take a digit count; `date`
+// takes a form. That is the whole rule, and the two halves below -- the check
+// and the resolution -- are the only places it is spelled out.
+
+// The four names are Intl's `dateStyle`, and CONTEXT.md's "Form" is the term.
+// A bare `date` means `medium`: the fifth shape Intl's no-option default used
+// to produce was nameable by nothing, so an author held one behaviour more
+// than the vocabulary described (docs/adr/0056).
+let FORMS = ["short", "medium", "long", "full"];
+let DEFAULT_FORM = "medium";
+// Both edges honour every count in this range: Intl guarantees it and an
+// Excel number format can spell it. A wider one would let an author name a
+// precision only one target could present, which is the divergence
+// docs/adr/0054 closed.
+let MAX_DIGITS = 20;
+// Which modifier each kind takes, and the whole answer to "does this kind
+// understand this option?". The three number kinds share one, so the table is
+// keyed by kind rather than by option -- a kind is what an author names first.
+/** @type {Record<string, string>} */
+let MODIFIERS = { number: "digits", percent: "digits", currency: "digits", date: "form" };
+let KINDS_MSG = "expected number, currency, percent, or date";
+/** @type {(value: any) => boolean} */
+let isDigits = (value) =>
+  Number.isInteger(value) && value >= 0 && /** @type {number} */ (value) <= MAX_DIGITS;
+/** @type {Record<string, (value: any) => string | null>} */
+let MODIFIER_CHECKS = {
+  digits: (value) =>
+    isDigits(value) ? null : "expected a whole number of digits from 0 to " + MAX_DIGITS,
+  form: (value) => (FORMS.includes(value) ? null : "expected short, medium, long, or full"),
+};
+/**
+ * The `format` vocabulary as data, for a tool that offers it rather than
+ * checks it -- the editor's style rail -- so no surface keeps a copy of the
+ * kinds, the forms, the default form or the digit ceiling that has to be told
+ * about a change here. `STYLE_NAMES` is the same bargain one level up.
+ */
+export let FORMAT_VOCABULARY = Object.freeze({
+  kinds: Object.freeze([...FORMATS]),
+  forms: Object.freeze([...FORMS]),
+  // Which modifier each kind takes, so a surface offering the pair does not
+  // have to know that three kinds share `digits` and `date` does not.
+  modifiers: Object.freeze({ ...MODIFIERS }),
+  defaultForm: DEFAULT_FORM,
+  maxDigits: MAX_DIGITS,
+});
+
+/**
+ * The kind a declaration names -- the shorthand string, or an object's `kind`
+ * -- or nothing when it names none this vocabulary knows. An own-key read,
+ * the guard every name from a document gets: a `kind` resolved off
+ * `Object.prototype` is not a kind.
+ *
+ * Exported because the typed-cell seam asks the same question and only that
+ * question: `typed()` gates its one coercion on the kind being `date`, and
+ * resolving a whole declaration to read one field off it would allocate per
+ * cell for nothing (`./stream.js`).
+ *
+ * @type {(value: any) => string | undefined}
+ */
+export let kindOf = (value) => {
+  let named = record(value) && Object.hasOwn(value, "kind") ? value.kind : value;
+  return FORMATS.includes(named) ? named : undefined;
+};
+
+// Which of the three refusals a value that named no kind earns. An object got
+// as far as being read and failed on one key; a string named a kind that is
+// not one; anything else is not a declaration at all.
+/** @type {(value: any) => string} */
+let noKind = (value) => {
+  if (record(value)) return KINDS_MSG + ' on the object\'s "kind"';
+  return typeof value === "string" ? KINDS_MSG : KINDS_MSG + ", or an object naming one";
+};
+
+// The two refusals are worded differently on purpose: a name no kind takes is
+// a typo, while a name another kind takes is a mismatch, and naming the kind
+// that refused it is what turns the diagnostic into the fix.
+/** @type {(name: string, kind: string) => string} */
+let refuseOption = (name, kind) =>
+  Object.hasOwn(MODIFIER_CHECKS, name)
+    ? 'format option "' + name + '" does not apply to ' + kind
+    : 'unknown format option "' + name + '"';
+
+/**
+ * Every key past `kind`, against the one option this kind understands.
+ *
+ * @type {(value: any, kind: string) => string | null}
+ */
+let checkOptions = (value, kind) => {
+  let modifier = MODIFIERS[kind];
+  let stray = Object.keys(value).find((name) => name !== "kind" && name !== modifier);
+  if (stray !== undefined) return refuseOption(stray, kind);
+  return Object.hasOwn(value, modifier) ? MODIFIER_CHECKS[modifier](value[modifier]) : null;
+};
+
+/**
+ * A `format` declaration's own check: a message naming which of the four
+ * mistakes this is, or null. The kind is settled first, because every other
+ * answer depends on it -- an option is only wrong *for a kind*.
+ *
+ * @type {(value: any) => string | null}
+ */
+let checkFormat = (value) => {
+  let kind = kindOf(value);
+  if (kind === undefined) return noKind(value);
+  return record(value) ? checkOptions(value, kind) : null;
+};
+
+// The two declarations that present a *value* rather than describe a surface:
+// the kind, and -- under the `currency` kind -- what the number is denominated
+// in. They share every site, so the places that refuse one refuse both from
+// this list rather than from two lists that have to be compared (ADR 0041).
+let VALUE_NAMES = ["format", "currency"];
 let POINTS = spec(
   "expected a non-negative number of points",
   (value) => finite(value) && value >= 0,
@@ -73,19 +228,39 @@ for (let name of FLOW) {
   STYLES[name] = POINTS;
   IMAGE_STYLES.push(name);
 }
+// The vocabulary as a list, in the order SCHEMA.md's table reads it: the text
+// names, the flow, then the box one part at a time across the four sides. A
+// tool that offers the vocabulary (the editor's style rail) imports this
+// rather than keeping a copy that has to be told about every new name.
+/** @type {readonly string[]} */
+// The box half of the vocabulary, generated once from the same two tables the
+// checks read. `isBoxName` is the only place the question "does this name
+// belong to the box?" is answered, so a name that does not start with
+// `padding` or `border` could join without every asker being told separately.
+let BOX_NAMES = [
+  ...SIDES.map((side) => "padding" + side),
+  ...BORDER_PARTS.flatMap((part) => SIDES.map((side) => "border" + side + part)),
+];
+let BOX = new Set(BOX_NAMES);
+/** @type {(name: string) => boolean} */
+export let isBoxName = (name) => BOX.has(name);
+export let STYLE_NAMES = Object.freeze([
+  ...Object.keys(STYLES).filter((name) => !FLOW.includes(name) && !isBoxName(name)),
+  ...FLOW,
+  ...BOX_NAMES,
+]);
 // 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).
 /** @type {(value: any) => boolean} */
-let isExpr = (value) => typeof value === "string" && value[0] === "=";
+export let isExpr = (value) => typeof value === "string" && value[0] === "=";
 /** @type {(name: string, value: any) => string | null} */
 export let checkStyle = (name, value) => {
   // Own-key lookup: a declaration named after an Object.prototype member
   // (`toString`, `constructor`) is unknown, not an inherited function.
   if (!Object.hasOwn(STYLES, name)) return 'unknown style "' + name + '"';
   if (isExpr(value)) return null;
-  let rule = STYLES[name];
-  return rule.ok(value) ? null : rule.msg;
+  return STYLES[name].check(value);
 };
 
 // A border side is width, style, and colour together, or none. Incomplete
@@ -132,8 +307,10 @@ 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 {(names: string[]) => Record<string, true>} */
+let nameSet = (names) => Object.fromEntries(names.map((name) => [name, true]));
 /** @type {Record<string, true>} */
-let FLOW_NAMES = Object.fromEntries(FLOW.map((name) => [name, true]));
+let FLOW_NAMES = nameSet(FLOW);
 /**
  * @type {(names: Record<string, true>, check: (name: string, value: any) => string | null, subject: string) =>
  *   (name: string, value: any) => string | null}
@@ -150,9 +327,297 @@ 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.
+// `valign` is legal exactly where a box has height it did not ask for
+// (CONTEXT.md "Box": slack). A slot's box is the split's height, so a slot --
+// text or image -- reads it; a band image's box is its own, so it does not.
+// That is the one name an image accepts in a slot and nowhere else, the same
+// shape of reason `width` reaches an item only there (docs/adr/0029).
+let SLOT_IMAGE_STYLES = [...IMAGE_STYLES, "valign"];
+export let checkSlotImageStyle = withoutFlow(
+  narrowed(SLOT_IMAGE_STYLES, "an image"),
+  "a split slot",
+);
+// A stacked text item's box is exactly its content and padding: no slack, so
+// `valign` is refused rather than left unread.
+/** @type {Record<string, true>} */
+let STACKED_NAMES = { valign: true };
+export let checkItemStyle = withoutNames(STACKED_NAMES, checkStyle, "a stacked item");
+// A row box has no cell value, so the value names are refused there the way
+// flow spacing is — they are a presentation of a value, not of a band of cells.
 /** @type {Record<string, true>} */
-let ROW_NAMES = { ...FLOW_NAMES, format: true };
+let ROW_NAMES = nameSet([...FLOW, ...VALUE_NAMES]);
 export let checkRowStyle = withoutNames(ROW_NAMES, checkStyle, "a table row");
+
+// --- resolution --------------------------------------------------------------
+
+// A resolved `=` result the vocabulary rejects, judged once where every style
+// block resolves rather than at each surface that would read it. What the
+// declaration falls back *to* decides what becomes of it, and that question
+// partitions the vocabulary three ways -- omitted, kept, voided. The argument
+// for each is docs/adr/0055; what is restated here is only which is which, and
+// why the two exceptions cannot be folded into the general rule.
+//
+// A literal never reaches here: `checkStyle` already refused it at compile, so
+// only an `=` entry is ever guarded.
+//
+// `format` then takes one more step that no other name needs, below: whatever
+// survives is **resolved**, the shorthand widened and the kind's own answer
+// filled in, because what crosses the stream is the declaration with its digit
+// count or its form already on it (docs/adr/0056).
+
+// The sentinel a failed result becomes when its name is one the engine omits.
+// A symbol, so nothing an expression can evaluate to is ever equal to it --
+// every value that reaches here came from author data or a `funcs` return, and
+// this came from neither. It is the one piece of this file the compiler has to
+// know, because writing the resolved block is its side of the seam; which name
+// gets which rule stays here.
+export let SKIP = Symbol("skip");
+
+/**
+ * Wrap a style entry's compiled `=` result in the rule its name answers to.
+ *
+ * **Omitted** is the general rule and needs no branch: the key is never
+ * written, so the layer below stands. That is what the spec means by
+ * "contributes nothing, same as omit" (SCHEMA.md, "Style declarations") -- a
+ * report-header item whose `bold` returns `1`, or whose `size` returns
+ * `"big"`, keeps its band-role bold and its band-role size rather than losing
+ * them to a value no target can read. It is the rule for the box too: side
+ * ownership is settled over the names a block declares, before any of this
+ * resolves, so dropping a rejected `borderTopColor` cannot hand the cell its
+ * row's other two (docs/adr/0056).
+ *
+ * **Voided** is `currency` alone. Its fallback is not the layer below but the
+ * instance's own code, so omitting would present one denomination's money
+ * under another's name -- the one failure louder than no formatting at all.
+ * `null` keeps the cell's answer, which nothing can present, so the cell drops
+ * to `display()` as a bogus `format` kind does (docs/adr/0041).
+ *
+ * @type {(name: string, resolve: (scope: any) => any) => (scope: any) => any}
+ */
+export let guarded = (name, resolve) => {
+  // The spec's own checker, not `checkStyle`: this judges a *resolved* value,
+  // where `checkStyle` short-circuits on an `=` source it would still be
+  // looking at. Reading the message rather than a predicate is what lets
+  // `format`, whose value has a shape, answer here like every scalar name.
+  let { check } = STYLES[name];
+  let fail = name === "currency" ? null : SKIP;
+  return (scope) => {
+    let value = resolve(scope);
+    return check(value) === null ? value : fail;
+  };
+};
+
+/** @type {(code: any) => string | null} */
+let codeOf = (code) => (typeof code === "string" && code ? code : null);
+
+/**
+ * Which currency code a cell wears: its own when it declares one, else the
+ * instance's default. A resolution rather than a presentation rule, which is
+ * why it sits here: the xlsx target needs the code itself — it splices it into
+ * a number format — where the display targets need the presented text
+ * `format()` returns, and one report's PDF and worksheet must not disagree
+ * about a denomination (docs/adr/0041, docs/adr/0014).
+ *
+ * @param {{ currency?: unknown } | null} [style] A cell's resolved style.
+ * @param {{ currency?: string } | null} [options] The instance's options.
+ * @returns {string | null} The code to present in, or nothing.
+ */
+export let currencyOf = (style, options) =>
+  // Declared at all — even as the `null` the engine's gate leaves behind — is
+  // the cell's own answer, and the instance's default does not override it.
+  style && Object.hasOwn(style, "currency") ? codeOf(style.currency) : codeOf(options?.currency);
+
+// The modifier the declaration names, or nothing. One that did not resolve to
+// a usable value is dropped rather than honoured, so the kind's own default
+// stands: the layer below a failed modifier is the kind's default count, not
+// nothing at all -- the same call `guarded` makes one level up, and for the
+// same reason (docs/adr/0055, docs/adr/0056).
+/** @type {(declared: any, kind: string) => any} */
+let modifierOf = (declared, kind) => {
+  let name = MODIFIERS[kind];
+  let own = Object.hasOwn(declared, name) ? declared[name] : undefined;
+  return own !== undefined && MODIFIER_CHECKS[name](own) ? undefined : own;
+};
+
+/** @type {(own: any) => any} */
+let presentedDate = (own) => Object.freeze({ kind: "date", form: own ?? DEFAULT_FORM });
+
+// A kind with no count at all -- an unreadable currency -- carries no
+// `digits` key rather than an explicit `undefined`, so a consumer's own
+// `Object.hasOwn` reads the same answer the engine reached.
+/** @type {(kind: string, own: any, style: any, options: any) => any} */
+let presentedNumber = (kind, own, style, options) => {
+  let digits = own ?? defaultDigits(kind, currencyOf(style, options));
+  return Object.freeze(digits === undefined ? { kind } : { kind, digits });
+};
+
+/**
+ * A `format` declaration resolved: the shorthand widened to its object, and
+ * the modifier the author did not name filled in from the kind's own default.
+ * `"number"` resolves to `{ kind: "number", digits: 2 }` and `"date"` to
+ * `{ kind: "date", form: "medium" }`, so what crosses the stream carries its
+ * own answer and no consumer computes one (docs/adr/0053, docs/adr/0056).
+ *
+ * A `currency` whose code Intl will not read resolves to a kind with **no**
+ * `digits` — the withdrawal that leaves the worksheet writing no number
+ * format. A declared `digits` still crosses there: it resolved on its own
+ * terms, and making it depend on a sibling declaration would be a special
+ * case bought for nothing.
+ *
+ * @param {{ format?: unknown, currency?: unknown } | null} [style] A cell's style.
+ * @param {{ currency?: string } | null} [options] The instance's options.
+ * @returns {{ kind: string, digits?: number, form?: string } | undefined} The
+ *   resolved declaration, or nothing when this style names no readable kind.
+ */
+export let formatOf = (style, options) => {
+  let declared = style?.format;
+  let kind = kindOf(declared);
+  if (kind === undefined) return undefined;
+  let own = modifierOf(declared, kind);
+  return kind === "date" ? presentedDate(own) : presentedNumber(kind, own, style, options);
+};
+
+/**
+ * Replace a block's `format` with what it resolves to, in place. The one step
+ * past `guarded` that a name needs here, and the last thing a style block has
+ * done to it before a target sees it (docs/adr/0056).
+ *
+ * By the time this runs the declaration is already sound: a literal passed
+ * `checkStyle` at compile, and an `=` result passed `guarded`, which omits a
+ * kind it cannot read the way it omits any other rejected value. So the
+ * `delete` below is not the omit rule -- that is `guarded`'s -- but the answer
+ * to a kind that reads and still presents nothing, which today is only a
+ * `currency` whose code Intl will not take.
+ *
+ * The block is returned rather than mutated silently, because it is the value
+ * `styleFn` hands on.
+ *
+ * @type {(style: any, options?: any) => any}
+ */
+export let resolveFormat = (style, options) => {
+  if (!Object.hasOwn(style, "format")) return style;
+  let resolved = formatOf(style, options);
+  if (resolved) style.format = resolved;
+  else delete style.format;
+  return style;
+};
+
+/**
+ * The fraction digits a cell presents. Public beside `format()` and
+ * `currencyOf()`, and taking the same argument they do — the whole style — so
+ * "which declarations does presentation read?" is answered in one place
+ * rather than once per helper.
+ *
+ * A resolved style already carries the answer, and a target reads it off the
+ * declaration rather than calling this. What this is for is a host holding a
+ * style the stream has not resolved: the shorthand is widened here first, so
+ * either may be asked.
+ *
+ * @param {{ format?: unknown, currency?: unknown } | null} [style] A cell's style.
+ * @param {{ currency?: string } | null} [options] The instance's currency code.
+ * @returns {number | undefined} The digits, or nothing when this cell presents
+ *   no count — `date`, no `format`, an unreadable kind, and a `currency` whose
+ *   code Intl will not read.
+ */
+export let fractionDigits = (style, options) => formatOf(style, options)?.digits;
+
+// A row's `style` resolves onto its cells (SCHEMA.md, "Style declarations").
+// The box is the half that cannot arrive any other way: a table row is not a
+// box on any surface -- not a `<tr>`, not a worksheet row, not a band of the
+// PDF's own -- so it is resolved here, once, and no target is left to have an
+// opinion about it. Every other declaration on a row reaches its cells by the
+// layering each target already does, which is why only the box moves.
+//
+// Which names are the box is decided where the block is compiled, not here: a
+// literal row style is partitioned once per table rather than once per row.
+// So is which of them reaches which cell -- see `boxReaching`. What is left
+// for render is writing the answer.
+
+// The three names of each border side, built once, which is what lets
+// `coveredNames` complete a side from any one of its parts.
+/** @type {Record<string, string[]>} */
+let BORDER_NAMES = Object.fromEntries(
+  SIDES.map((side) => [side, BORDER_PARTS.map((part) => "border" + side + part)]),
+);
+
+/**
+ * The names an under-box loses once an over-box has spoken: every name the
+ * over-box states, plus the other two of any border side it states one of.
+ *
+ * This is the whole-side rule, over declaration names rather than resolved
+ * objects -- which is all it ever needed, since a compiled block writes every
+ * name it declares whatever the values resolve to. Composing the totals block
+ * into its rows uses it at compile time, so no third style level survives to
+ * render (docs/adr/0049); fanning a row's box onto its cells uses it for the
+ * same reason (docs/adr/0056).
+ *
+ * @type {(names: Iterable<string>) => Set<string>}
+ */
+export let coveredNames = (names) => {
+  let out = new Set(names);
+  for (let side of SIDES)
+    if (BORDER_NAMES[side].some((name) => out.has(name)))
+      for (let name of BORDER_NAMES[side]) out.add(name);
+  return out;
+};
+
+/**
+ * Which of a row box's names reach one cell: the row's, less everything the
+ * cell's own declarations cover. A border side is won whole by the cell that
+ * names any of its three parts, so a cell that failed-soft on one name does
+ * not pick up the row's other two and become a stroke nobody declared -- the
+ * question settled here, once per table, rather than per cell per row.
+ *
+ * `null` is the answer for a cell that declares no box name at all, which is
+ * the common case: the row's box is that cell's box entire, so `fanBox` hands
+ * the object over rather than copying it name by name.
+ *
+ * @type {(rowNames: readonly string[], cellNames: readonly string[]) => string[] | null}
+ */
+export let boxReaching = (rowNames, cellNames) => {
+  if (!cellNames.length) return null;
+  let covered = coveredNames(cellNames);
+  return rowNames.filter((name) => !covered.has(name));
+};
+
+// One cell's share of the row's box: the names settled for it, written in
+// the row's own order, under whatever the cell declared itself. A name the
+// row declared may still be absent -- a row's box is guarded like any other
+// block, so one that resolved badly was never written.
+/** @type {(box: any, style: any, names: readonly string[]) => any} */
+let underBox = (box, style, names) => {
+  /** @type {any} */
+  let out = {};
+  for (let name of names) if (Object.hasOwn(box, name)) out[name] = box[name];
+  return Object.assign(out, style);
+};
+
+// What one cell's style becomes under the row's box. `null` names the common
+// case -- the cell claimed none of the box, so the row's is the cell's own
+// and the resolved object is shared rather than copied. An empty list is the
+// opposite end: the cell covered all of it, and its style comes back
+// unchanged, so `fanBox` can tell there is nothing to write.
+/** @type {(box: any, style: any, names: string[] | null) => any} */
+let fanned = (box, style, names) => {
+  if (names === null) return style ? { ...box, ...style } : box;
+  return names.length ? underBox(box, style, names) : style;
+};
+
+/**
+ * Resolve a row's box onto the row's cells, each taking the names settled for
+ * it at compile time (`boxReaching`). The cells are written in place: both
+ * they and the box were built for this one event and nothing else holds them
+ * yet. A row that declares no box is the common case and costs one test.
+ *
+ * @type {(box: any, cells: any[], reaching: (string[] | null)[]) => void}
+ */
+export let fanBox = (box, cells, reaching) => {
+  if (!box) return;
+  for (let i = 0; i < cells.length; i++) {
+    let cell = cells[i];
+    let style = fanned(box, cell.style, reaching[i]);
+    // A cell the box does not reach keeps the style object it already had, so
+    // one that carried none never gains the key.
+    if (style !== cell.style) cell.style = style;
+  }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quario",
-  "version": "0.4.0",
+  "version": "0.6.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": "10 kB"
+      "limit": "13 kB"
     }
   ],
   "engines": {