@quario/html 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-02
+
+### Added
+
+- **`format` stringifies at the markup edge.** The kind is presented through
+  the engine's `format()` helper from the instance locale, then escaped like
+  any other interpolated value.
+
+- **`page.margin` becomes `@page{margin:<n>pt}`.** Report-header `height`
+  is unread: a CSS height would pin in the body box, not from the page top.
+
+- **`spaceBefore` / `spaceAfter` map to `margin-top` / `margin-bottom`.**
+  Report and group containers are flex columns so adjacent authored gaps add
+  rather than collapse.
+
+- **Padding and complete border sides map to inline CSS.**
+  `box-sizing:border-box` rides the same attribute. A side that does not
+  resolve all three names emits nothing, so a missing colour never becomes
+  the browser's solid black. Header-row, row, and total-row boxes are
+  withdrawn from `<tr>` — CSS does not box a table row — while other row
+  styles still inherit.
+
+### Changed
+
+- **`<tfoot>` holds every total row.** Extra rows are extra `<tr>`; the
+  section still closes at `table-end`.
+
+- **A visible text item occupies a line, and a literal newline is a break.**
+  Before, an empty item collapsed and a newline became a space. The honor
+  rules now hang off `.q-item` and `.q-table th, td` in the reference
+  stylesheet, the same pattern as `.q-break` — class is the hook, the rule
+  is overridable. Empty table cells still collapse. Host CSS still owns
+  leading; this is not `line-height: 1.4`.
+
+### Fixed
+
+- **A declared `false` flag now emits its CSS off-value.** `bold: false` used
+  to emit nothing, so the reference stylesheet's band-role `font-weight: bold`
+  still won on screen while PDF rendered regular. Exact `false` now writes
+  `font-weight:normal` (and the matching off-value for italic, uppercase, and
+  the decorations), which beats the sheet. Omit and a non-boolean result still
+  emit nothing.
+
 ## [0.2.0] - 2026-09-01
 
 ### Added

package/README.md

@@ -109,15 +109,16 @@ A column `width` becomes an inline `width:<n>%` on its `<col>`. The classes abov
 target. The schema never speaks in CSS. Displaying a fragment that contains images under a Content
 Security Policy needs `img-src data:`.
 
-Style declarations map to inline CSS (`bold` → `font-weight:bold`, `size` → `font-size:<n>pt`,
-`family: "mono"` → `font-family:monospace`, …). Only those mappings appear in the markup. This
-target supplies no defaults in the markup: no weight or size per band role, no leading, no padding,
-no spacing between bands, no borders. An unstyled report renders as unstyled markup, and the
-classes above are where a stylesheet supplies the look. An inline `style` attribute would beat
-yours in the cascade and force `!important` on you; the defaults ship as an ordinary stylesheet
-instead, at [`@quario/html/style.css`](#the-reference-stylesheet). The PDF and XLSX targets carry
-theirs built in, because their consumers have no stylesheet. An empty row set still emits the
-table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
+Style declarations map to inline CSS (`bold` → `font-weight:bold` or `font-weight:normal`, `size` → `font-size:<n>pt`,
+`family: "mono"` → `font-family:monospace`, …). Occupy-a-line and newline-as-break are **not** inline: they hang off
+`.q-item` and `.q-table th, td` in [`@quario/html/style.css`](#the-reference-stylesheet), the same way `.q-break`
+honors `break: "page"`. The class is the hook; the rule is a reference default a host overrides on source order.
+A fragment without that sheet still carries the classes and the text, including newlines; it does not occupy or
+break until some stylesheet says so. This target supplies no defaults in the markup: no weight or size per band
+role, no leading, no padding, no spacing between bands, no borders. An inline `style` attribute would beat yours
+in the cascade and force `!important` on you; the defaults and the honor rules ship as an ordinary stylesheet
+instead. The PDF and XLSX targets carry theirs built in, because their consumers have no stylesheet. An empty
+row set still emits the table, its header, and an empty `<tbody>`. A hidden table cell keeps its `<td>`, empty.
 
 This target is unpaginated: it ignores schema page bands (page furniture belongs to your print CSS)
 and maps `break: "page"` and `reset: "page"` to the `q-break` class. Page columns are accepted on
@@ -151,6 +152,7 @@ Host CSS targets these classes:
 1. Render the fragment and wrap it in a document with two stylesheets inlined, in order:
    `@quario/html/style.css` below, then your own.
 2. The shipped sheet already puts band behavior on the emitted classes:
+   `.q-item { min-height: 1lh; white-space: pre-line }` occupies a line and breaks on newlines,
    `.q-group { break-inside: avoid }` keeps a group header with its rows,
    `.q-break { break-before: page }` honors the schema's own break hint, and `thead` repeats per
    printed page. Yours adds the page geometry in `@page`, which only you can decide.
@@ -161,8 +163,9 @@ Host CSS targets these classes:
 ### The reference stylesheet
 
 The package ships the default look as a real stylesheet, `@quario/html/style.css`: the band-role
-weights and sizes, the table look, and the four pagination rules above. Link it, import it through
-a bundler, or read and inline it. Plain Node cannot `import` a `.css` file, so on the server:
+weights and sizes, the table look, occupy and newline-as-break on `.q-item` and table cells, and
+the four pagination rules above. Link it, import it through a bundler, or read and inline it.
+Plain Node cannot `import` a `.css` file, so on the server:
 
 ```js
 import { readFileSync } from "node:fs";

package/lib/index.js

@@ -9,7 +9,7 @@
  * never carries markup-escaped text.
  */
 
-import { display, isReportBand, text, walk } from "quario";
+import { display, format, isReportBand, text, walk } from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
@@ -21,12 +21,18 @@ let esc = (value) => display(value).replace(/[&<>"']/g, (char) => ESC[char]);
 // exceptions. The engine's own `text` join is the other one -- display text,
 // where a literal is words rather than markup -- and an attribute value takes
 // that one, escaped whole.
-/** @type {(tokens: any[]) => string} */
-let markup = (tokens) => {
+/** @type {(tokens: any[], style?: any, intl?: any) => string} */
+let markup = (tokens, style, intl) => {
   let out = "";
-  for (let token of tokens) out += "literal" in token ? token.literal : esc(token.value);
+  for (let token of tokens)
+    out += "literal" in token ? token.literal : esc(shown(token.value, style, intl));
   return out;
 };
+/** @type {(value: any, style: any, intl: any) => any} */
+let shown = (value, style, intl) => {
+  let text = format(value, style?.format, intl);
+  return text != null ? text : value;
+};
 
 // base64 for an image's `data:` URI, without Buffer: this package runs in Node
 // and in ES2024 browsers off the same `lib/`, and `btoa` is a standard global
@@ -100,6 +106,10 @@ let named = (map, value) => {
   if (Object.hasOwn(map, key)) return map[key];
   return NAMEABLE.test(value) ? "'" + value + "'" : "";
 };
+// Exact true/false only: a computed value of the wrong shape contributes
+// nothing, same as omit (SCHEMA.md, Style declarations).
+/** @type {(on: string, off: string) => (value: any) => string} */
+let flag = (on, off) => (value) => (value === true ? on : value === false ? off : "");
 /** @type {Record<string, (value: any, map: Record<string, string>) => string>} */
 let CSS = {
   family: (value, map) => {
@@ -108,22 +118,68 @@ let CSS = {
     return name ? "font-family:" + name : "";
   },
   size: (value) => (Number.isFinite(value) && value > 0 ? "font-size:" + value + "pt" : ""),
-  bold: (value) => (value ? "font-weight:bold" : ""),
-  italic: (value) => (value ? "font-style:italic" : ""),
+  bold: flag("font-weight:bold", "font-weight:normal"),
+  italic: flag("font-style:italic", "font-style:normal"),
   color: (value) => (isHex(value) ? "color:" + value : ""),
   background: (value) => (isHex(value) ? "background-color:" + value : ""),
   align: (value) => (ALIGNMENTS.includes(value) ? "text-align:" + value : ""),
   // The text itself is untouched, so selection and screen readers get what
   // the author wrote; only its rendering is capitalised.
-  uppercase: (value) => (value ? "text-transform:uppercase" : ""),
+  uppercase: flag("text-transform:uppercase", "text-transform:none"),
+};
+
+let SIDES = ["Top", "Right", "Bottom", "Left"];
+let LINES = ["solid", "dashed", "dotted"];
+/** @type {(value: any) => boolean} */
+let isPad = (value) => Number.isFinite(value) && value >= 0;
+for (let side of SIDES) {
+  let edge = side.toLowerCase();
+  CSS["padding" + side] = (value) => (isPad(value) ? "padding-" + edge + ":" + value + "pt" : "");
+}
+CSS.spaceBefore = (value) => (isPad(value) ? "margin-top:" + value + "pt" : "");
+CSS.spaceAfter = (value) => (isPad(value) ? "margin-bottom:" + value + "pt" : "");
+
+/** @type {(width: any) => boolean} */
+let isStroke = (width) => Number.isFinite(width) && width > 0;
+
+/** @type {(style: any, side: string) => string[]} */
+let borderSide = (style, side) => {
+  let width = style["border" + side + "Width"];
+  let line = style["border" + side + "Style"];
+  let color = style["border" + side + "Color"];
+  if (!isStroke(width) || !LINES.includes(line) || !isHex(color)) return [];
+  let edge = side.toLowerCase();
+  return [
+    "border-" + edge + "-width:" + width + "pt",
+    "border-" + edge + "-style:" + line,
+    "border-" + edge + "-color:" + color,
+  ];
+};
+
+/** @type {(name: string) => boolean} */
+let isBox = (name) => name.startsWith("padding") || name.startsWith("border");
+
+/** @type {(style: any) => any} */
+let unbox = (style) => {
+  if (!style) return;
+  let names = Object.keys(style).filter((name) => !isBox(name));
+  if (!names.length) return;
+  return Object.fromEntries(names.map((name) => [name, style[name]]));
+};
+
+/** @type {(style: any) => string[]} */
+let decoLine = (style) => {
+  let parts = [];
+  if (style.underline === true) parts.push("underline");
+  if (style.strikethrough === true) parts.push("line-through");
+  return parts;
 };
 
 /** @type {(style: any) => string} */
 let decoration = (style) => {
-  let parts = [];
-  if (style.underline) parts.push("underline");
-  if (style.strikethrough) parts.push("line-through");
-  return parts.length ? "text-decoration:" + parts.join(" ") : "";
+  let parts = decoLine(style);
+  if (parts.length) return "text-decoration:" + parts.join(" ");
+  return style.underline === false || style.strikethrough === false ? "text-decoration:none" : "";
 };
 
 /** @type {(name: string) => boolean} */
@@ -144,17 +200,40 @@ let pushDecl = (out, name, value, map) => {
   if (declaration) out.push(declaration);
 };
 
+/** @type {(out: string[], style: any, seen: { box: boolean, sizing: boolean }) => void} */
+let pushBox = (out, style, seen) => {
+  if (seen.box) return;
+  seen.box = true;
+  let start = out.length;
+  for (let side of SIDES) out.push(...borderSide(style, side));
+  if (out.length > start) seen.sizing = true;
+};
+
+/** @type {(seen: { sizing: boolean }, name: string, added: boolean) => void} */
+let notePad = (seen, name, added) => {
+  if (added && name.startsWith("padding")) seen.sizing = true;
+};
+
+/** @type {(out: string[], name: string, style: any, seen: { decoration: boolean, box: boolean, sizing: boolean }, map: Record<string, string>) => void} */
+let emitDecl = (out, name, style, seen, map) => {
+  if (isDecoration(name)) return pushDecoration(out, style, seen);
+  if (name.startsWith("border")) return pushBox(out, style, seen);
+  let start = out.length;
+  pushDecl(out, name, style[name], map);
+  notePad(seen, name, out.length > start);
+};
+
 // Serialize a resolved style object to inline CSS, in declaration order.
 // underline and strikethrough share one CSS property, so the first of either
-// in authored order emits the composed value and the second is skipped.
+// in authored order emits the composed value and the second is skipped. A
+// border side emits only when width, style and colour all resolve, so a
+// missing name never becomes a browser-default solid black stroke.
 /** @type {(style: any, map: Record<string, string>) => string} */
 let css = (style, map) => {
   let out = /** @type {string[]} */ ([]);
-  let seen = { decoration: false };
-  for (let name in style) {
-    if (isDecoration(name)) pushDecoration(out, style, seen);
-    else pushDecl(out, name, style[name], map);
-  }
+  let seen = { decoration: false, box: false, sizing: false };
+  for (let name in style) emitDecl(out, name, style, seen, map);
+  if (seen.sizing) out.push("box-sizing:border-box");
   return out.join(";");
 };
 
@@ -189,10 +268,13 @@ let pathAttr = ({ path }) => (path ? ' data-q-path="' + esc(path) + '"' : "");
 /** @type {() => string} */
 let noAttr = () => "";
 
-/** @type {(list: any[], tag: string, attrs: (event: any) => string) => string} */
-let cells = (list, tag, attrs) =>
+/** @type {(list: any[], tag: string, attrs: (event: any) => string, intl: any) => string} */
+let cells = (list, tag, attrs, intl) =>
   list
-    .map((cell) => "<" + tag + attrs(cell) + ">" + markup(cell.tokens) + "</" + tag + ">")
+    .map(
+      (cell) =>
+        "<" + tag + attrs(cell) + ">" + markup(cell.tokens, cell.style, intl) + "</" + tag + ">",
+    )
     .join("");
 
 /**
@@ -240,7 +322,7 @@ export function html(options) {
       // goes with the render — nothing here outlives it.
       /** @type {Map<Uint8Array, string>} */
       let sources = new Map();
-      // Whether a `total-row` already closed the `<tbody>` — markup
+      // Whether a `total-row` already opened `<tfoot>` — markup
       // bookkeeping that stays at this edge, out of the event contract.
       let tfoot = false;
       // Whether `report-start` opened the report root. A stream may start
@@ -264,6 +346,8 @@ export function html(options) {
       // enough. Null whenever the walk is not inside a bracket.
       /** @type {{ slots: any[], at: number } | null} */
       let split = null;
+      /** @type {{ locale?: string, currency?: string, timeZone?: string } | null} */
+      let intl = null;
       // Place one item's markup: inside a bracket it goes in the next slot,
       // and everywhere else it is a band item like any other.
       /** @type {(event: any, fragment: string) => void} */
@@ -317,7 +401,10 @@ export function html(options) {
         // edge, so the badge stays childless whatever stream a host compiles
         // against.
         "report-start": (event) => {
+          intl = { locale: event.locale, currency: event.currency, timeZone: event.timeZone };
           if (event.marking) out += '<div class="q-unlicensed">' + esc(event.marking) + "</div>";
+          if (event.margin != null)
+            out += "<style>@page{margin:" + esc(event.margin) + "pt}</style>";
           // The report root. Always emitted, because the fragment otherwise
           // has no element for a document-wide declaration to be inherited
           // from, and the shipped stylesheet's own baseline now hangs off it.
@@ -339,7 +426,7 @@ export function html(options) {
               styleAttr(event) +
               mark(event) +
               ">" +
-              markup(event.tokens) +
+              markup(event.tokens, event.style, intl) +
               "</div>",
           );
         },
@@ -438,19 +525,34 @@ export function html(options) {
             "<colgroup>" +
             cols +
             "</colgroup>" +
-            "<thead><tr>" +
-            cells(headers, "th", attrs) +
+            "<thead><tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(headers, "th", attrs, intl) +
             "</tr></thead><tbody>";
         },
         row: (event) => {
-          out += "<tr" + styleAttr(event) + ">" + cells(event.cells, "td", attrs) + "</tr>";
+          out +=
+            "<tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(event.cells, "td", attrs, intl) +
+            "</tr>";
         },
         "total-row": (event) => {
-          tfoot = true;
-          out += "</tbody><tfoot><tr>" + cells(event.cells, "td", attrs) + "</tr></tfoot>";
+          if (!tfoot) {
+            out += "</tbody><tfoot>";
+            tfoot = true;
+          }
+          out +=
+            "<tr" +
+            styleAttr({ style: unbox(event.style) }) +
+            ">" +
+            cells(event.cells, "td", attrs, intl) +
+            "</tr>";
         },
         "table-end": () => {
-          out += tfoot ? "</table>" : "</tbody></table>";
+          out += tfoot ? "</tfoot></table>" : "</tbody></table>";
         },
       });
       // A root region reaches here open when no full-width footer followed the

package/lib/style.css

@@ -36,15 +36,31 @@
   font-family: sans-serif;
 }
 
+.q-report,
+.q-group {
+  display: flex;
+  flex-direction: column;
+}
+
 .q-table {
   width: 100%;
   border-collapse: collapse;
 }
 
+/* A visible text item occupies a line, and a literal newline is a break.
+   The class is the hook; a host overrides these the ordinary way, as with
+   .q-break. Empty table cells stay contentless, so they take only the
+   newline mapping. */
+.q-item {
+  min-height: 1lh;
+  white-space: pre-line;
+}
+
 .q-table th,
 .q-table td {
   padding: 2pt 6pt;
   text-align: left;
+  white-space: pre-line;
 }
 
 .q-table thead th {
@@ -95,6 +111,10 @@
  * Pages are not the only fragmentation context: the columns case lives in the
  * shared block above, because a sheet with no pages can still have columns.
  *
+ * Occupy and newline-as-break live in the shared block above: a screen needs
+ * them, and they follow the same pattern as `.q-break` -- class is the hook,
+ * the rule is overridable.
+ *
  * A host overrides any of these the ordinary way; `example/print.css` turns
  * `break-inside` back to `auto` for one group to let it span pages.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/html",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The HTML render target for quario — in the makings, not yet released",
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
@@ -39,17 +39,17 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.2.0",
+    "quario": "^0.3.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.2.0"
+    "quario": "^0.3.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "2 kB",
+      "limit": "2.5 kB",
       "ignore": [
         "quario"
       ]