@quario/html 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @quario/html
 
+## 0.11.0
+
+### Minor Changes
+
+- **A `capabilities` descriptor.** The target exports what it makes of each declaration the spec's support matrix names — `resolved`, `approximated`, `withdrawn` or `unread` — beside its factory, so a host can ask before it renders rather than reading the prose. It is keyed by the schema name an author writes (`valign`, `break`, `page.margin`, and `column.width` / `slot.width` where one word carries two declarations), hand-written and gated against that matrix. It carries no version of its own: the package that ships it is the version.
+- **`negative` and `zero` reach the markup edge.** The target stringifies through the engine's `format()`, so a cell declaring either presents there too: a negative in parentheses, a zero as a dash.
+- **A collapsed group does not draw its content.** An instance whose group declares `collapsed` renders as its header and footer, with the rows between them left out — a page has nowhere to put a row a reader could open. Aggregates are unchanged, so a footer still totals them.
+- **A run that links becomes an anchor.** A run carrying `href` is wrapped in an `<a>` inside its own span, so the style the run declared paints the link, and the URL is escaped at the one markup edge like every other interpolated value. A real anchor rather than a styled span, because keyboard reachability comes with it. The engine admitted the URL before it crossed, so this target decides nothing about it.
+- **The report header scales with the size it sits in.** The shipped stylesheet's `.q-item.q-report-header` rule is `font-size: 1.4em` rather than `14pt`. A document declaring `"size": 20` now renders its report header at 28pt where it rendered at 14pt, smaller than its own body. This is visible to every host page: an unstyled report's header is now 1.4× the host's own body type rather than a fixed 14pt, so a host whose body is not 10pt sees the headline move. A host rule on the class still wins, as before.
+
+### Patch Changes
+
+- **A cell's own `href` now links its text.** `href` sits on a cell as well as in a run's inline subset, but this target read it only off a run that declared a style of its own, so `{ style: { href } }` on the cell rendered the text with no anchor at all. It now asks the style the run wears rather than the one it declares, which is the cell's wherever the run is silent. A run declaring its own `href` still replaces the cell's rather than nesting inside it.
+- Updated dependencies
+  - quario@0.11.0
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -121,6 +121,7 @@ change.
 | Emits                                              | For                                                                                                                                                                                                                                                                        |
 | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `<div class="q-report">`                           | The fragment's root, holding every band                                                                                                                                                                                                                                    |
+| `<a href>`                                         | A styled run that declares `href`, inside that run's own span. The URL is escaped like every other interpolated value, and the engine admitted it against the host's scheme allowlist before this target saw it                                                            |
 | `<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` where the group's `break` turns a page before the instance, and `q-break-after` where one turns after it                                                                              |
 | `<table class="q-table">`                          | Each table, with a real `colgroup`, `thead`, `tbody`, and a `tfoot` around the total rows the walk emits. No `tfoot` when `total` is absent or every row of it is hidden. A spanning cell carries `colspan`                                                                |

package/lib/index.d.ts

@@ -29,3 +29,27 @@ export interface HtmlOptions {
  * described in SCHEMA.md ("The HTML target").
  */
 export function html(options?: HtmlOptions): Target<"html", Promise<string>>;
+
+/** What a target makes of a declaration: CONTEXT.md's fate vocabulary. */
+export type Fate = "resolved" | "approximated" | "withdrawn" | "unread";
+
+/**
+ * What this target makes of each declaration SCHEMA.md's support matrix
+ * names. Hand-written and gated against that matrix rather than generated
+ * from it. It carries no version of its own: the package that ships it is the
+ * version.
+ *
+ * Keyed by the schema name an author writes — `valign`, `break`, `page.margin`
+ * — so a host, a `required` marking and a problem message share one
+ * vocabulary. Two matrix rows share the bare word `width`, so each is
+ * qualified by what carries it: `column.width` and `slot.width`.
+ *
+ * It covers the declarations every official target states one fate for. An
+ * absent key means the matrix states no single fate for that row — a row that
+ * summarises more than one declaration, or that describes a behaviour — never
+ * that this target has no answer.
+ */
+export const capabilities: {
+  readonly target: "html";
+  readonly declarations: Readonly<Record<string, Fate>>;
+};

package/lib/index.js

@@ -9,7 +9,17 @@
  * never carries markup-escaped text.
  */
 
-import { display, format, hostOptions, isReportBand, splits, styledRuns, text, walk } from "quario";
+import {
+  collapse,
+  display,
+  format,
+  hostOptions,
+  isReportBand,
+  splits,
+  styledRuns,
+  text,
+  walk,
+} from "quario";
 
 /** @type {Record<string, string>} */
 let ESC = {
@@ -43,19 +53,33 @@ let shown = (value, style, intl) => {
 // not a difference against the cell's -- the engine already composed the two.
 // An unstyled run stays bare.
 /** @type {(styled: { style: any, tokens: any[] }, style: any, intl: any, map: any) => string} */
-let piece = (styled, style, intl, map) => {
-  let body = joined(styled.tokens, styled.style ?? style, intl);
+let styledRun = (styled, style, intl, map) => {
+  let worn = styled.style ?? style;
+  let body = linked(joined(styled.tokens, worn, intl), worn);
   if (!styled.style) return body;
   let inline = css(styled.style, map);
   return inline ? '<span style="' + esc(inline) + '">' + body + "</span>" : body;
 };
 
+// A run that carries an `href` is wrapped in an anchor, inside its own span so
+// the style the run declared paints the link as well. The style asked is the
+// one the run wears rather than the one it declares, because `href` sits on a
+// cell as well as on a run (SCHEMA.md, "Style declarations") and a cell's own
+// links every run that declared no other. The engine admitted the
+// URL against the host's scheme allowlist before it crossed (docs/adr/0085);
+// this target escapes it like every other interpolated value and decides
+// nothing about it. An `<a>` is keyboard-reachable for nothing, which is why
+// this is a real anchor rather than a styled span with a click handler.
+/** @type {(body: string, style: any) => string} */
+let linked = (body, style) =>
+  style?.href ? '<a href="' + esc(style.href) + '">' + body + "</a>" : body;
+
 // A cell's markup: its styled runs in order. The grouping is the engine's
 // `styledRuns`, so this target cannot drift from the others.
 /** @type {(map: any) => (tokens: any[], style?: any, intl?: any) => string} */
 let cellMarkup = (map) => (tokens, style, intl) => {
   let out = "";
-  for (let styled of styledRuns(tokens)) out += piece(styled, style, intl, map);
+  for (let styled of styledRuns(tokens)) out += styledRun(styled, style, intl, map);
   return out;
 };
 
@@ -86,14 +110,12 @@ let NAMEABLE = /^[A-Za-z0-9 _-]+$/;
 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
@@ -149,27 +171,29 @@ 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).
+// A declared flag is `true` or `false`: the engine drops every other shape
+// before a target sees it (SCHEMA.md, "Style declarations"), so a target maps
+// the vocabulary rather than checking it a second time.
 /** @type {(on: string, off: string) => (value: any) => string} */
-let flag = (on, off) => (value) => (value === true ? on : value === false ? off : "");
+let flag = (on, off) => (value) => (value ? on : off);
 /** @type {Record<string, (value: any, map: Record<string, string>) => string>} */
 let CSS = {
+  // A family is the one declaration whose value a host may name, so the map
+  // may still answer with nothing; the value itself is a non-empty string.
   family: (value, map) => {
-    if (typeof value !== "string" || !value) return "";
     let name = named(map, value);
     return name ? "font-family:" + name : "";
   },
-  size: (value) => (Number.isFinite(value) && value > 0 ? "font-size:" + value + "pt" : ""),
+  size: (value) => "font-size:" + value + "pt",
   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 : ""),
+  color: (value) => "color:" + value,
+  background: (value) => "background-color:" + value,
+  align: (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.
   // `placed` below lifts the name out before this map sees a slot item's.
-  valign: (value) => (VALIGNMENTS.includes(value) ? "vertical-align:" + value : ""),
+  valign: (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"),
@@ -177,14 +201,12 @@ let CSS = {
 
 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["padding" + side] = (value) => "padding-" + edge + ":" + value + "pt";
 }
-CSS.spaceBefore = (value) => (isPad(value) ? "margin-top:" + value + "pt" : "");
-CSS.spaceAfter = (value) => (isPad(value) ? "margin-bottom:" + value + "pt" : "");
+CSS.spaceBefore = (value) => "margin-top:" + value + "pt";
+CSS.spaceAfter = (value) => "margin-bottom:" + value + "pt";
 
 /** @type {(width: any) => boolean} */
 let isStroke = (width) => Number.isFinite(width) && width > 0;
@@ -211,11 +233,12 @@ let decoLine = (style) => {
   return parts;
 };
 
+// Only called where one of the two names is declared, so a style that draws
+// neither line is a style that turned one off.
 /** @type {(style: any) => string} */
 let decoration = (style) => {
   let parts = decoLine(style);
-  if (parts.length) return "text-decoration:" + parts.join(" ");
-  return style.underline === false || style.strikethrough === false ? "text-decoration:none" : "";
+  return parts.length ? "text-decoration:" + parts.join(" ") : "text-decoration:none";
 };
 
 /** @type {(name: string) => boolean} */
@@ -494,7 +517,7 @@ export function html(options) {
       };
       // Hidden items never reach the stream and a hidden cell arrives with no
       // tokens, so no visibility checks are needed in any handler below.
-      await walk(splits(stream(data)), {
+      await walk(collapse(splits(stream(data))), {
         // Nothing unless the render is unlicensed — then the fragment opens
         // with the marking badge: the engine's wording in this target's
         // element, escaped, so the badge stays childless whatever stream a
@@ -629,3 +652,53 @@ export function html(options) {
     },
   };
 }
+
+/**
+ * What this target makes of each declaration the support matrix names: one of
+ * the [fates](../../../CONTEXT.md#declaration-and-resolution) — `resolved`,
+ * `approximated`, `withdrawn` or `unread` — so a host can ask before it
+ * renders rather than reading the prose.
+ *
+ * **Hand-written, and gated rather than generated.** SCHEMA.md's matrix is the
+ * description a person maintains and this is the data a host reads; the repo's
+ * `test/capabilities.test.js` holds the two equal, which is the same bargain
+ * ADR 0014 makes for the band-role table. It carries no version of its own:
+ * the package that ships it is the version, and a second copy could only drift
+ * from it.
+ *
+ * Keyed by the **schema name** an author writes, so a host, a `required`
+ * marking and a problem message all index by one vocabulary. Two rows share
+ * the bare word `width`, so each is qualified by what carries it.
+ *
+ * It covers the declarations every official target states one fate for. A
+ * matrix row that summarises more than one declaration, or that describes a
+ * behaviour rather than a declaration, states no single fate and is absent
+ * here — an absent key means the spec does not answer, never that this target
+ * has no answer.
+ */
+export const capabilities = Object.freeze({
+  target: "html",
+  declarations: Object.freeze({
+    "page.header": "unread",
+    "page.footer": "unread",
+    break: "approximated",
+    reset: "withdrawn",
+    "page.margin": "resolved",
+    "header.height": "withdrawn",
+    groups: "resolved",
+    label: "withdrawn",
+    collapsed: "resolved",
+    "column.width": "approximated",
+    "slot.width": "resolved",
+    span: "resolved",
+    uppercase: "resolved",
+    href: "resolved",
+    spaceBefore: "resolved",
+    spaceAfter: "resolved",
+    format: "resolved",
+    family: "resolved",
+    valign: "resolved",
+    runs: "resolved",
+    alt: "resolved",
+  }),
+});

package/lib/style.css

@@ -73,8 +73,10 @@
   white-space: pre-line;
 }
 
+/* 1.4x the size it sits in, so a report default scales its headline with
+   its body. Unstyled, that is the host page's own body size. */
 .q-item.q-report-header {
-  font-size: 14pt;
+  font-size: 1.4em;
   font-weight: bold;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quario/html",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Tiny, escape-by-default HTML render target for quario. Semantic tables and a stable class contract.",
   "keywords": [
     "csp",
@@ -34,24 +34,25 @@
     "access": "public"
   },
   "scripts": {
-    "check": "npm run size && npm test && npm run test:browser",
+    "check": "npm run size && npm test",
+    "coverage:check": "c8 report --src lib/ --temp-directory=../../coverage/tmp --reporter=text --check-coverage --100",
     "size": "size-limit",
-    "test": "npm run test:unit && npm run test:types",
+    "test": "npm run test:unit && npm run test:browser && npm run test:types && npm run coverage:check",
     "test:browser": "node test/browser/setup.js",
     "test:types": "tsc && attw --pack . --profile esm-only --exclude-entrypoints style.css",
-    "test:unit": "node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
+    "test:unit": "c8 --clean=false --src lib/ --reporter=none --temp-directory=../../coverage/tmp node --disallow-code-generation-from-strings --test --test-concurrency=1 test/*.test.js",
     "prepack": "node -e \"require('fs').copyFileSync('../../LICENSE','LICENSE')\"",
     "postpack": "node -e \"require('fs').rmSync('LICENSE',{force:true})\""
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.3",
     "@size-limit/preset-small-lib": "^13.0.3",
-    "quario": "^0.10.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.10.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {