@quario/html 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+
+- **A split slot's box now fills the split's height.** Before, a slot's
+  background and border stopped at that slot's own content, leaving a gap under
+  any slot shorter than its neighbours. The slot wrapper now carries inline
+  `display:grid`, so the item inside it fills the row; a slot's item markup is
+  unchanged. See the `@quario/layout` changelog for the rule and for what it
+  costs a report that relied on the short box.
+
+- **A date string under `format: "date"` now presents as a date.** The
+  engine's `format()` helper revives the two read forms, so a cell that
+  rendered `2026-08-14` verbatim now renders the presented date. See the
+  `quario` changelog for the forms and the timezone rule.
+
 ## [0.3.0] - 2026-09-02
 
 ### Added

package/README.md

@@ -97,13 +97,13 @@ 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">` sized inline, each holding the slot item's ordinary container  |
+| 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
 target. The schema never speaks in CSS. Displaying a fragment that contains images under a Content

package/lib/index.js

@@ -63,6 +63,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 +130,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 +168,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 = [];
@@ -256,18 +257,45 @@ let styling = (fonts) => {
 
 // One slot's wrapper. An authored share is that width; a width-less slot
 // divides what the sized ones leave, exactly as a width-less column does.
+// `display:grid` is what gives a slot's box the split's height rather than its
+// own content's: the wrapper already stretches as a flex item, and a grid makes
+// its single child fill it in both axes. It belongs here and not on the
+// fragment, because a slot's item is the same `q-item` div it would be
+// anywhere else -- nothing about an item's markup depends on where it sits.
 /** @type {(slot: { width?: number } | undefined) => string} */
 let slotAttr = (slot) =>
-  ' style="' + esc(slot && slot.width != null ? "width:" + slot.width + "%" : "flex:1") + '"';
+  ' style="' +
+  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
@@ -306,12 +334,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) => {
@@ -418,12 +458,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) +
@@ -454,6 +495,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(
@@ -465,7 +507,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 +
@@ -515,9 +557,13 @@ 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 }),
-          );
+          // The header row is the cells the columns declared: a column a
+          // neighbour's span covers has none, and contributes only its `<col>`.
+          let headers = event.columns
+            .filter((/** @type {any} */ column) => column.header)
+            .map((/** @type {any} */ column) =>
+              Object.assign({}, column.header, { path: column.path }),
+            );
           out +=
             '<table class="q-table"' +
             mark(event) +
@@ -525,31 +571,19 @@ export function html(options) {
             "<colgroup>" +
             cols +
             "</colgroup>" +
-            "<thead><tr" +
-            styleAttr({ style: unbox(event.style) }) +
-            ">" +
-            cells(headers, "th", attrs, intl) +
-            "</tr></thead><tbody>";
+            "<thead>" +
+            tr(event, headers, "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

@@ -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

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