@quario/viewer 0.9.0 → 0.11.0

package/lib/index.js

@@ -14,15 +14,13 @@
  * and `@quario/viewer/register` performs the one-line define for hosts that
  * want it (docs/adr/0005-the-surfaces-are-custom-elements.md).
  *
- * Nothing here is markup: the sheet is a stack of canvases, and the list's
- * text reaches them as strings the painter draws, so the viewer has no
- * markup edge and adds no report content of its own. The unlicensed marking
- * rides on the list, one op per page, painted last — the same placement the
- * pdf target writes (docs/adr/0017-the-viewer-watermarks-the-sheet.md).
+ * Nothing here is markup: the sheet is a stack of canvases, so the viewer has
+ * no markup edge. The unlicensed marking rides on the list, one op per page,
+ * painted last (docs/adr/0017).
  *
- * The error panel is the only wording the viewer authors, and it is not
- * report content: it names which failure occurred, because no error knows
- * whether it was a mount, an update or an export (panel.js).
+ * The error panel is the only wording the viewer authors: it names which
+ * failure occurred, because no error knows whether it was a mount, an update
+ * or an export (panel.js).
  */
 import { Task, TaskStatus } from "@lit/task";
 import { LitElement, html } from "lit";
@@ -30,8 +28,10 @@ import { Landing, failures, options } from "@quario/landing";
 import { layout } from "@quario/layout";
 import { BUTTON } from "./button.js";
 import { CHROME, progress } from "./chrome.js";
-import { exports, faces, geometry, level, name, scheme } from "./check.js";
+import { LINKS } from "./links.js";
+import { exports, faces, geometry, level, name, outlined, scheme } from "./check.js";
 import { MENU, zoomMenu } from "./menu.js";
+import { OUTLINE, outlinePanel, outlineToggle } from "./outline.js";
 import { PANEL, label, panel } from "./panel.js";
 import { SURFACE, stage } from "./stage.js";
 import { EXPORTS, exportGroup, saveAs } from "./toolbar.js";
@@ -50,21 +50,19 @@ export const TAG = "quario-viewer";
 /**
  * The viewer element. Hosts assign `report`, `targets` and `data` (plus the
  * option properties `zoom`, `page`, `fonts`, `filename` and `colorScheme`)
- * and listen for `rendered` and `error`; rapid successive writes render only
- * the newest state, because the render pipeline is a task keyed on those
- * properties and the task's own call-id guard drops every superseded run
- * whole — including its failure, which is reported to no one (ADR 0005's
- * narrowed guarantee).
+ * and listen for `rendered` and `error`. Rapid successive writes render only
+ * the newest state: the task's call-id guard drops every superseded run
+ * whole, including its failure, which is reported to no one (ADR 0005).
  *
- * Removal is not destruction: disconnecting abandons in-flight work and
+ * Removal is not destruction: disconnecting stops the work in flight and
  * releases the resize observer, the properties persist, and reconnecting
- * re-renders from them. There is no `destroy()`.
+ * renders them again unless the last render landed. There is no `destroy()`.
  */
 export class QuarioViewer extends LitElement {
   // CHROME declares the default palette every other sheet paints from, so it
   // has to be in this list -- but anywhere in it: a custom property resolves
   // down the inherited chain, not by stylesheet order.
-  static styles = [CHROME, BUTTON, MENU, SURFACE, PANEL];
+  static styles = [CHROME, BUTTON, MENU, OUTLINE, SURFACE, LINKS, PANEL];
 
   // Properties only, no attributes: `report`, `targets`, `data` and `page`
   // are values no attribute could carry, and one door beats two.
@@ -77,6 +75,7 @@ export class QuarioViewer extends LitElement {
     fonts: { attribute: false },
     filename: { attribute: false },
     colorScheme: { attribute: false },
+    outline: { attribute: false },
   };
 
   // The stage is built once and never rebuilt: it is the one imperative thing
@@ -105,57 +104,65 @@ export class QuarioViewer extends LitElement {
   #reapply = false;
   /** @type {Set<string>} The exports in flight; their buttons disable. */
   #exporting = new Set();
+  /** Whether the outline module is on, committed from the property. */
+  #outlined = false;
+  /** Whether the reader has the panel open. The reader's, so a property
+   * write does not close what they opened. */
+  #outlineOpen = true;
+  /** @type {readonly any[]} The newest landed list's marks: the outline. */
+  #marks = [];
   /** @type {(() => void) | undefined} */
   #unwatch;
-  /**
-   * The newest swap's paint, which `renderComplete` waits behind. Bare, with
-   * no catch of its own: the stage settles a page it cannot draw rather than
-   * rejecting, so the chain below is reached whatever the pixels did.
-   *
-   * @type {Promise<void>}
-   */
-  #painting = Promise.resolve();
-
   // The whole async pipeline: keyed on the render properties, re-run when one
   // changes — `page` and `fonts` among them, since either moves where the
-  // pages break. The task's call-id guard is the latest-wins machinery; side
-  // effects — the stage swap and both events — live only in the callbacks
-  // below, which that guard restricts to the newest run, never in the task
-  // body a stale run still executes to completion. `null` is the "nothing to
-  // show" result: unlike the task primitive's own initial-state symbol it
-  // settles `taskComplete`, which is what lets `renderComplete` always answer.
+  // pages break. Side effects live only in the callbacks below, which the
+  // task's call-id guard restricts to the newest run, never in the task body a
+  // stale run still executes to completion. `null` is the "nothing to show"
+  // result: unlike the initial-state symbol it settles `taskComplete`, which
+  // is what lets `renderComplete` always answer.
   #task = new Task(this, {
     args: () => [this.report, this.targets, this.data, this.page, this.fonts, this.#landing.epoch],
-    task: async ([report, targets, data, page, fonts], { signal }) => {
+    task: async ([report, targets, data, page, fonts]) => {
+      // First, before anything that can throw: the debt opens by starting, so
+      // every way of not landing keeps it without saying so (ADR 0075). A
+      // host-option throw out of `#begin` is one of them.
+      this.#landing.owe();
       if (!this.#begin(report, targets)) return null;
       // The sheet's own target: the layout list, on the host's page and
       // fonts — the same two a host passes to `pdf()`, which is what makes
       // the preview page where the document pages.
       let target = layout({ page: /** @type {any} */ (page), fonts: /** @type {any} */ (fonts) });
       let list = await /** @type {any} */ (report).render(target, data);
-      // The engine takes no signal, so abandonment is the guards around this
-      // body; the check only spares the swap when the answer arrives after a
-      // disconnect mid-render.
-      if (this.#landing.dropped(signal, this.isConnected)) return this.#landing.abandon();
       return { list, fonts };
     },
     onComplete: (result) => {
-      if (result === null || !this.isConnected) return;
+      if (result === null || !this.isConnected) return this.#landing.nothing();
       // The swap sizes every page before it settles, so the reader's place
       // is held; the paint it awaits is what `rendered` waits for.
-      this.#painting = this.#stage.swap(result.list, result.fonts).then(() => {
-        this.#landing.land();
-        // A render that landed on the sheet takes the panel down: the panel
-        // says what is wrong with what the reader is looking at, and this is
-        // the moment that stops being true. A successful export is not that
-        // moment.
-        this.#failures.clear();
-        // After the paint, so the update the task queued has already run.
-        this.requestUpdate();
-        this.dispatchEvent(new CustomEvent("rendered"));
-      });
+      // The boundary takes the paint rather than a promise to report back
+      // with: it reads which run this is here, while this run is still the
+      // newest one. The work after the paint rides inside it, so the run
+      // ends — and `renderComplete` settles — once `rendered` has fired.
+      // Bare, with no catch: the stage settles a page it cannot draw rather
+      // than rejecting, so the chain is reached whatever the pixels did.
+      this.#marks = result.list.marks;
+      // `void`: the boundary owns this promise now, and a caller awaiting the
+      // paint asks `renderComplete` rather than holding a field of its own.
+      void this.#landing.land(
+        this.#stage.swap(result.list, result.fonts).then(() => {
+          // A render that landed on the sheet takes the panel down: the panel
+          // says what is wrong with what the reader is looking at, and this is
+          // the moment that stops being true. A successful export is not that
+          // moment.
+          this.#failures.clear();
+          // After the paint, so the update the task queued has already run.
+          this.requestUpdate();
+          this.dispatchEvent(new CustomEvent("rendered"));
+        }),
+      );
     },
     onError: (error) => {
+      this.#landing.fail();
       if (!this.isConnected) return;
       this.#announce(error, this.#kindOf(error));
     },
@@ -182,6 +189,8 @@ export class QuarioViewer extends LitElement {
     this.filename = undefined;
     /** @type {"light" | "dark" | "auto" | undefined} */
     this.colorScheme = undefined;
+    /** @type {boolean | undefined} */
+    this.outline = undefined;
   }
 
   /**
@@ -191,19 +200,17 @@ export class QuarioViewer extends LitElement {
    * render still landed, so `true` promises the sheet is done changing, not
    * that every page carries pixels. It never rejects — a failed
    * render is handled, on the panel and through the error event — and like
-   * every outcome here it answers for the newest render only.
+   * every outcome here it answers for the newest render only: the one that
+   * is newest when it settles, so a run starting behind it is the one it
+   * then waits for.
+   *
+   * After `updateComplete`, because a property written just before the ask
+   * starts its run in the update this waits for.
    *
    * @returns {Promise<boolean>}
    */
   get renderComplete() {
-    return this.updateComplete.then(() =>
-      this.#task.status === TaskStatus.INITIAL
-        ? this.#landing.landed
-        : this.#task.taskComplete.then(
-            () => this.#painting.then(() => this.#landing.landed),
-            () => false,
-          ),
-    );
+    return this.updateComplete.then(() => this.#landing.complete);
   }
 
   /** @param {Map<string, unknown>} changed */
@@ -229,6 +236,7 @@ export class QuarioViewer extends LitElement {
       <div class="qv-viewer" aria-busy=${String(busy)}>
         <div class="qv-bar">
           ${progress(busy)}
+          ${this.#outlineControl()}
           ${zoomMenu({
             mode: this.#mode,
             percent: Math.round(this.#stage.percent()),
@@ -241,6 +249,7 @@ export class QuarioViewer extends LitElement {
         </div>
         <div class="qv-body">
           ${this.#failures.showing ? panel(this.#failures.showing, () => this.#dismiss()) : ""}
+          ${this.#outlineAside()}
           ${this.#stage.element}
         </div>
       </div>
@@ -264,9 +273,9 @@ export class QuarioViewer extends LitElement {
     this.#unwatch ??= this.#stage.watch(() => {
       if (this.#mode === "fit" && this.#wanted() !== this.#stage.percent()) this.#apply();
     });
-    // Reconnect re-renders from the current properties — but only when the
-    // sheet stopped matching them: a render was abandoned mid-flight, or a
-    // property write landed while disconnected. The task's arguments did not
+    // Reconnect re-renders from the current properties — but only where a
+    // render is owed, which is every run that did not reach the sheet
+    // (ADR 0075). The task's arguments did not
     // change, so the epoch is what re-runs it; left alone, reparenting a
     // settled viewer costs nothing.
   }
@@ -283,16 +292,17 @@ export class QuarioViewer extends LitElement {
    * A property the host got wrong fails loudly even while there is nothing to
    * render yet: a misconfigured host is caught in development, not when the
    * report arrives. Nothing assigned yet is not a failure. Disconnected
-   * elements keep processing updates, so the guard is what makes removal
-   * abandon work rather than merely hide it.
+   * elements keep processing updates, so the guard is what stops a removed
+   * element working where nobody is looking; the debt the run opened stands
+   * either way, and reconnecting collects it.
    *
    * @param {unknown} report
    * @param {unknown} targets
+   * @returns {boolean} Whether there is a render to do.
    */
   #begin(report, targets) {
     if (this.#options.invalid) throw this.#options.invalid;
-    if (vacant(report, targets)) return null;
-    if (!this.isConnected) return this.#landing.abandon();
+    if (vacant(report, targets) || !this.isConnected) return false;
     exports(report, targets);
     return true;
   }
@@ -343,6 +353,15 @@ export class QuarioViewer extends LitElement {
         let used = scheme(this.colorScheme);
         if (gate("colorScheme")) this.style.colorScheme = used;
       },
+      // The panel opens with the module: turning it on is what a reader would
+      // do next, and the toggle is there to close it.
+      (gate) => {
+        let on = outlined(this.outline);
+        if (gate("outline")) {
+          this.#outlined = on;
+          this.#outlineOpen = true;
+        }
+      },
     ]);
     if (moved) this.#landing.epoch++;
   }
@@ -406,6 +425,29 @@ export class QuarioViewer extends LitElement {
     this.requestUpdate();
   }
 
+  /** The bar's outline toggle, while the module is on. */
+  #outlineControl() {
+    if (!this.#outlined) return "";
+    return outlineToggle({ open: this.#outlineOpen, toggle: () => this.#toggleOutline() });
+  }
+
+  /** The outline panel, while the module is on and the reader has it open. */
+  #outlineAside() {
+    if (!this.#outlined || !this.#outlineOpen) return "";
+    return outlinePanel({
+      marks: this.#marks,
+      go: (mark) => this.#stage.reveal(mark.page, mark.y),
+    });
+  }
+
+  /** Open or close the outline panel. Chrome moves; nothing re-renders the
+   * report, and a fitted sheet follows its narrower or wider box through the
+   * observer `watch()` started. */
+  #toggleOutline() {
+    this.#outlineOpen = !this.#outlineOpen;
+    this.requestUpdate();
+  }
+
   /**
    * Report one failure, wherever it came from: the panel for the reader, the
    * event for the host. Failures that reach neither — a superseded render's,

package/lib/links.js

@@ -0,0 +1,221 @@
+/**
+ * The links on the sheet: one focusable region per linked run, over the very
+ * rectangle the painter drew it in.
+ *
+ * `@quario/layout` writes one text op per run, carrying the destination the
+ * engine admitted beside the `x`, `y`, `w` and `h` it drew at (`docs/adr/0085`),
+ * so the geometry is the list's own and nothing here re-measures. A run that
+ * wraps across two lines is two ops, which is two regions — the correct
+ * rendering rather than a degradation, as it is in the PDF.
+ *
+ * **A region is an element, because a painted one is not reachable.** ADR 0085
+ * makes focusability and Enter activation part of done: a link a pointer can
+ * reach and a keyboard cannot is an accessibility defect shipped as a feature.
+ * An `<a>` and a `<button>` carry both from the platform, so this module owns
+ * where they sit and nothing about how they are worked.
+ *
+ * The two destinations take the two elements. A URL leaves the page, which is
+ * what an anchor is for, and it opens in a tab of its own so a reader reading a
+ * report never loses it. An `href` naming a group's `label` moves the sheet,
+ * which is what a button is for — the same step the outline panel takes, and
+ * `reveal` is the one that takes it.
+ *
+ * **A destination the report does not hold is no region at all**, as it is in
+ * the PDF: a surface cannot invent a place, and a dead link is worse than plain
+ * text. The first instance wins a repeated label, which is what `SCHEMA.md` asks
+ * an author to declare labels that differ for.
+ *
+ * This is the viewer's own, and it is **not** the editor's hit box (ADR 0061,
+ * ADR 0085): it carries a destination and no path, and a link in the editor's
+ * preview stays deliberately unclickable, because the author is editing the
+ * document rather than reading it.
+ *
+ * The sheet carries elements only in the [reach](../../../CONTEXT.md#reach)
+ * (ADR 0043), and so does this: the regions are rebuilt when the band of pages
+ * under the reader moves, or when the scale does. Nothing here is markup — the
+ * text goes in as a property and the destination as an attribute — so the
+ * viewer still has no markup edge.
+ */
+
+import { css } from "lit";
+
+/** How far either side of the view the regions reach, in pages. The editor's
+ *  overlay uses the same one page: enough that a scroll landing between two
+ *  frames never shows a linked run with nothing over it. */
+let PAD = 1;
+
+export let LINKS = css`
+  /* Above the page canvases, which are appended after this layer on every
+     swap. Both are positioned, so one line settles the order. */
+  .qv-links {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+  }
+
+  /* A region shows nothing: the run under it is already painted. What it
+     carries is the pointer, the focus ring and the platform's activation. */
+  .qv-link {
+    position: absolute;
+    display: block;
+    padding: 0;
+    border: none;
+    background: transparent;
+    cursor: pointer;
+  }
+
+  .qv-link:focus-visible {
+    outline: 2px solid var(--_focus);
+    outline-offset: 1px;
+  }
+`;
+
+/**
+ * @typedef {{ title: string, page: number, x: number, y: number }} Mark
+ * @typedef {{ op: any, page: number }} Linked A linked text op, and its page.
+ */
+
+/**
+ * The linked runs on pages `first` through `last`, in document order. Scans
+ * those pages rather than the document, because this is asked on every swap and
+ * every scroll and the answer is bounded by the view.
+ *
+ * @param {any} list A layout list.
+ * @param {number} first
+ * @param {number} last
+ * @returns {Linked[]}
+ */
+export let linksOn = (list, first, last) => {
+  /** @type {Linked[]} */
+  let out = [];
+  for (let page = first; page <= last; page++)
+    for (let op of list.pages[page].ops) if (op.kind === "text" && op.href) out.push({ op, page });
+  return out;
+};
+
+/**
+ * The document's named destinations, by label. The first instance wins a
+ * repeated one, as a reader scrolling to the first match would — the rule the
+ * PDF target's annotations follow, and the one `SCHEMA.md` states.
+ *
+ * @param {readonly Mark[]} marks The list's own outline entries.
+ * @returns {Map<string, Mark>}
+ */
+export let destinations = (marks) => {
+  /** @type {Map<string, Mark>} */
+  let byLabel = new Map();
+  for (let mark of marks) if (!byLabel.has(mark.title)) byLabel.set(mark.title, mark);
+  return byLabel;
+};
+
+/**
+ * Where one `href` goes: out of the document, to a place in it, or nowhere.
+ *
+ * @param {string} href The destination the engine admitted.
+ * @param {Map<string, Mark>} byLabel
+ * @returns {{ url: string, mark: null } | { url: null, mark: Mark } | null}
+ */
+export let destination = (href, byLabel) => {
+  if (!href.startsWith("#")) return { url: href, mark: null };
+  let mark = byLabel.get(href.slice(1));
+  return mark ? { url: null, mark } : null;
+};
+
+/**
+ * The layer of regions over one sheet.
+ *
+ * @param {{ sheet: HTMLElement, paged: any, ratio: () => number,
+ *   view: () => { top: number, bottom: number },
+ *   reveal: (page: number, y: number) => void }} of What the stage owns: the
+ *   element the regions hang in, the sheet that places its pages, the scale on
+ *   screen, the band the reader is looking at, and the step a named destination
+ *   takes.
+ */
+export let overlay = ({ sheet, paged, ratio, view, reveal }) => {
+  let layer = document.createElement("div");
+  layer.className = "qv-links";
+  sheet.append(layer);
+
+  /** @type {any} */
+  let list = null;
+  /** @type {Map<string, Mark>} */
+  let byLabel = new Map();
+  /** What is standing: the band it was built for and the scale it was placed
+   *  at. A scroll inside one band and a repaint at one scale both cost the
+   *  compare and nothing else. */
+  let standing = "";
+
+  /** @type {(el: HTMLElement, op: any, page: number) => void} */
+  let place = (el, op, page) => {
+    let px = ratio();
+    el.style.left = op.x * px + "px";
+    el.style.top = paged.topOf(page) + op.y * px + "px";
+    el.style.width = op.w * px + "px";
+    el.style.height = op.h * px + "px";
+  };
+
+  /** One region, or nothing where the destination is not in the document. The
+   *  run's text is the region's name: the words are painted on the canvas,
+   *  which is nothing but an image to a screen reader. */
+  /** @type {(found: Linked) => HTMLElement | null} */
+  let region = ({ op, page }) => {
+    let where = destination(op.href, byLabel);
+    if (!where) return null;
+    let el = where.url === null ? step(where.mark) : anchor(where.url);
+    el.className = "qv-link";
+    el.setAttribute("aria-label", op.text);
+    place(el, op, page);
+    return el;
+  };
+
+  /** @type {(url: string) => HTMLElement} */
+  let anchor = (url) => {
+    let el = document.createElement("a");
+    el.href = url;
+    el.target = "_blank";
+    el.rel = "noopener noreferrer";
+    return el;
+  };
+
+  /** @type {(mark: Mark) => HTMLElement} */
+  let step = (mark) => {
+    let el = document.createElement("button");
+    el.type = "button";
+    el.addEventListener("click", () => reveal(mark.page, mark.y));
+    return el;
+  };
+
+  let update = () => {
+    let band = view();
+    let span = paged.pagesIn(band.top, band.bottom, PAD);
+    // Nothing on the sheet has nothing to lay a region over. The resize
+    // observer the stage starts reports once as it begins watching, which is
+    // before any list has arrived.
+    if (!span) return;
+    let wanted = span.first + ":" + span.last + ":" + ratio();
+    if (wanted === standing) return;
+    standing = wanted;
+    layer.replaceChildren();
+    for (let found of linksOn(list, span.first, span.last)) {
+      let el = region(found);
+      if (el) layer.append(el);
+    }
+  };
+
+  return {
+    /** Take the list the sheet is now showing, and build the regions under the
+     *  reader. A list with nothing to show leaves an empty layer. */
+    /** @type {(next: any) => void} */
+    swap(next) {
+      list = next;
+      byLabel = destinations(next.marks);
+      // The band and the scale may be the very ones the last list stood at,
+      // so the key is dropped rather than compared: what changed is the list.
+      standing = "";
+      layer.replaceChildren();
+      update();
+    },
+    /** Rebuild where the band or the scale has moved, and nowhere else. */
+    update,
+  };
+};

package/lib/menu.js

@@ -74,14 +74,12 @@ export let MENU = css`
     cursor: pointer;
   }
 
-  .qv-menuitem:hover {
-    background: var(--_hover);
-    color: var(--_icon-active);
-  }
-
-  /* Inset, so the ring stays inside the menu's own padding. */
-  .qv-menuitem:focus-visible {
-    outline: 2px solid var(--_focus);
+  /* A row's hover, active and focus treatment is \`button.js\`'s, shared with
+   every other <button> the viewer draws. The one difference is the ring's
+   side: inset, so it stays inside the menu's own padding. Narrower on
+   specificity rather than on where this sheet sits in \`static styles\` —
+   reordering that array must not silently put the ring back outside. */
+  .qv-viewer .qv-menuitem:focus-visible {
     outline-offset: -2px;
   }