@quario/viewer 0.1.0

package/lib/stage.js

@@ -0,0 +1,361 @@
+/**
+ * The stage: the surface a report is scaled on. It owns the scroll container
+ * the reader looks through, the wrapper that carries whatever extent the
+ * current scale needs, and the white sheet itself — their elements, their CSS,
+ * and every number relating the three.
+ *
+ * Scaling is `transform: scale()` from the sheet's top-left corner, with the
+ * wrapper sized to the scaled result: a transformed child grows no scroll
+ * extent of its own, so without the wrapper a zoomed-in report would simply be
+ * clipped.
+ *
+ * What the stage does not decide is which percentage to show: `fit()` measures
+ * what would make the sheet span the width available, and `zoom.js` owns the
+ * policy over that answer. What is on screen, though, is the stage's own —
+ * `percent()` reports it, so no caller keeps a second copy.
+ */
+
+import { css } from "lit";
+import { geometry } from "./check.js";
+import { FACE, angle, centres, size, span } from "./mark.js";
+
+/**
+ * Space around the sheet, in px. Read from here and nowhere else: the stage's
+ * margin in the CSS below, the width `fit()` measures against, and the offset
+ * `scale()` converts a scroll position through.
+ */
+let GUTTER = 28;
+
+export let SURFACE = css`
+/* Where scrollbars take width, the gutter is held whether one is showing or
+   not, which is what rules out a feedback loop in the observer \`watch()\`
+   starts: scaling sets the wrapper's height, the height is what decides
+   whether this element needs a vertical scrollbar, and a scrollbar that came
+   and went would change the width \`fit()\` measures. Reserving it permanently
+   means the width fit reads cannot move in response to the height fit writes.
+   Where scrollbars overlay instead, the width never moved to begin with and
+   this changes nothing. It also keeps the sheet from shifting sideways as a
+   report changes length under an update. */
+.qv-scroll {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+  scrollbar-gutter: stable;
+}
+
+/* The wrapper carries the margin and the scroll extent: a margin on a scaled
+   child scales with it, and a transformed child grows no extent at all. Only
+   the vertical margin is the gutter as such — the horizontal ones centre
+   whatever slack the fit left over. */
+.qv-stage {
+  margin: ${GUTTER}px auto;
+}
+
+/* Sheet is the containing block for on-sheet watermark stamps. */
+.qv-sheet {
+  position: relative;
+  box-sizing: border-box;
+  transform-origin: 0 0;
+  background: #fff;
+  color: #000;
+  font: 10pt/1.4 system-ui, sans-serif;
+  box-shadow: var(--_sheet-shadow);
+}
+
+/* Stamps live under the sheet's transform so zoom/fit scales them. Absolute
+   layer clips rotated glyphs so they never widen scroll extent or feed \`fit()\`
+   — see docs/adr/0017-the-viewer-watermarks-the-sheet.md. */
+.qv-marks {
+  position: absolute;
+  inset: 0;
+  overflow: hidden;
+  pointer-events: none;
+  user-select: none;
+  z-index: 1;
+}
+
+.qv-mark {
+  position: absolute;
+  left: 50%;
+  height: 0;
+  width: 0;
+  overflow: visible;
+  text-align: center;
+}
+
+.qv-mark span {
+  display: inline-block;
+  white-space: nowrap;
+  color: var(--_mark);
+  opacity: 0.15;
+}
+`;
+
+/**
+ * @typedef {{ width: number, height: number, margin: number }} PageBox
+ * @typedef {{ text: string, turn: number, fontSize: number }} Face
+ * @typedef {{ element: HTMLElement, fit: () => number | null,
+ *   percent: () => number, scale: (percent: number) => void,
+ *   resize: (geometry: PageBox) => void,
+ *   swap: (fragment: string) => void,
+ *   watch: (changed: () => void) => () => void }} Stage
+ */
+
+/** @type {(sheet: HTMLElement, text: string, pxPerPt: number) => number} */
+let measure = (sheet, text, pxPerPt) => {
+  let probe = document.createElement("span");
+  probe.style.cssText =
+    "position:absolute;visibility:hidden;white-space:nowrap;font:" +
+    FACE +
+    "pt system-ui,sans-serif";
+  probe.textContent = text;
+  sheet.append(probe);
+  let width = probe.offsetWidth / pxPerPt;
+  probe.remove();
+  return width;
+};
+
+/** @type {(sheet: HTMLElement, page: PageBox) => number} */
+let rateOf = (sheet, page) => (page.width ? sheet.offsetWidth / page.width : 0);
+
+/**
+ * @param {HTMLElement} sheet
+ * @param {PageBox} page
+ * @param {string} text
+ * @param {number} pxPerPt
+ * @returns {Face}
+ */
+let faceAt = (sheet, page, text, pxPerPt) => ({
+  text,
+  turn: angle(page.width, page.height),
+  fontSize: size(span(page.width, page.height), measure(sheet, text, pxPerPt)),
+});
+
+/**
+ * @param {HTMLElement} sheet
+ * @param {PageBox} page
+ * @returns {Face | null}
+ */
+let faceOf = (sheet, page) => {
+  let badge = sheet.querySelector(".q-unlicensed");
+  let pxPerPt = rateOf(sheet, page);
+  if (!badge || !(pxPerPt > 0)) return null;
+  return faceAt(sheet, page, badge.textContent ?? "", pxPerPt);
+};
+
+/**
+ * @param {Face} face
+ * @param {number} y
+ * @returns {HTMLElement}
+ */
+let stampAt = (face, y) => {
+  let mark = document.createElement("div");
+  mark.className = "qv-mark";
+  mark.style.top = y + "pt";
+  let wording = document.createElement("span");
+  wording.textContent = face.text;
+  wording.style.font = face.fontSize + "pt system-ui, sans-serif";
+  wording.style.transform = "translate(-50%, -50%) rotate(" + face.turn + "deg)";
+  mark.append(wording);
+  return mark;
+};
+
+/**
+ * @param {HTMLElement} sheet
+ * @param {Face} face
+ * @param {number} sheetPt
+ * @param {number} pageHeight
+ */
+let paintMarks = (sheet, face, sheetPt, pageHeight) => {
+  let layer = document.createElement("div");
+  layer.className = "qv-marks";
+  layer.setAttribute("aria-hidden", "true");
+  for (let y of centres(sheetPt, pageHeight)) layer.append(stampAt(face, y));
+  sheet.append(layer);
+};
+
+/** @type {(sheet: HTMLElement) => void} */
+let clearMarks = (sheet) => {
+  for (let node of sheet.querySelectorAll(".qv-marks")) node.remove();
+};
+
+/**
+ * @param {HTMLElement} sheet
+ * @param {Face} face
+ * @param {PageBox} page
+ */
+let placeMarks = (sheet, face, page) => {
+  let pxPerPt = rateOf(sheet, page);
+  if (!(pxPerPt > 0)) return;
+  paintMarks(sheet, face, sheet.offsetHeight / pxPerPt, page.height);
+};
+
+/**
+ * Build the stage and take ownership of the sheet's scale. The element
+ * renders `element` into its template; everything else about the three
+ * elements stays in here. Geometry arrives through `resize` rather than
+ * construction, because the `page` property can change over the element's
+ * lifetime.
+ *
+ * @returns {Stage}
+ */
+export let stage = () => {
+  let scroll = document.createElement("div");
+  scroll.className = "qv-scroll";
+  let wrapper = document.createElement("div");
+  // The class names the part that carries the scroll extent; "the stage" in
+  // the glossary is this whole surface, the way `.qv-viewer` is one element
+  // inside the viewer. The `qv-*` names are documented as stable, so the
+  // narrower one keeps its name.
+  wrapper.className = "qv-stage";
+  let sheet = document.createElement("div");
+  sheet.className = "qv-sheet";
+  wrapper.append(sheet);
+  scroll.append(wrapper);
+
+  let page = geometry(undefined);
+  /** @type {Face | null} */
+  let face = null;
+
+  /**
+   * Show the marking this fragment carries, or none. Wording is the engine's
+   * on the html target's badge; stamps are presentation on the sheet (ADR 0017).
+   * `fresh` remeasures the face (swap / page change); height-only updates reuse it.
+   *
+   * @param {boolean} [fresh]
+   */
+  let marking = (fresh = true) => {
+    clearMarks(sheet);
+    if (fresh) face = null;
+    face ??= faceOf(sheet, page);
+    if (face) placeMarks(sheet, face, page);
+  };
+
+  /** The percentage currently on screen. */
+  let applied = 100;
+
+  // Write the scale and size the wrapper against it. Both reads are layout
+  // metrics, unaffected by the transform, so the wrapper is sized from the
+  // sheet's own untransformed box — and both come before any write, so a
+  // paint costs one layout pass rather than one per measurement.
+  let paint = () => {
+    let factor = applied / 100;
+    let width = sheet.offsetWidth;
+    let height = sheet.offsetHeight;
+    sheet.style.transform = factor === 1 ? "" : "scale(" + factor + ")";
+    wrapper.style.width = width * factor + "px";
+    wrapper.style.height = height * factor + "px";
+  };
+
+  return {
+    element: scroll,
+
+    /**
+     * The percentage at which the sheet spans the width available to it, or
+     * `null` when there is nothing to measure against — a `display: none`
+     * host, or a pane narrower than its own gutters. A caller with nothing to
+     * compute from keeps what is on screen rather than scaling to a guess.
+     */
+    fit: () => {
+      let usable = scroll.clientWidth - 2 * GUTTER;
+      let width = sheet.offsetWidth;
+      if (usable <= 0 || !width) return null;
+      return (usable / width) * 100;
+    },
+
+    /** The percentage on screen. The only copy of it there is. */
+    percent: () => applied,
+
+    /**
+     * Scale to `percent`, holding the middle of the viewport where it was:
+     * scaling about the sheet's corner would otherwise throw the reader back
+     * toward the top-left of whatever they were reading. The sheet starts one
+     * gutter down the scroll extent, so the centre converts through that
+     * offset; horizontally the wrapper is centred by auto margins while it
+     * fits — which is exactly when `scrollLeft` is 0 anyway — and its margins
+     * are 0 once it overflows, so the plain ratio holds wherever it can be
+     * seen. The browser clamps whatever it cannot honour. An empty sheet has
+     * no view to hold, which is what mounting at an authored zoom takes.
+     */
+    scale: (percent) => {
+      let held = sheet.firstChild && {
+        top: scroll.scrollTop,
+        left: scroll.scrollLeft,
+        height: scroll.clientHeight,
+        width: scroll.clientWidth,
+      };
+      let ratio = percent / applied;
+      applied = percent;
+      paint();
+      if (!held) return;
+      let middle = held.top + held.height / 2 - GUTTER;
+      scroll.scrollTop = GUTTER + middle * ratio - held.height / 2;
+      scroll.scrollLeft = (held.left + held.width / 2) * ratio - held.width / 2;
+    },
+
+    /**
+     * Give the sheet its point geometry. Page points are CSS points, so the
+     * host's values transfer unit-for-unit; the wrapper re-sizes against the
+     * result so the scroll extent keeps describing what is there. Height is
+     * the watermark stamp period (full page box), not a sheet height.
+     *
+     * @param {PageBox} next
+     */
+    resize: (next) => {
+      page = next;
+      sheet.style.width = next.width + "pt";
+      sheet.style.padding = next.margin + "pt";
+      marking(true);
+      paint();
+    },
+
+    /**
+     * Put a rendered fragment on the sheet, keeping the reader where they
+     * were. The order is the point of the method: the wrapper takes the new
+     * content's height before the offsets go back, so the browser clamps them
+     * against the extent they will have rather than the one they had.
+     */
+    swap: (fragment) => {
+      // Reading the offsets flushes layout, so only an actual reswap pays for
+      // it: on an empty sheet there is nothing scrolled to preserve.
+      let held = sheet.firstChild && { top: scroll.scrollTop, left: scroll.scrollLeft };
+      // The viewer's one markup edge. What goes in is the html target's
+      // documented output, injected the documented way. Watermark stamps are
+      // presentation synthesized after from the badge (ADR 0017) — not report
+      // content (hard constraint 4).
+      sheet.innerHTML = fragment;
+      face = null;
+      marking(true);
+      // A resize, not a zoom — the scale has not changed, so nothing
+      // recentres here or it would fight the restore below.
+      paint();
+      if (held) {
+        scroll.scrollTop = held.top;
+        scroll.scrollLeft = held.left;
+      }
+    },
+
+    /**
+     * Watch the box for changes the viewer learns of no other way — a
+     * collapsed side panel, a resized window, a flex sibling appearing — so a
+     * fitted sheet can follow its host. Also watches sheet height so stamp
+     * density tracks layout. Returns the disposer; what rules out a fit
+     * feedback loop is the CSS above.
+     */
+    watch: (changed) => {
+      let last = sheet.offsetHeight;
+      let observer = new ResizeObserver(() => {
+        let height = sheet.offsetHeight;
+        if (height !== last) {
+          last = height;
+          marking(false);
+          paint();
+        }
+        changed();
+      });
+      observer.observe(scroll);
+      observer.observe(sheet);
+      return () => observer.disconnect();
+    },
+  };
+};

package/lib/style.js

@@ -0,0 +1,94 @@
+/**
+ * The canonical `q-*` report stylesheet the viewer adopts into its shadow
+ * root: how a quario HTML fragment looks on the sheet. The selector contract
+ * is the html target's stable markup (SCHEMA.md, "The HTML target"): every
+ * item is `.q-item.q-<role>`, every group instance `.q-group[data-group]`,
+ * every table `.q-table`, and a keyless render opens with `.q-unlicensed`.
+ *
+ * `@quario/html` ships the same look as a real stylesheet its consumers can
+ * link (`@quario/html/style.css`, and see ADR 0016). This file cannot import
+ * it -- the viewer depends on no target package at runtime, and Lit wants a
+ * `css` template rather than a file -- so the block between the `shared:`
+ * markers below is byte-identical to the one there, and
+ * `test/stylesheet.test.js` at the repo root fails when they drift. Edit one,
+ * edit the other.
+ *
+ * Two things stay outside that block, in each direction. The html sheet adds
+ * pagination rules a sheet has no use for: it can be printed, this cannot.
+ * And the marking diverges on mechanism rather than on result -- a plain host
+ * document scales nothing, so there `.q-unlicensed` can carry a watermark
+ * itself; here it cannot, and `stage.js` says why.
+ */
+import { css } from "lit";
+
+export let REPORT = css`
+/* shared:start */
+.q-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.q-table th,
+.q-table td {
+  padding: 2pt 6pt;
+  text-align: left;
+}
+
+.q-table thead th {
+  border-bottom: 0.5pt solid #000;
+}
+
+.q-table tfoot td {
+  border-top: 0.5pt solid #000;
+  font-weight: bold;
+}
+
+.q-item.q-report-header {
+  font-size: 14pt;
+  font-weight: bold;
+}
+
+.q-item.q-group-header {
+  margin-top: 8pt;
+  font-weight: bold;
+}
+
+.q-item.q-group-footer {
+  margin-bottom: 8pt;
+}
+
+.q-item.q-report-footer {
+  margin-top: 10pt;
+  border-top: 1pt solid #000;
+  padding-top: 4pt;
+}
+
+/* A columned container is a fragmentation context on screen, not only in
+   print, so this is what keeps a label whole in one page column -- the rule
+   SCHEMA.md's "Page columns" leans on. Scoped to a columned region, so an
+   uncolumned report pays nothing. Inside the shared block because both sheets
+   need it: a sheet has no pages, but it can have columns. */
+.q-columns .q-group {
+  break-inside: avoid;
+}
+/* shared:end */
+
+/* The unlicensed-evaluation badge (LICENSE section 6). The viewer presents the
+   marking as on-sheet watermark stamps instead -- \`.qv-mark\`, in stage.js
+   (ADR 0017) -- so the badge itself is hidden from sight but kept in the
+   accessibility tree: the document is what states the marking, and the
+   watermark is decoration announcing nothing. Hiding it with \`display: none\`
+   would take the statement away from the readers least able to see the
+   watermark. */
+.q-unlicensed {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+`;

package/lib/toolbar.js

@@ -0,0 +1,95 @@
+/**
+ * The capability-driven export group: one button per exportable target the
+ * host passed, in the order they were given. It sits at the right of the
+ * viewer's bar, beside the zoom menu; no exportable target, no group.
+ * The element owns the click — rendering with its current data and
+ * auto-downloading through `download` below — because only it knows
+ * whether it is still connected when the file arrives.
+ *
+ * The icon's label goes in as a template value, never as a string spliced
+ * into a document, so this module has no markup edge to escape at and never
+ * grows one (hard constraint 4).
+ */
+import { html, nothing } from "lit";
+import { button } from "./button.js";
+
+/** The exportable targets: content type and button wording. */
+/** @type {Record<string, { type: string, label: string }>} */
+export let EXPORTS = {
+  pdf: { type: "application/pdf", label: "PDF" },
+  xlsx: {
+    type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    label: "XLSX",
+  },
+  csv: { type: "text/csv", label: "CSV" },
+};
+
+// Sheet outline with a folded corner, over the format's name.
+/** @type {(label: string) => import('lit').TemplateResult} */
+let icon = (label) => html`
+  <svg viewBox="0 0 20 20" width="19" height="19" aria-hidden="true">
+    <g fill="none" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round">
+      <path d="M4.5 2.5h7l4 4v11h-11z"></path>
+      <path d="M11.5 2.5v4h4"></path>
+    </g>
+    <text
+      x="10"
+      y="14.5"
+      text-anchor="middle"
+      font-size="5"
+      font-weight="700"
+      letter-spacing="0.2"
+      fill="currentColor"
+    >
+      ${label}
+    </text>
+  </svg>
+`;
+
+// The anchor joins the document for the click — detached-anchor downloads
+// are unreliable outside Chromium — and the URL is revoked well after the
+// browser has had time to start reading the blob.
+/** @type {(body: string | Uint8Array<ArrayBuffer>, name: string, type: string) => void} */
+export let download = (body, name, type) => {
+  let url = URL.createObjectURL(new Blob([body], { type }));
+  let anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = name;
+  anchor.hidden = true;
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 30_000);
+};
+
+/**
+ * The export group, or nothing when no exportable target was passed — then
+ * the viewer's bar carries the zoom menu alone.
+ *
+ * @param {readonly any[] | undefined} targets The host's targets.
+ * @param {{ busy: Set<string>, click: (target: any) => void }} context
+ *   Which exports are in flight (their buttons disable), and the element's
+ *   own click handler — a click has no promise the host can catch.
+ * @returns {import('lit').TemplateResult | typeof nothing}
+ */
+export let exportGroup = (targets, context) => {
+  let exportable = (targets ?? []).filter((/** @type {any} */ target) =>
+    Object.hasOwn(EXPORTS, target?.name),
+  );
+  if (!exportable.length) return nothing;
+  return html`
+    <div class="qv-exports">
+      ${exportable.map((target) => {
+        let { label } = EXPORTS[target.name];
+        return button({
+          // The icon carries the format, so the button takes no text of its own.
+          title: "Download " + label,
+          name: target.name,
+          disabled: context.busy.has(target.name),
+          click: () => context.click(target),
+          content: icon(label),
+        });
+      })}
+    </div>
+  `;
+};

package/lib/zoom.js

@@ -0,0 +1,45 @@
+/**
+ * The zoom policy: the percentages the menu offers and what fit resolves to.
+ * Pure functions, no DOM — the menu that presents them lives in `menu.js`,
+ * and scaling itself belongs to the stage, which measures the fit and writes
+ * it (see stage.js).
+ *
+ * The preview **scales; it never reflows**. Fit shrinks the rendered sheet
+ * like a photograph, so line breaks, column widths and point sizes stay
+ * exactly what they are at 100%. Letting the sheet's width follow the viewer
+ * instead would keep small text readable, but it would lay the report out
+ * differently from the document the pdf target will page — and the `page`
+ * property exists to promise those two agree. A legible-at-any-width reading mode
+ * would be a separate feature under its own name, not something fit becomes
+ * quietly.
+ */
+
+/**
+ * The percentages the menu offers, and — through its ends — the range the
+ * `zoom` property accepts (check.js reads them, so the two cannot drift).
+ *
+ * The ends are therefore public API, not a menu detail: moving the first or
+ * last entry widens or narrows what a host may author. `viewer.test.js` spells
+ * the current range out in the message it expects, so such a move fails a test
+ * that says so rather than passing quietly. Adding a stop between the ends is
+ * free.
+ */
+export let STEPS = [25, 50, 75, 100, 150, 200];
+
+/**
+ * The percentage the policy asks for. Fit is shrink-only — it never enlarges
+ * past 100%, so a viewer with room to spare shows the report at its true
+ * point size — and unbounded below, so it always genuinely fits, even at
+ * percentages the menu can never return to.
+ *
+ * @param {"fit" | number} mode
+ * @param {number | null} fitted What the stage measured, or `null` when there
+ *   is nothing to measure against.
+ * @param {number} current The percentage already on screen — kept when
+ *   fitting has no measurement, rather than scaling to a guess.
+ * @returns {number}
+ */
+export let wanted = (mode, fitted, current) => {
+  if (mode !== "fit") return mode;
+  return fitted === null ? current : Math.min(100, fitted);
+};

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@quario/viewer",
+  "version": "0.1.0",
+  "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
+  "homepage": "https://getquario.com",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getquario/quario.git",
+    "directory": "packages/viewer"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "lib"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./lib/register.js"
+  ],
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./register": {
+      "types": "./lib/register.d.ts",
+      "default": "./lib/register.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "npm run size && npm test && npm run test:browser",
+    "size": "size-limit",
+    "test": "npm run test:unit && npm run test:types",
+    "test:browser": "node test/browser/setup.js",
+    "test:types": "tsc && attw --pack . --profile esm-only",
+    "test:unit": "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})\""
+  },
+  "dependencies": {
+    "@lit/task": "^1.0.3",
+    "lit": "^3.3.3"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.3",
+    "@quario/csv": "^0.1.0",
+    "@quario/html": "^0.1.0",
+    "@quario/pdf": "^0.1.0",
+    "@quario/xlsx": "^0.1.0",
+    "@size-limit/preset-small-lib": "^13.0.3",
+    "esbuild": "^0.28.2",
+    "exceljs": "^4.4.0",
+    "pdf-lib": "^1.17.1",
+    "quario": "^0.1.0",
+    "size-limit": "^13.0.3",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "quario": "^0.1.0"
+  },
+  "size-limit": [
+    {
+      "path": "lib/index.js",
+      "ignore": [
+        "quario"
+      ],
+      "limit": "14 kB"
+    }
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}