npm - @quario/html - Versions diffs - 0.4.0 → 0.6.0 - Mend

@quario/html 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -7,6 +7,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.6.0] - 2026-09-07
+### Added
+- **A cell's own `currency` code is honoured** at the markup edge, ahead of the
+  instance's default, so a listing whose rows arrive in different currencies
+  presents each in its own. A code the engine could not accept leaves the cell
+  as plain display text rather than presenting it in the instance's currency.
+### Changed
+- **Numbers presented through `format` now show a fixed two fraction digits,
+  matching every other target.** `format: "number"` on `1000` renders
+  `1,000.00` where it rendered `1,000`, and `0.12345` renders `0.12` where it
+  rendered `0.123`; `format: "percent"` on `0.21` renders `21.00%` where it
+  rendered `21%`. `format: "currency"` follows the currency's own minor units,
+  so a JPY amount loses the two decimals it never had. `date` is unchanged, as
+  are grouping separators and symbol placement. The digits come from the
+  engine, so a cell reads the same here as it does in a workbook.
+## [0.5.0] - 2026-09-05
+### Added
+- **A spanning cell emits `colspan`**, ahead of its `style`; a span of one
+  emits no attribute. The `<colgroup>` still names every column, so the
+  geometry is the document's and only the cells merge — which means the header
+  row can carry fewer `<th>` than there are columns.
+- **`valign`** renders as `vertical-align`, on a cell or on the row's `<tr>`,
+  which the browser's own `inherit` on cells carries down. On a split slot the
+  item itself becomes a grid with `align-content`, so the content moves inside
+  the box the slot wrapper already stretches.
+### Changed
+- **A row's box now reaches the cells** instead of being dropped. Padding and
+  border on `detail.header`, `detail.row` or a total row's `style` are emitted
+  inline on each `<th>`/`<td>`, where they also beat the reference
+  stylesheet's own cell padding. The `<tr>` still carries the row's other
+  declarations and still never carries a box, which it could not honour.
+  Fragments of documents that declared a box on a row gain borders and padding
+  they previously rendered without.
+### Fixed
+- **Unstyled table cells sit at the top of their row.** The reference
+  stylesheet now pins `vertical-align: top` on `.q-table tr`, which the cells
+  inherit.
+  Before, a browser centred the shorter cells of a wrapping row while the PDF
+  painted them from the top, so the same report read differently in the two.
+  A host stylesheet overrides it the ordinary way.
 ## [0.4.0] - 2026-09-03
 ### Changed

package/README.md CHANGED Viewed

@@ -61,8 +61,9 @@ const page = await report.render(html(), data);
 </div>
 ```
-The output is a **fragment**: no `<html>`, no `<head>`, no styles of its own. Wrap it in your own
-page shell and stylesheet.
+The output is a **fragment**: no `<html>`, no `<head>`, no stylesheet of its own — the one
+`<style>` it writes is an `@page { margin }` rule when the schema declares `page.margin`. Wrap it
+in your own page shell and stylesheet.
 ## API
@@ -72,9 +73,16 @@ The target factory returns the target you pass to `render`.
 `report()` compiles once and `report.render(html(), data)` resolves the fragment. Compile at
 startup and render per request. Definition problems throw at `report()`, at compile time.
-One option: `{ paths: true }` stamps `data-q-path="<schema path>"` on each element whose event
+Two options. `{ paths: true }` stamps `data-q-path="<schema path>"` on each element whose event
 carries one (items, images, group containers, the table and its cells), mapping rendered output
-back to the definition behind it. Off by default.
+back to the definition behind it. Off by default. `{ fonts }` maps a declared `family` name to the
+CSS `font-family` value it should emit — a custom property, a font stack, a quoted name —
+consulted before the three built-in generics; names match case-insensitively, and a value holding
+`;` or `}` is rejected when the target is constructed:
+```js
+html({ fonts: { "Instrument Sans": "var(--font-instrument-sans)", mono: "var(--font-ibm-plex-mono)" } });
+```
 ```js
 const report = quario().report(schema, funcs);
@@ -97,15 +105,17 @@ host. Compilation stays synchronous; render-time failures reject with the same l
 These classes are the contract host CSS targets. They are stable, and changing them is a breaking
 change.
-| Emits                                     | For                                                                                                                                                                              |
-| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `<div class="q-item q-<role>">`           | Every item. Roles: `q-report-header`, `q-empty`, `q-group-header`, `q-detail`, `q-group-footer`, `q-report-footer`                                                               |
-| `<div class="q-group" data-group="name">` | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` when the group declares `break: "page"` or `reset: "page"`                                  |
-| `<table class="q-table">`                 | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` when totals are declared                                                                                     |
-| `<div class="q-item q-image q-<role>">`   | Each image item, holding one `<img>` whose `src` is a base64 `data:` URI of the event's bytes; the rendered `alt` is escaped                                                     |
-| `<div class="q-split q-<role>">`          | Each split, carrying inline `display:flex`; its slots are `<div class="q-slot">` carrying inline `display:grid` and their share, each holding the slot item's ordinary container |
-A column `width` becomes an inline `width:<n>%` on its `<col>`. The classes above belong to this
+| Emits                                              | For                                                                                                                                                                                                                     |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                 |
+| `<div class="q-item q-<role>">`                    | Every item. Roles: `q-report-header`, `q-empty`, `q-group-header`, `q-detail`, `q-group-footer`, `q-report-footer`                                                                                                      |
+| `<div class="q-group" data-group="name">`          | Each group instance, wrapping its header, nested content, and footer. Adds `q-break` when the group declares `break: "page"` or `reset: "page"`                                                                         |
+| `<table class="q-table">`                          | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` around the total rows the walk emits — none when `total` is absent or every row of it is hidden. A spanning cell carries `colspan`                  |
+| `<div class="q-item q-image q-<role>">`            | Each image item, holding one `<img>` whose `src` is a base64 `data:` URI of the event's bytes; `fit` sets `max-width:100%` or `width:100%` on it, and the rendered `alt` is escaped                                     |
+| `<div class="q-columns" style="column-count:<n>">` | The content between a node's own bands when it declares `columns`: on the root, the body between report header and footer; on a group, inside that instance's `q-group`                                                 |
+| `<div class="q-split q-<role>">`                   | Each split, carrying inline `display:flex`; its slots are `<div class="q-slot">` carrying inline `display:grid` and their share (a slot's `valign` as `align-content`), each holding the slot item's ordinary container |
+A column `width` becomes an inline `width:<n>%` on its `<col>`. A row's `style` lands on its `<tr>`, except the box, which the engine has already resolved onto the cells (each `<td>` carries `box-sizing:border-box`). The classes above belong to this
 target. The schema never speaks in CSS. Displaying a fragment that contains images under a Content
 Security Policy needs `img-src data:`.
@@ -121,8 +131,9 @@ instead. The PDF and XLSX targets carry theirs built in, because their consumers
 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
-the schema and ignored here until a target honors them.
+and maps `break: "page"` and `reset: "page"` to the `q-break` class. Page columns are laid out:
+a node declaring `columns` wraps the content between its own bands in the `q-columns` container
+above, and the browser flows it.
 ## Unlicensed marking
@@ -134,8 +145,8 @@ badge unstyled, because a watermark would escape the fragment's box onto the hos
 ## Escaping
 **Every interpolated value is escaped.** `{{{ }}}` is a definition error, so no schema syntax can
-exempt a data value from escaping. Generated attribute values, including classes and inline
-styles built from expressions, are escaped too.
+exempt a data value from escaping. Every generated attribute value is escaped too — inline styles, `data-` attributes, `src`, `alt`
+and `colspan`; class names are constants the target owns and never carry data.
 Literal template text passes through verbatim as author-controlled markup. A definition is
 trusted configuration. Its _data_ is untrusted, and data can never reach the document unescaped.
@@ -154,6 +165,7 @@ Host CSS targets these classes:
 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-table tr { break-inside: avoid }` keeps a row whole,
    `.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.
 3. Print with a headless browser (`page.pdf()` in Playwright or Puppeteer, page numbers via the

package/lib/index.js CHANGED Viewed

@@ -12,7 +12,13 @@
 import { display, format, isReportBand, text, walk } from "quario";
 /** @type {Record<string, string>} */
-let ESC = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+let ESC = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
 /** @type {(value: any) => string} */
 let esc = (value) => display(value).replace(/[&<>"']/g, (char) => ESC[char]);
@@ -30,7 +36,7 @@ let markup = (tokens, style, intl) => {
 };
 /** @type {(value: any, style: any, intl: any) => any} */
 let shown = (value, style, intl) => {
-  let text = format(value, style?.format, intl);
+  let text = format(value, style, intl);
   return text != null ? text : value;
 };
@@ -63,6 +69,13 @@ let UNSAFE = /[;}]/;
 /** @type {(value: any) => boolean} */
 let isHex = (value) => typeof value === "string" && HEX.test(value);
 let ALIGNMENTS = ["left", "center", "right"];
+// A slot item's `valign` and `align` as grid placement (see `placed`); the
+// vertical vocabulary is these keys, so the three readers of it agree.
+/** @type {Record<string, string>} */
+let ALIGN_CONTENT = { top: "start", middle: "center", bottom: "end" };
+/** @type {Record<string, string>} */
+let JUSTIFY_ITEMS = { left: "start", center: "center", right: "end" };
+let VALIGNMENTS = Object.keys(ALIGN_CONTENT);
 // A group instance's own bands. They sit outside a columned container only when
 // that instance is the node which declared the count — an inner instance's are
@@ -123,6 +136,11 @@ let CSS = {
   color: (value) => (isHex(value) ? "color:" + value : ""),
   background: (value) => (isHex(value) ? "background-color:" + value : ""),
   align: (value) => (ALIGNMENTS.includes(value) ? "text-align:" + value : ""),
+  // The table reading, on a `<tr>` or a cell: the browser's own sheet gives
+  // cells `vertical-align: inherit`, so a row's reaches them like `bold`
+  // does. A slot item's is placement, and `placed` below lifts the name out
+  // before this map sees it.
+  valign: (value) => (VALIGNMENTS.includes(value) ? "vertical-align:" + value : ""),
   // The text itself is untouched, so selection and screen readers get what
   // the author wrote; only its rendering is capitalised.
   uppercase: flag("text-transform:uppercase", "text-transform:none"),
@@ -156,17 +174,6 @@ let borderSide = (style, side) => {
   ];
 };
-/** @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 = [];
@@ -267,14 +274,34 @@ let slotAttr = (slot) =>
   esc("display:grid;" + (slot && slot.width != null ? "width:" + slot.width + "%" : "flex:1")) +
   '"';
+// A slot item's `valign`. The slot wrapper's grid stretches the item to the
+// split's height, so the item is the box and its content has to move inside
+// it: the item becomes a grid of its own and `align-content` places the
+// content. Not on the wrapper -- `align-items` there would shrink the item
+// back to its content and reopen the gap the grid closed. Lifted out of the
+// style so the cell mapping (`vertical-align`) does not also emit on a div.
+// The result is what `styleAttr` takes: a style and the structural prefix.
+/** @type {(event: { style?: any }) => { style?: any, own: string }} */
+let placed = (event) => {
+  let valign = event.style?.valign;
+  if (!Object.hasOwn(ALIGN_CONTENT, valign)) return { style: event.style, own: "" };
+  let { valign: _, ...style } = event.style;
+  return { style, own: "display:grid;align-content:" + ALIGN_CONTENT[valign] };
+};
+// A picture is a replaced element, which a grid places at the start rather
+// than stretching, so the container's `text-align` no longer reaches it: the
+// same `align` word rides `justify-items` while the item is a grid.
+/** @type {(own: string, style: any) => string} */
+let justified = (own, style) =>
+  own && Object.hasOwn(JUSTIFY_ITEMS, style?.align)
+    ? own + ";justify-items:" + JUSTIFY_ITEMS[style.align]
+    : own;
 // The identity attribute, escaped like every other generated value at this
 // edge. `mark` is the factory's verdict: a render without `paths` maps every
 // event to "" through the same function rather than re-deciding per call site.
 /** @type {(event: { path?: string }) => string} */
 let pathAttr = ({ path }) => (path ? ' data-q-path="' + esc(path) + '"' : "");
-/** @type {() => string} */
-let noAttr = () => "";
 /** @type {(list: any[], tag: string, attrs: (event: any) => string, intl: any) => string} */
 let cells = (list, tag, attrs, intl) =>
   list
@@ -313,12 +340,24 @@ let cells = (list, tag, attrs, intl) =>
  *   The target (see SCHEMA.md, "Instances and targets").
  */
 export function html(options) {
-  let mark = options?.paths ? pathAttr : noAttr;
+  let mark = options?.paths ? pathAttr : () => "";
   // The factory's verdict, like `mark`: the mapping is validated once, here.
   let styleAttr = styling(options?.fonts);
   // The pair every cell carries, bound once rather than threaded as two.
   /** @type {(cell: any) => string} */
-  let attrs = (cell) => styleAttr(cell) + mark(cell);
+  // A span covers several columns; `colspan` is what that is on this surface.
+  // Escaped like every other attribute value this target writes, though the
+  // engine has already vouched the span is a positive integer.
+  /** @type {(cell: any) => string} */
+  let attrs = (cell) =>
+    (cell.span > 1 ? ' colspan="' + esc(cell.span) + '"' : "") + styleAttr(cell) + mark(cell);
+  // One table row: the row style on the `<tr>`, from which it inherits into
+  // the cells, `valign` included. The box is not among these names — a `<tr>`
+  // could not honour one, and the engine has already resolved that half onto
+  // the cells, where it arrives as ordinary inline CSS.
+  /** @type {(event: any, list: any[], tag: string, intl: any) => string} */
+  let tr = (event, list, tag, intl) =>
+    "<tr" + styleAttr(event) + ">" + cells(list, tag, attrs, intl) + "</tr>";
   return {
     name: "html",
     compile: (stream) => async (data) => {
@@ -408,7 +447,11 @@ 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 };
+          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>";
@@ -425,12 +468,13 @@ export function html(options) {
         // The stable `q-item q-<role>` classes are the whole class attribute;
         // print CSS targets the band-role class for styling and breaks.
         item: (event) => {
+          let slot = placed(event);
           emit(
             event,
             '<div class="q-item q-' +
               event.role +
               '"' +
-              styleAttr(event) +
+              styleAttr(slot, slot.own) +
               mark(event) +
               ">" +
               markup(event.tokens, event.style, intl) +
@@ -461,6 +505,7 @@ export function html(options) {
         // never the markup-passing join a cell body gets; an image without one
         // carries `alt=""`, the decorative-image convention.
         image: (event) => {
+          let slot = placed(event);
           let source = sources.get(event.bytes);
           if (source === undefined)
             sources.set(
@@ -472,7 +517,7 @@ export function html(options) {
             '<div class="q-item q-image q-' +
               event.role +
               '"' +
-              styleAttr(event) +
+              styleAttr(slot, justified(slot.own, event.style)) +
               mark(event) +
               '><img src="' +
               source +
@@ -522,9 +567,6 @@ export function html(options) {
           for (let column of /** @type {any[]} */ (event.columns))
             cols +=
               "<col" + (column.width ? ' style="width:' + esc(column.width) + '%"' : "") + ">";
-          let headers = event.columns.map((/** @type {any} */ column) =>
-            Object.assign({}, column.header, { path: column.path }),
-          );
           out +=
             '<table class="q-table"' +
             mark(event) +
@@ -532,31 +574,21 @@ export function html(options) {
             "<colgroup>" +
             cols +
             "</colgroup>" +
-            "<thead><tr" +
-            styleAttr({ style: unbox(event.style) }) +
-            ">" +
-            cells(headers, "th", attrs, intl) +
-            "</tr></thead><tbody>";
+            "<thead>" +
+            // The header row arrives shaped like a `row` payload, so the same
+            // `<tr>` writer takes it whole (docs/adr/0053).
+            tr(event.header, event.header.cells, "th", intl) +
+            "</thead><tbody>";
         },
         row: (event) => {
-          out +=
-            "<tr" +
-            styleAttr({ style: unbox(event.style) }) +
-            ">" +
-            cells(event.cells, "td", attrs, intl) +
-            "</tr>";
+          out += tr(event, event.cells, "td", intl);
         },
         "total-row": (event) => {
           if (!tfoot) {
             out += "</tbody><tfoot>";
             tfoot = true;
           }
-          out +=
-            "<tr" +
-            styleAttr({ style: unbox(event.style) }) +
-            ">" +
-            cells(event.cells, "td", attrs, intl) +
-            "</tr>";
+          out += tr(event, event.cells, "td", intl);
         },
         "table-end": () => {
           out += tfoot ? "</tfoot></table>" : "</tbody></table>";

package/lib/style.css CHANGED Viewed

@@ -15,11 +15,11 @@
  * rules are not. They are a reference default -- adjust freely, or never link
  * this file at all.
  *
- * The block between the `shared:` markers below is byte-identical to the one
- * in `packages/viewer/lib/style.js`, which the viewer adopts into its shadow
- * root. The two cannot be single-sourced -- the viewer imports no target
- * package -- so `test/stylesheet.test.js` at the repo root fails when they
- * drift. Edit one, edit the other.
+ * The block between the `shared:` markers below is the one shipped look.
+ * The viewer and the editor used to adopt a copy of it into their shadow
+ * roots; both now paint the layout list on a canvas and carry no report
+ * stylesheet (docs/adr/0039), so `test/stylesheet.test.js` at the repo root
+ * gates this block against `example/print.css` growing a copy back.
  */
 /* shared:start */
@@ -56,6 +56,16 @@
   white-space: pre-line;
 }
+/* A wrapping row leaves its shorter cells slack, and a browser fills that
+   from the middle where the PDF paints from the top. Pin the top so an
+   unstyled table reads the same in both; an author who wants otherwise
+   declares `valign`. On the row, not the cells: the browser's own sheet gives
+   cells `vertical-align: inherit`, which is what lets a row's declaration
+   reach them, and a rule on the cells would cut that off. */
+.q-table tr {
+  vertical-align: top;
+}
 .q-table th,
 .q-table td {
   padding: 2pt 6pt;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@quario/html",
-  "version": "0.4.0",
+  "version": "0.6.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.4.0",
+    "quario": "^0.6.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.4.0"
+    "quario": "^0.6.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "2.5 kB",
+      "limit": "3 kB",
       "ignore": [
         "quario"
       ]