@quario/html 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,39 @@ 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

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 = [];
@@ -267,14 +268,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 +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) => {
@@ -425,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) +
@@ -461,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(
@@ -472,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 +
@@ -522,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) +
@@ -532,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.4.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.4.0",
+    "quario": "^0.5.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.4.0"
+    "quario": "^0.5.0"
   },
   "size-limit": [
     {
       "path": "lib/index.js",
-      "limit": "2.5 kB",
+      "limit": "3 kB",
       "ignore": [
         "quario"
       ]