@quario/viewer 0.9.0 → 0.11.0

package/lib/outline.js

@@ -0,0 +1,166 @@
+/**
+ * The outline panel: the report's group tree as a list of rows beside the
+ * sheet, each one a step to where that instance begins. The tree is the
+ * layout list's own `marks` — the entries the PDF target writes as bookmarks
+ * — so the panel derives it exactly as that target does, and an author
+ * declares nothing for it (`docs/adr/0044` for the icon, ADR 0047 for the
+ * chrome). A hollow instance is not a mark, so it is not a row.
+ *
+ * Optional: a host turns it on with the `outline` property, and the bar then
+ * carries one toggle. The reader opens and closes the panel; the property
+ * says only whether the module is there at all.
+ *
+ * A title goes in as a template value, never as markup — a group's key is
+ * report data — so this module has no markup edge to escape at (hard
+ * constraint 4).
+ */
+import { css, html } from "lit";
+import { button } from "./button.js";
+import { listTree } from "./icons.js";
+
+export let OUTLINE = css`
+  .qv-outline {
+    flex: none;
+    width: 220px;
+    min-width: 0;
+    overflow: auto;
+    padding: 6px;
+    background: var(--_bar);
+    border-right: 1px solid var(--_border);
+  }
+
+  .qv-outline ol {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  /* Each level steps in by one indent, written on the list rather than the
+   row, so a row's own box stays the full width the hover fills. */
+  .qv-outline ol ol {
+    padding-left: 12px;
+  }
+
+  .qv-outline-row {
+    display: block;
+    width: 100%;
+    padding: 4px 8px;
+    border: none;
+    border-radius: 5px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    text-align: left;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    cursor: pointer;
+  }
+
+  .qv-outline-empty {
+    margin: 0;
+    padding: 4px 8px;
+    color: var(--_icon);
+  }
+`;
+
+/**
+ * @typedef {{ title: string, depth: number, page: number, x: number, y: number }} Mark
+ * @typedef {{ mark: Mark, children: Node[] }} Node
+ */
+
+/**
+ * The marks as a tree: a mark is a child of the nearest mark before it at
+ * the depth above. Depth is the group's nesting, so the walk that emitted
+ * the marks in document order has already put every child after its parent.
+ *
+ * @param {readonly Mark[]} marks
+ * @returns {Node[]}
+ */
+export let tree = (marks) => {
+  /** @type {Node[]} */
+  let roots = [];
+  /** @type {Node[]} */
+  let open = [];
+  for (let mark of marks) {
+    /** @type {Node} */
+    let node = { mark, children: [] };
+    open.length = mark.depth;
+    (open[mark.depth - 1]?.children ?? roots).push(node);
+    open.push(node);
+  }
+  return roots;
+};
+
+/** @type {(event: HTMLElement) => HTMLElement[]} */
+let rows = (panel) => /** @type {HTMLElement[]} */ ([...panel.querySelectorAll(".qv-outline-row")]);
+
+/** @type {Record<string, (list: HTMLElement[], at: number) => HTMLElement>} */
+let MOVE = {
+  ArrowDown: (list, at) => list[Math.min(at + 1, list.length - 1)],
+  ArrowUp: (list, at) => list[Math.max(at - 1, 0)],
+  Home: (list) => list[0],
+  End: (list) => list[list.length - 1],
+};
+
+/**
+ * Arrow keys walk the rows in document order, whatever their depth; Tab
+ * leaves the panel as it left the bar. The platform owns activation.
+ *
+ * @param {KeyboardEvent} event
+ */
+let navigate = (event) => {
+  let move = MOVE[event.key];
+  if (!move) return;
+  event.preventDefault();
+  let list = rows(/** @type {HTMLElement} */ (event.currentTarget));
+  let at = list.indexOf(/** @type {HTMLElement} */ (event.target));
+  move(list, at).focus();
+};
+
+/**
+ * @param {Node[]} nodes
+ * @param {(mark: Mark) => void} go
+ * @returns {import('lit').TemplateResult}
+ */
+let branch = (nodes, go) => html`
+  <ol>
+    ${nodes.map(
+      (node) => html`
+        <li>
+          <button type="button" class="qv-outline-row" @click=${() => go(node.mark)}>
+            ${node.mark.title}
+          </button>
+          ${node.children.length ? branch(node.children, go) : ""}
+        </li>
+      `,
+    )}
+  </ol>
+`;
+
+/**
+ * The bar's toggle, drawn only while the module is on.
+ *
+ * @param {{ open: boolean, toggle: () => void }} state
+ */
+export let outlineToggle = ({ open, toggle }) => html`
+  <div class="qv-outline-toggle">
+    ${button({ title: open ? "Hide outline" : "Show outline", click: toggle, content: listTree })}
+  </div>
+`;
+
+/**
+ * The panel itself. A report with no groups has no tree, and the panel says
+ * so rather than standing empty.
+ *
+ * @param {{ marks: readonly Mark[], go: (mark: Mark) => void }} state
+ */
+export let outlinePanel = ({ marks, go }) => html`
+  <nav class="qv-outline" aria-label="Outline" @keydown=${navigate}>
+    ${
+      marks.length
+        ? branch(tree(marks), go)
+        : html`<p class="qv-outline-empty">This report has no groups.</p>`
+    }
+  </nav>
+`;

package/lib/panel.js

@@ -6,15 +6,13 @@
  * Always the compound — "the error panel", never a bare "panel", which stays
  * the word for the host's own UI regions around the viewer (see CONTEXT.md).
  *
- * It is the one place the viewer states wording of its own. Everything else it
- * shows comes from the report: the fragment is the html target's, and even the
- * unlicensed marking's wording arrives inside it. A label cannot, because no
- * error knows whether it was a mount, an update or an export that failed —
- * which is exactly what the error event's `kind` names.
+ * It is the one place the viewer states wording of its own: no error knows
+ * whether it was a mount, an update or an export that failed, which is what
+ * the error event's `kind` names.
  *
- * What it prints beside that label is the error's own message, as a template
- * value. That is a markup edge, and it stays one: a message can carry report
- * data, because a host's registry function is free to interpolate a row into
+ * Beside that label it prints the error's own message, as a template value.
+ * That is a markup edge and stays one: a message can carry report data,
+ * because a host's registry function is free to interpolate a row into
  * whatever it throws (hard constraint 4).
  */
 import { css, html } from "lit";

package/lib/stage.js

@@ -13,68 +13,46 @@
  *
  * The sheet carries the whole list's extent, but only the
  * [reach](../../../CONTEXT.md#reach) carries elements and pixels — the pages
- * on screen and one viewport height either side. The extent the reader scrolls
- * through is whole and synchronous whatever is standing, because the sheet is
- * given its height and width inline and paints the page silhouettes itself; a
- * page leaving the reach is removed, which takes its backing store with it
- * (ADR 0065). A scroll or a resize runs the same arithmetic over the list's own
- * geometry, coalesced to one pass a frame. ADR 0043 says what the reach is
- * worth: painting the whole sheet asked a thousand-page report for gigabytes of
- * backing store, and past what the browser would grant the pages simply came up
- * blank.
+ * on screen and one viewport height either side. The extent is whole and
+ * synchronous whatever is standing, because the sheet is given its height and
+ * width inline and paints the page silhouettes itself; a page leaving the
+ * reach is removed, which takes its backing store with it (ADR 0043, 0065).
  *
  * **A page the browser will not paint is blank, not a failure.** `start`
  * swallows and nothing here rejects: the report laid out and the list reached
- * the sheet, which is all a render promised, so the surfaces have no channel
- * for it and deliberately grow none.
- *
- * Little reaches it. An image that will not decode is the layout's own to
- * absorb — `paint` draws it as nothing and draws the page around it — and a
- * face is parsed with fontkit while the report is measured, so bytes that will
- * not parse are a render error long before the sheet. What is left is the face
- * fontkit accepted and the browser refuses, which the browser suite drives by
- * making `FontFace.prototype.load` reject under a record handed straight to
- * `swap`.
+ * the sheet, which is all a render promised.
  *
  * **A canvas on the sheet is never re-pointed at a second paint.** `paint()`
  * awaits before it draws, so a canvas whose paint is still in flight is
- * *retired* rather than painted over or emptied: it comes off the sheet, its
- * pixels go back, and a fresh one stands in its place, so the superseded
- * paint draws into an element nobody is looking at. A canvas whose paint has
- * settled has nothing that could land late and is re-sized in place as before;
- * a page leaving the reach is removed either way, which takes its pixels with
- * it whether that paint has landed or not. Without this a zoom landing mid-paint could leave a page
- * carrying old-scale content on a new-scale canvas, with the memo below
- * calling it painted so that nothing repainted it again (ADR 0046).
+ * *retired*: it comes off the sheet and a fresh one stands in its place, so
+ * the superseded paint draws into an element nobody is looking at. Otherwise
+ * a zoom landing mid-paint could leave a page carrying old-scale content on a
+ * new-scale canvas, with the memo below calling it painted (ADR 0046). A
+ * canvas whose paint has settled is re-sized in place.
+ *
+ * Retirement is lazy: a scale change sizes the reach's CSS boxes at once but
+ * retires a page only when the repaint loop reaches it, so a page further
+ * down shows its old pixels stretched until its turn comes. The cost is that
+ * a retired page is a replaced `role="img"` node, which assistive technology
+ * sees swapped under it — accepted, because the alternative is a second
+ * element per page on a sheet ADR 0043 exists to keep cheap.
  *
- * Retirement is lazy, and only the paint is guarded. A scale change sizes the
- * reach's CSS boxes at once but retires a page only when the repaint loop
- * reaches it, so a page further down the reach shows its old pixels stretched
- * into the new box until its turn comes — the ordinary look of a zoom in
- * progress, not the artefact above. The cost is that a retired page is a
- * replaced `role="img"` node: assistive technology reading that page sees it
- * swapped under them. Judged acceptable because retirement only happens while
- * that very page is mid-repaint and about to change what it shows anyway, and
- * because the alternative — a stable wrapper element per page to announce
- * from — is a second element per page on a sheet ADR 0043 exists to keep
- * cheap.
+ * The linked runs get a **focusable region each**, in `links.js`, hung on the
+ * sheet over the rectangles the painter drew them in and rebuilt as the band
+ * under the reader or the scale moves. They follow the reach for the reason the
+ * pages do, and this file owns the two numbers they need: the band, and the
+ * scale on screen.
  *
  * What the stage does not decide is which percentage to show: `fit()`
  * measures what would make one page 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.
- *
- * The editor builds its own stack of pages next door, and deliberately: what
- * the two surfaces share is the display list and the size of a point, not the
- * sheet. Each is a canvas element, a device-pixel size and a `paint()` call
- * around policy neither could lend the other — this one repaints under zoom
- * and guards a superseded repaint, that one builds once per swap and lays box
- * elements over the result.
+ * owns the policy over that answer. `percent()` reports what is on screen, so
+ * no caller keeps a second copy.
  */
 
 import { css } from "lit";
 import { GUTTER, sheet } from "@quario/landing";
 import { PX_PER_POINT } from "@quario/layout";
+import { overlay } from "./links.js";
 
 // `GUTTER` comes from `@quario/landing`, which walks the reach over it: the CSS
 // below and the sheet's own arithmetic have to agree about where a page sits,
@@ -130,6 +108,7 @@ export let SURFACE = css`
  *   percent: () => number, scale: (percent: number) => void,
  *   resize: (geometry: PageBox) => void,
  *   swap: (list: any, fonts: any) => Promise<void>,
+ *   reveal: (page: number, y: number) => void,
  *   watch: (changed: () => void) => () => void }} Stage
  */
 
@@ -169,7 +148,42 @@ export let stage = () => {
    * the elements above stay this file's, because the CSS is the viewer's own
    * public surface. */
   let paged = sheet(scroll, sheetEl, ratio);
-  return {
+
+  /** The band of the sheet the reader is looking at, in the sheet's own CSS
+   *  pixels: the frame a page is placed in. The sheet starts one gutter down
+   *  the scroll extent, which is the same offset `reveal` scrolls through. */
+  let view = () => {
+    let top = scroll.scrollTop - GUTTER;
+    return { top, bottom: top + scroll.clientHeight };
+  };
+
+  /** The focusable regions over the linked runs. The viewer's own and not the
+   *  editor's, which is the whole of ADR 0085's "a link in the editor's
+   *  preview is not clickable". */
+  let links = overlay({
+    sheet: sheetEl,
+    paged,
+    ratio,
+    view,
+    reveal: (page, y) => api.reveal(page, y),
+  });
+
+  /** One region pass a frame, however many scrolls ask — the same coalescing
+   *  the sheet's own reach pass uses, and a separate listener because the two
+   *  answer different questions about the same scroll. */
+  let following = false;
+  let follow = () => {
+    if (following) return;
+    following = true;
+    requestAnimationFrame(() => {
+      following = false;
+      links.update();
+    });
+  };
+  scroll.addEventListener("scroll", follow);
+
+  /** @type {Stage} */
+  let api = {
     element: scroll,
 
     /**
@@ -191,23 +205,19 @@ export let stage = () => {
 
     /**
      * 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. A sheet with no list
-     * on it has no view to hold, which is what mounting at an authored zoom
-     * takes. Asked of the list rather than of the sheet's children, which
-     * since ADR 0065 are the reach's and can be none of them while a list is
-     * standing — and it saves a DOM read besides.
+     * scaling about the sheet's corner would throw the reader back toward the
+     * top-left of what 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 — exactly when
+     * `scrollLeft` is 0 — and its margins are 0 once it overflows. A sheet
+     * with no list on it has no view to hold. Asked of the list rather than
+     * the sheet's children, which since ADR 0065 are the reach's and can be
+     * none of them while a list is standing.
      *
-     * Only the reach is repainted, and only where the scale actually changed,
-     * so a zoom step costs a handful of pages however long the report is.
+     * Only the reach is repainted, and only where the scale actually changed.
      */
     scale: (percent) => {
-      let held = paged.count() > 0 && {
+      let held = paged.width() !== null && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
         height: scroll.clientHeight,
@@ -222,6 +232,7 @@ export let stage = () => {
         scroll.scrollLeft = (held.left + held.width / 2) * ratioOf - held.width / 2;
       }
       void paged.repaint();
+      links.update();
     },
 
     /**
@@ -236,22 +247,17 @@ export let stage = () => {
     },
 
     /**
-     * Put a laid-out report on the sheet, keeping the reader where they
-     * were: the extent whole at once, with the reach's pages painted at the
-     * applied scale. The order is the point of the method: the sheet takes its
-     * height from the list before anything else, so the browser clamps the
-     * offsets going back against the extent the sheet will have rather than
-     * the one it had — and the reach is read from those offsets, so it is
-     * chosen after they are in. What the
-     * returned promise settles behind is the reach, which is what the caller's
-     * `renderComplete` means by "the pages on screen have finished trying to
-     * paint" — and **it never rejects**, because `start` swallows a page the
-     * browser will not draw and the reach walks on past it.
+     * Put a laid-out report on the sheet, keeping the reader where they were.
+     * The order is the point of the method: the sheet takes its height from
+     * the list first, so the browser clamps the offsets going back against
+     * the extent the sheet will have rather than the one it had, and the
+     * reach is read from those offsets afterwards. The returned promise
+     * settles behind the reach and **never rejects**.
      */
     swap: async (next, faces) => {
       // Reading the offsets flushes layout, so only an actual reswap pays for
       // it: with no list standing there is nothing scrolled to preserve.
-      let held = paged.count() > 0 && {
+      let held = paged.width() !== null && {
         top: scroll.scrollTop,
         left: scroll.scrollLeft,
       };
@@ -260,6 +266,24 @@ export let stage = () => {
         scroll.scrollTop = held.top;
         scroll.scrollLeft = held.left;
       }
+      // After the offsets go back, so the band the regions are built for is
+      // the one the reader is left looking at.
+      links.swap(next);
+    },
+
+    /**
+     * Scroll so that a point on a page sits at the top of the view: the
+     * outline's step to where an instance begins. The offset is the sheet's
+     * own — `topOf()` is where the sheet places that page, and the point
+     * scales as the page does — so this restates no stacking (ADR 0070).
+     * Horizontal stays where the reader left it.
+     *
+     * @param {number} page
+     * @param {number} y In points, down that page.
+     */
+    reveal: (page, y) => {
+      scroll.scrollTop = GUTTER + paged.topOf(page) + y * ratio();
+      paged.follow();
     },
 
     /**
@@ -273,10 +297,12 @@ export let stage = () => {
         // A resize that changes the fit repaints through `changed()`; one
         // that does not still moved the viewport the reach is measured in.
         paged.follow();
+        follow();
         changed();
       });
       observer.observe(scroll);
       return () => observer.disconnect();
     },
   };
+  return api;
 };

package/lib/zoom.js

@@ -5,24 +5,17 @@
  * 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.
+ * like a photograph, so line breaks, column widths and point sizes stay what
+ * they are at 100%. Letting the sheet's width follow the viewer would lay the
+ * report out differently from the document the pdf target pages, and the
+ * `page` property exists to promise those two agree.
  */
 
 /**
  * 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.
+ * The ends are therefore public API: moving the first or last entry widens or
+ * narrows what a host may author. Adding a stop between them is free.
  */
 export let STEPS = [25, 50, 75, 100, 150, 200];
 

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@quario/viewer",
-  "version": "0.9.0",
-  "description": "The embeddable report viewer shell for quario — in the makings, not yet released",
+  "version": "0.11.0",
+  "description": "Tiny, embeddable report viewer for quario. A custom element that pages on screen and exports what you hand it.",
+  "keywords": [
+    "csp",
+    "custom-element",
+    "quario",
+    "report",
+    "viewer"
+  ],
   "homepage": "https://getquario.com",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -33,19 +40,20 @@
     "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",
-    "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})\""
   },
   "dependencies": {
     "@lit/task": "^1.0.3",
-    "@quario/landing": "^0.2.1",
-    "@quario/layout": "^0.6.0",
+    "@quario/landing": "^0.3.1",
+    "@quario/layout": "^0.8.0",
     "lit": "^3.3.3"
   },
   "devDependencies": {
@@ -53,13 +61,12 @@
     "@cantoo/pdf-lib": "~2.9.1",
     "@size-limit/preset-small-lib": "^13.0.3",
     "esbuild": "^0.28.2",
-    "exceljs": "^4.4.0",
-    "quario": "^0.9.0",
+    "quario": "^0.11.0",
     "size-limit": "^13.0.3",
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
-    "quario": "^0.9.0"
+    "quario": "^0.11.0"
   },
   "size-limit": [
     {
@@ -71,7 +78,7 @@
         "lit",
         "@lit/task"
       ],
-      "limit": "8.5 kB"
+      "limit": "9.5 kB"
     }
   ],
   "engines": {