@quario/viewer 0.3.0 → 0.5.0

package/lib/index.d.ts

@@ -1,18 +1,20 @@
 import type { LitElement } from "lit";
+import type { LayoutFonts, LayoutPage } from "@quario/layout";
 import type { CompiledReport, Target } from "quario";
 
 /**
- * Sheet geometry, in PostScript points — the pdf target's `PdfPage`
- * vocabulary, because the sheet stands in visually for the page configured
- * there. Purely visual: pass the same values to `pdf({ page })` so preview
- * and export agree.
+ * Page geometry, in PostScript points — the layout's own vocabulary, which
+ * the pdf target's `page` shares. The sheet is laid out on it: pass the same
+ * values to `pdf({ page })` and the preview pages where the document pages.
  */
-export interface ViewerPage {
-  /** Named size or `[width, height]` in points. Default `'A4'`. */
-  size?: "A4" | "letter" | [number, number];
-  /** Margin on all four sides, in points. Default `54` (0.75 in). */
-  margin?: number;
-}
+export type ViewerPage = LayoutPage;
+
+/**
+ * The font mapping: a declared `family` name to TrueType bytes, the same
+ * record a host passes to `pdf({ fonts })`. The layout measures against
+ * them and the sheet draws in them.
+ */
+export type ViewerFonts = LayoutFonts;
 
 /**
  * A compiled report, from a quario instance's `report()`. The instance —
@@ -29,8 +31,8 @@ export interface ViewerErrorDetail {
   /** The caught value, exactly as thrown. */
   error: unknown;
   /**
-   * Which failure occurred: `mount-render` until a render has ever reached
-   * the sheet, `update-render` after, `export` for a download that could not
+   * Which failure occurred: `mount-render` until a render has ever landed
+   * on the sheet, `update-render` after, `export` for a download that could not
    * be produced.
    */
   kind: ViewerErrorKind;
@@ -40,16 +42,18 @@ export interface ViewerErrorDetail {
  * The embeddable report viewer, `<quario-viewer>`. Assign `report`,
  * `targets` and `data` as properties (they are values no attribute could
  * carry) and listen for `rendered` and `error`; rapid successive writes
- * render only the newest state. Importing this module defines nothing —
- * import `@quario/viewer/register` for the one-line define, or call
+ * render only the newest state. The sheet is the report laid out on pages
+ * by `@quario/layout` — the list the pdf target writes — painted on one
+ * canvas per page. Importing this module defines nothing — import
+ * `@quario/viewer/register` for the one-line define, or call
  * `customElements.define` with a tag of your own.
  *
  * Failures split along one line: the host's own mistakes (a report that is
- * not compiled, a missing `"html"` target, a malformed option property)
- * throw a `TypeError` naming the property, delivered through the `error`
- * event and the error panel like every other failure; a report that could
- * not be rendered leaves the element up with the panel saying why. A
- * superseded render's failure is reported to no one.
+ * not compiled, a malformed option property) throw a `TypeError` naming the
+ * property, delivered through the `error` event and the error panel like
+ * every other failure; a report that could not be rendered leaves the
+ * element up with the panel saying why. A superseded render's failure is
+ * reported to no one.
  *
  * Removing the element abandons in-flight work and releases its observers;
  * the properties persist, and reconnecting re-renders from them. There is no
@@ -61,16 +65,17 @@ export class QuarioViewer extends LitElement {
   /** The compiled report to display and export. */
   report: ViewableReport | undefined;
   /**
-   * The configured targets, as passed to `report.render` — one must be named
-   * `"html"` to display; ones named `"pdf"`/`"xlsx"`/`"csv"` become
-   * export buttons, in array order.
+   * The export targets, as passed to `report.render`: ones named
+   * `"pdf"`/`"xlsx"`/`"csv"` become export buttons, in array order. The
+   * sheet needs none of them — it is the layout's own. An empty array is
+   * a viewer with nothing to export.
    */
   targets: readonly Target[] | undefined;
   /** The render document. Assigning re-renders; the newest write wins. */
   data: unknown;
   /**
    * The zoom to open at: `'fit'` (the default) or a percentage. Fit sizes
-   * the sheet to the viewer's width and is shrink-only — it never enlarges
+   * one page to the viewer's width and is shrink-only — it never enlarges
    * past 100%, so a viewer with room to spare shows the report at its true
    * point size. An authored percentage must be between 25 and 200, and is
    * continuous in that range rather than one of the zoom menu's own stops;
@@ -79,8 +84,10 @@ export class QuarioViewer extends LitElement {
    * computes them.
    */
   zoom: "fit" | number | undefined;
-  /** Sheet geometry. The preview approximates; exports are exact. */
+  /** Page geometry. Pass the same values to `pdf({ page })`. */
   page: ViewerPage | undefined;
+  /** Font mapping. Pass the same record to `pdf({ fonts })`. */
+  fonts: ViewerFonts | undefined;
   /** Export download name, without extension. Default `'report'`. */
   filename: string | undefined;
   /**
@@ -89,10 +96,11 @@ export class QuarioViewer extends LitElement {
    */
   colorScheme: "light" | "dark" | "auto" | undefined;
   /**
-   * The newest render settling: `true` when it reached the sheet, `false`
-   * when it failed or there was nothing to render. Never rejects — failures
-   * are the `error` event's — and like every outcome here it answers for
-   * the newest render only.
+   * The newest render settling: `true` when it landed on the sheet with the
+   * pages on screen painted, `false` when it failed or there was nothing to
+   * render. Never rejects — failures are the `error` event's — and like every
+   * outcome here it answers for the newest render only. `rendered` fires at
+   * that same moment.
    */
   get renderComplete(): Promise<boolean>;
 
@@ -120,7 +128,7 @@ export class QuarioViewer extends LitElement {
 
 /** The element's events. Both are non-bubbling, like `<img>`'s. */
 export interface QuarioViewerEventMap {
-  /** A render reached the sheet — the mount and every update. */
+  /** A render landed on the sheet — the mount and every update. */
   rendered: CustomEvent<undefined>;
   /** A failure the host should know about; `detail.kind` says which. */
   error: CustomEvent<ViewerErrorDetail>;

package/lib/index.js

@@ -1,22 +1,24 @@
 /**
  * @quario/viewer — the embeddable viewer element. Not a render target: it
  * compiles nothing and never touches the event stream. `<quario-viewer>`
- * consumes a compiled report plus the host's configured targets through
- * properties, displays the html target's fragment on a shadow-DOM sheet, and
- * offers export downloads for whichever exportable targets the host passed.
- * Outcomes reach the host as `rendered` and `error` events, plus
- * `renderComplete`, the one awaitable for the newest render settling.
+ * consumes a compiled report plus the host's configured export targets
+ * through properties, lays the report out on pages through `@quario/layout`
+ * and paints them on a shadow-DOM sheet — the same list the pdf target
+ * writes, so the preview breaks its pages where the document does
+ * (docs/adr/0039) — and offers export downloads for whichever exportable
+ * targets the host passed. Outcomes reach the host as `rendered` and `error`
+ * events, plus `renderComplete`, the one awaitable for the newest render
+ * settling.
  *
  * Importing this module defines nothing: the element class is the export,
  * and `@quario/viewer/register` performs the one-line define for hosts that
  * want it (docs/adr/0005-the-surfaces-are-custom-elements.md).
  *
- * Escaping stays exclusively the html target's job (its documented output is
- * injected the documented way), and the viewer adds no report content of its
- * own. The unlicensed marking is the one thing it presents rather than merely
- * styles: the wording still arrives inside the fragment, and the stage draws
- * repeating watermarks on the scaled sheet — see
- * docs/adr/0017-the-viewer-watermarks-the-sheet.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).
  *
  * 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
@@ -24,14 +26,14 @@
  */
 import { Task, TaskStatus } from "@lit/task";
 import { LitElement, html } from "lit";
+import { layout } from "@quario/layout";
 import { BUTTON } from "./button.js";
 import { CHROME, progress } from "./chrome.js";
-import { display, geometry, level, name, scheme } from "./check.js";
+import { exports, geometry, level, name, scheme } from "./check.js";
 import { MENU, zoomMenu } from "./menu.js";
 import { PANEL, label, panel } from "./panel.js";
 import { SURFACE, stage } from "./stage.js";
-import { REPORT } from "./style.js";
-import { EXPORTS, download, exportGroup } from "./toolbar.js";
+import { EXPORTS, exportGroup, saveAs } from "./toolbar.js";
 import { wanted } from "./zoom.js";
 
 /** @type {(report: unknown, targets: unknown) => boolean} */
@@ -45,18 +47,19 @@ let said = (error) => {
 
 // The properties are described once, in the hand-written public declarations,
 // and read back here — a second copy in JSDoc is a copy that drifts.
-/** @import { ViewableReport, ViewerPage } from './index.d.ts' */
+/** @import { ViewableReport, ViewerFonts, ViewerPage } from './index.d.ts' */
 
 /** The tag `@quario/viewer/register` defines the element under. */
 export const TAG = "quario-viewer";
 
 /**
  * The viewer element. Hosts assign `report`, `targets` and `data` (plus the
- * option properties `zoom`, `page`, `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).
+ * 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).
  *
  * Removal is not destruction: disconnecting abandons in-flight work and
  * releases the resize observer, the properties persist, and reconnecting
@@ -66,7 +69,7 @@ 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, REPORT];
+  static styles = [CHROME, BUTTON, MENU, SURFACE, PANEL];
 
   // Properties only, no attributes: `report`, `targets`, `data` and `page`
   // are values no attribute could carry, and one door beats two.
@@ -76,6 +79,7 @@ export class QuarioViewer extends LitElement {
     data: { attribute: false },
     zoom: { attribute: false },
     page: { attribute: false },
+    fonts: { attribute: false },
     filename: { attribute: false },
     colorScheme: { attribute: false },
   };
@@ -85,7 +89,7 @@ export class QuarioViewer extends LitElement {
   // fails and a disconnect that does not. The template interpolates its
   // element as a node, which lit-html leaves untouched across re-renders.
   #stage = stage();
-  /** Whether a render has ever reached the sheet — the mount/update boundary. */
+  /** Whether a render has ever landed on the sheet — the mount/update boundary. */
   #landed = false;
   /** Whether the sheet stopped matching the properties while disconnected. */
   #stale = false;
@@ -108,37 +112,49 @@ export class QuarioViewer extends LitElement {
   #exporting = new Set();
   /** @type {(() => void) | undefined} */
   #unwatch;
+  /** @type {Promise<void>} The newest swap's paint, which `renderComplete` waits behind. */
+  #painting = Promise.resolve();
 
   // The whole async pipeline: keyed on the render properties, re-run when one
-  // changes. The task's call-id guard is the latest-wins machinery; side
+  // 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.
   #task = new Task(this, {
-    args: () => [this.report, this.targets, this.data, this.#epoch],
-    task: async ([report, targets, data], { signal }) => {
+    args: () => [this.report, this.targets, this.data, this.page, this.fonts, this.#epoch],
+    task: async ([report, targets, data, page, fonts], { signal }) => {
       if (!this.#begin(report, targets)) return null;
-      let target = display(report, targets);
-      let fragment = await /** @type {any} */ (report).render(target, data);
+      // 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.#drop(signal)) return this.#abandon();
-      return fragment;
+      if (signal.aborted && !this.isConnected) return this.#abandon();
+      return { list, fonts };
     },
-    onComplete: (fragment) => {
-      if (fragment === null || !this.isConnected) return;
-      this.#stage.swap(fragment);
-      this.#landed = true;
-      this.#stale = false;
-      // A render that reached 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.#failure = undefined;
-      this.#dismissed = false;
-      this.dispatchEvent(new CustomEvent("rendered"));
+    onComplete: (result) => {
+      if (result === null || !this.isConnected) return;
+      // 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.#landed = true;
+        this.#stale = false;
+        // 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.#failure = undefined;
+        this.#dismissed = false;
+        // After the paint, so the update the task queued has already run.
+        this.requestUpdate();
+        this.dispatchEvent(new CustomEvent("rendered"));
+      });
     },
     onError: (error) => {
       if (!this.isConnected) return;
@@ -161,6 +177,8 @@ export class QuarioViewer extends LitElement {
     this.zoom = undefined;
     /** @type {ViewerPage | undefined} */
     this.page = undefined;
+    /** @type {ViewerFonts | undefined} */
+    this.fonts = undefined;
     /** @type {string | undefined} */
     this.filename = undefined;
     /** @type {"light" | "dark" | "auto" | undefined} */
@@ -168,7 +186,7 @@ export class QuarioViewer extends LitElement {
   }
 
   /**
-   * The newest render settling: `true` when it reached the sheet, `false`
+   * The newest render settling: `true` when it landed on the sheet, `false`
    * when it failed or there was nothing to render. 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.
@@ -180,7 +198,7 @@ export class QuarioViewer extends LitElement {
       this.#task.status === TaskStatus.INITIAL
         ? this.#landed
         : this.#task.taskComplete.then(
-            () => this.#landed,
+            () => this.#painting.then(() => this.#landed),
             () => false,
           ),
     );
@@ -220,7 +238,7 @@ export class QuarioViewer extends LitElement {
           })}
         </div>
         <div class="qv-body">
-          ${this.#panel()}
+          ${this.#failure && !this.#dismissed ? panel(this.#failure, () => this.#dismiss()) : ""}
           ${this.#stage.element}
         </div>
       </div>
@@ -241,7 +259,9 @@ export class QuarioViewer extends LitElement {
     super.connectedCallback();
     // A fitted sheet follows the host's box; the observer is released on
     // disconnect, so reconnection takes it again.
-    this.#watchStage();
+    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
@@ -273,14 +293,10 @@ export class QuarioViewer extends LitElement {
     if (this.#invalid) throw this.#invalid;
     if (vacant(report, targets)) return null;
     if (!this.isConnected) return this.#abandon();
+    exports(report, targets);
     return true;
   }
 
-  /** @param {AbortSignal} signal */
-  #drop(signal) {
-    return signal.aborted && !this.isConnected;
-  }
-
   #abandon() {
     this.#stale = true;
     return null;
@@ -342,18 +358,6 @@ export class QuarioViewer extends LitElement {
     if (said(was) !== said(this.#invalid)) this.#epoch++;
   }
 
-  #panel() {
-    return this.#failure && !this.#dismissed ? panel(this.#failure, () => this.#dismiss()) : "";
-  }
-
-  #onResize() {
-    if (this.#mode === "fit" && this.#wanted() !== this.#stage.percent()) this.#apply();
-  }
-
-  #watchStage() {
-    this.#unwatch ??= this.#stage.watch(() => this.#onResize());
-  }
-
   #wake() {
     if (this.#stale || this.#task.status === TaskStatus.PENDING) {
       this.#epoch++;
@@ -423,12 +427,13 @@ export class QuarioViewer extends LitElement {
    * @param {any} target
    */
   async #export(target) {
-    let { type, label: format } = EXPORTS[target.name];
+    let type = EXPORTS[target.name];
+    let format = target.name.toUpperCase();
     this.#exporting.add(target.name);
     this.requestUpdate();
     try {
       let body = await /** @type {any} */ (this.report).render(target, this.data);
-      this.#ifConnected(() => download(body, this.#name + "." + target.name, type));
+      this.#ifConnected(() => saveAs(body, this.#name + "." + target.name, type));
     } catch (error) {
       this.#ifConnected(() => this.#announce(error, "export", format));
     } finally {

package/lib/menu.js

@@ -1,6 +1,6 @@
 /**
- * The zoom menu: the magnifier trigger in the bar and the popover it opens —
- * "Fit sheet" above a separator, then the percentages `zoom.js` offers. It is
+ * The zoom menu: the search trigger in the bar and the popover it opens —
+ * "Fit page" above a separator, then the percentages `zoom.js` offers. It is
  * the whole zoom control; the live percentage is never drawn, it is what the
  * trigger is named after ("Zoom, 62%"), so the bar carries one icon rather
  * than a readout that changes width under the reader.
@@ -20,7 +20,7 @@
  * Radio semantics, not toggles: exactly one row is the current mode, and
  * choosing the one already checked settles as a no-op in the element's own
  * `#setMode`, so this module reports every row alike. The check follows
- * the mode rather than the measurement — "Fit sheet" is checked whenever the
+ * the mode rather than the measurement — "Fit page" is checked whenever the
  * viewer is fitting, whatever percentage that came out at, and a host-set
  * percentage the menu does not offer checks nothing.
  *
@@ -29,6 +29,7 @@
  */
 import { css, html } from "lit";
 import { button } from "./button.js";
+import { check, search } from "./icons.js";
 import { STEPS } from "./zoom.js";
 
 /** The popover's id, scoped to the shadow root, so two viewers never collide. */
@@ -85,12 +86,22 @@ export let MENU = css`
   }
 
   /* The check's slot is held whether or not a check is in it, so the labels
-   line up down the menu. */
+   line up down the menu. 14px rather than 13: the small icon size serves this
+   slot and the editor's gutter alike, which is one size fewer than buying a
+   third for one glyph (ADR 0044). */
   .qv-tick {
     display: inline-flex;
     flex: none;
-    width: 13px;
-    height: 13px;
+    width: 14px;
+    height: 14px;
+  }
+
+  /* Narrower than the chrome's 18px base on specificity, not on where this
+   sheet sits in \`static styles\` — reordering that array must not silently
+   put the tick back to 18px. */
+  .qv-viewer .qv-tick svg {
+    width: 14px;
+    height: 14px;
   }
 
   .qv-separator {
@@ -100,30 +111,6 @@ export let MENU = css`
   }
 `;
 
-/** @type {import('lit').TemplateResult} */
-let magnifier = html`
-  <svg viewBox="0 0 20 20" width="19" height="19" aria-hidden="true">
-    <g fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round">
-      <circle cx="8.75" cy="8.75" r="5.25"></circle>
-      <path d="M12.6 12.6 16.4 16.4"></path>
-    </g>
-  </svg>
-`;
-
-/** @type {import('lit').TemplateResult} */
-let tick = html`
-  <svg viewBox="0 0 16 16" width="13" height="13" aria-hidden="true">
-    <path
-      d="M3.4 8.4 6.4 11.4 12.6 4.8"
-      fill="none"
-      stroke="currentColor"
-      stroke-width="1.9"
-      stroke-linecap="round"
-      stroke-linejoin="round"
-    ></path>
-  </svg>
-`;
-
 /**
  * The button that opens this menu, found by the invoker relationship itself
  * rather than by where it sits: a wrapper added for layout, or a second
@@ -276,7 +263,7 @@ let row = (label, value, checked, choose) => html`
     data-zoom=${String(value)}
     @click=${pick(value, choose)}
   >
-    <span class="qv-tick">${checked ? tick : ""}</span>
+    <span class="qv-tick">${checked ? check : ""}</span>
     ${label}
   </button>
 `;
@@ -298,7 +285,7 @@ export let zoomMenu = ({ mode, percent, choose }) => html`
     ${button({
       title: "Zoom, " + percent + "%",
       popover: ID,
-      content: magnifier,
+      content: search,
     })}
     <div
       id=${ID}
@@ -310,7 +297,7 @@ export let zoomMenu = ({ mode, percent, choose }) => html`
       @beforetoggle=${leaving}
       @keydown=${navigate}
     >
-      ${row("Fit sheet", "fit", mode === "fit", choose)}
+      ${row("Fit page", "fit", mode === "fit", choose)}
       <hr class="qv-separator" role="separator" />
       ${STEPS.map((step) => row(step + "%", step, mode === step, choose))}
     </div>

package/lib/panel.js

@@ -19,6 +19,7 @@
  */
 import { css, html } from "lit";
 import { button } from "./button.js";
+import { x } from "./icons.js";
 
 export let PANEL = css`
   /* Positioned rather than laid out, for the reason the progress strip is: a
@@ -121,6 +122,6 @@ export let panel = (failure, dismiss) => html`
       <p class="qv-error-label">${failure.label}</p>
       <p class="qv-error-message">${wording(failure.error)}</p>
     </div>
-    ${button({ title: "Dismiss", label: "×", click: dismiss })}
+    ${button({ title: "Dismiss", content: x, click: dismiss })}
   </div>
 `;