@quario/viewer 0.1.0

package/lib/index.js

@@ -0,0 +1,450 @@
+/**
+ * @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.
+ *
+ * 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.
+ *
+ * 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).
+ */
+import { Task, TaskStatus } from "@lit/task";
+import { LitElement, html } from "lit";
+import { BUTTON } from "./button.js";
+import { CHROME, progress } from "./chrome.js";
+import { display, 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 { wanted } from "./zoom.js";
+
+let OPTION = ["page", "zoom", "filename", "colorScheme"];
+let SUBJECT = ["data", "report"];
+
+/** @type {(el: LitElement, changed: Map<string, unknown>) => boolean} */
+let optionWrite = (el, changed) => !el.hasUpdated || OPTION.some((key) => changed.has(key));
+
+/** @type {(changed: Map<string, unknown>) => boolean} */
+let subjectWrite = (changed) => SUBJECT.some((key) => changed.has(key));
+
+/** @type {(report: unknown, targets: unknown) => boolean} */
+let vacant = (report, targets) => report === undefined && targets === undefined;
+
+/** @type {(error: unknown) => unknown} */
+let said = (error) => {
+  // oxlint-disable-next-line typescript/no-base-to-string
+  return error && String(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' */
+
+/** 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).
+ *
+ * Removal is not destruction: disconnecting abandons in-flight work and
+ * releases the resize observer, the properties persist, and reconnecting
+ * re-renders from them. 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, REPORT];
+
+  // Properties only, no attributes: `report`, `targets`, `data` and `page`
+  // are values no attribute could carry, and one door beats two.
+  static properties = {
+    report: { attribute: false },
+    targets: { attribute: false },
+    data: { attribute: false },
+    zoom: { attribute: false },
+    page: { attribute: false },
+    filename: { attribute: false },
+    colorScheme: { attribute: false },
+  };
+
+  // The stage is built once and never rebuilt: it is the one imperative thing
+  // the element owns, and the sheet's content has to survive an update that
+  // 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. */
+  #landed = false;
+  /** Whether the sheet stopped matching the properties while disconnected. */
+  #stale = false;
+  /** @type {"fit" | number} The live zoom mode; the controls move it. */
+  #mode = "fit";
+  /** @type {{ width: number, height: number, margin: number }} */
+  #box = geometry(undefined);
+  #name = "report";
+  /** A property the host got wrong, rethrown by the task so it reports once. */
+  /** @type {unknown} */
+  #invalid;
+  /** Bumped to re-run the task when its real arguments did not change. */
+  #epoch = 0;
+  /** @type {{ label: string, error: unknown } | undefined} */
+  #failure;
+  #dismissed = false;
+  /** Re-applies geometry and scale after the update that changed them. */
+  #reapply = false;
+  /** @type {Set<string>} The exports in flight; their buttons disable. */
+  #exporting = new Set();
+  /** @type {(() => void) | undefined} */
+  #unwatch;
+
+  // 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
+  // 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 }) => {
+      if (!this.#begin(report, targets)) return null;
+      let target = display(report, targets);
+      let fragment = 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;
+    },
+    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"));
+    },
+    onError: (error) => {
+      if (!this.isConnected) return;
+      this.#announce(error, this.#landed ? "update-render" : "mount-render");
+    },
+  });
+
+  constructor() {
+    super();
+    // Constructor assignment, never class fields: the source ships verbatim,
+    // so a declared field would shadow the accessor `static properties`
+    // installs and reactivity would go quiet.
+    /** @type {ViewableReport | undefined} */
+    this.report = undefined;
+    /** @type {readonly any[] | undefined} */
+    this.targets = undefined;
+    /** @type {unknown} */
+    this.data = undefined;
+    /** @type {"fit" | number | undefined} */
+    this.zoom = undefined;
+    /** @type {ViewerPage | undefined} */
+    this.page = undefined;
+    /** @type {string | undefined} */
+    this.filename = undefined;
+    /** @type {"light" | "dark" | "auto" | undefined} */
+    this.colorScheme = undefined;
+  }
+
+  /**
+   * The newest render settling: `true` when it reached 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.
+   *
+   * @returns {Promise<boolean>}
+   */
+  get renderComplete() {
+    return this.updateComplete.then(() =>
+      this.#task.status === TaskStatus.INITIAL
+        ? this.#landed
+        : this.#task.taskComplete.then(
+            () => this.#landed,
+            () => false,
+          ),
+    );
+  }
+
+  /** @param {Map<string, unknown>} changed */
+  willUpdate(changed) {
+    // The option properties are derived here, not in the task: a zoom change
+    // must not re-render the report. A property the host got wrong keeps the
+    // last good values and is stashed for the task, whose next run reports it
+    // through the one failure channel; flipping validity re-runs the task by
+    // epoch, because the render arguments themselves did not change.
+    if (optionWrite(this, changed)) this.#checkOptions(changed);
+    // A new document is a new subject: dismissing the last failure said
+    // nothing about this one.
+    if (subjectWrite(changed)) this.#dismissed = false;
+  }
+
+  render() {
+    let busy = this.#task.status === TaskStatus.PENDING;
+    return html`
+      <div class="qv-viewer" aria-busy=${String(busy)}>
+        <div class="qv-bar">
+          ${progress(busy)}
+          ${zoomMenu({
+            mode: this.#mode,
+            percent: Math.round(this.#stage.percent()),
+            choose: (next) => this.#setMode(next),
+          })}
+          ${exportGroup(this.targets, {
+            busy: this.#exporting,
+            click: (target) => this.#export(target),
+          })}
+        </div>
+        <div class="qv-body">
+          ${this.#panel()}
+          ${this.#stage.element}
+        </div>
+      </div>
+    `;
+  }
+
+  updated() {
+    // Layout writes belong here, never in render(): applying a scale measures
+    // the box, and the stage is only measurable once the update committed it.
+    if (this.#reapply) {
+      this.#reapply = false;
+      this.#stage.resize(this.#box);
+      this.#apply();
+    }
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    // A fitted sheet follows the host's box; the observer is released on
+    // disconnect, so reconnection takes it again.
+    this.#watchStage();
+    // 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
+    // change, so the epoch is what re-runs it; left alone, reparenting a
+    // settled viewer costs nothing.
+    this.#wake();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    // Abandon in-flight work and release the observer. The properties and the
+    // sheet persist: removal is destruction only in the collector's sense.
+    this.#task.abort();
+    this.#unwatch?.();
+    this.#unwatch = undefined;
+  }
+
+  /**
+   * 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.
+   *
+   * @param {unknown} report
+   * @param {unknown} targets
+   */
+  #begin(report, targets) {
+    if (this.#invalid) throw this.#invalid;
+    if (vacant(report, targets)) return null;
+    if (!this.isConnected) return this.#abandon();
+    return true;
+  }
+
+  /** @param {AbortSignal} signal */
+  #drop(signal) {
+    return signal.aborted && !this.isConnected;
+  }
+
+  #abandon() {
+    this.#stale = true;
+    return null;
+  }
+
+  /** @param {() => void} run */
+  #take(run) {
+    try {
+      run();
+    } catch (error) {
+      this.#invalid ??= error;
+    }
+  }
+
+  /** @param {Map<string, unknown>} changed */
+  #commitPage(changed) {
+    let box = geometry(this.page);
+    if (!this.hasUpdated || changed.has("page")) {
+      this.#box = box;
+      this.#reapply = true;
+    }
+  }
+
+  /** @param {Map<string, unknown>} changed */
+  #commitZoom(changed) {
+    let mode = level(this.zoom);
+    // Committed only when the host wrote `zoom`, so re-validating on a
+    // filename change cannot clobber the mode the reader clicked to.
+    if (!this.hasUpdated || changed.has("zoom")) {
+      this.#mode = mode;
+      this.#reapply = true;
+    }
+  }
+
+  /**
+   * Each property validates and commits on its own, stashing the first
+   * failure: one bad property must not block a good write to another. All
+   * four re-validate whatever changed, so a still-broken property keeps the
+   * element failing loudly rather than being cleared by an unrelated write.
+   *
+   * Compared by wording rather than identity: each check mints a fresh
+   * TypeError, and the same still-broken property re-reported on every
+   * unrelated write would be churn, while a genuinely different failure (or
+   * recovery) is a render outcome and re-runs the task. Stringifying whatever
+   * was thrown is the comparison — its wording is the identity here, and a
+   * value with no better one still compares equal.
+   *
+   * @param {Map<string, unknown>} changed
+   */
+  #checkOptions(changed) {
+    let was = this.#invalid;
+    this.#invalid = undefined;
+    this.#take(() => this.#commitPage(changed));
+    this.#take(() => this.#commitZoom(changed));
+    this.#take(() => {
+      this.#name = name(this.filename);
+    });
+    this.#take(() => {
+      let used = scheme(this.colorScheme);
+      // Same gate as zoom/page: re-validate always, write the CSSOM pin only
+      // when this property changed, so a filename write does not dirty
+      // inherited color-scheme before layout.
+      if (!this.hasUpdated || changed.has("colorScheme")) this.style.colorScheme = used;
+    });
+    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++;
+      this.requestUpdate();
+    }
+  }
+
+  /** @param {() => void} run */
+  #ifConnected(run) {
+    if (this.isConnected) run();
+  }
+
+  /** The percentage the zoom policy asks for right now. */
+  #wanted() {
+    return wanted(this.#mode, this.#stage.fit(), this.#stage.percent());
+  }
+
+  /**
+   * Write the asked-for scale to the stage — the one imperative side effect
+   * the declarative render cannot own — then re-render so the trigger's name
+   * re-derives from what is actually on screen.
+   */
+  #apply() {
+    this.#stage.scale(this.#wanted());
+    this.requestUpdate();
+  }
+
+  /**
+   * Move the zoom. Settling on the mode already current is not a change — the
+   * menu's rows are radios, and re-choosing the checked one only closes the
+   * menu — so it costs no measurement and no re-render.
+   *
+   * @param {"fit" | number} next
+   */
+  #setMode(next) {
+    if (next === this.#mode) return;
+    this.#mode = next;
+    this.#apply();
+  }
+
+  #dismiss() {
+    this.#dismissed = true;
+    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,
+   * or anything after a disconnect — never come through here.
+   *
+   * @param {unknown} error The caught value.
+   * @param {"mount-render" | "update-render" | "export"} kind
+   * @param {string} [format] The export format's name, for that kind alone.
+   */
+  #announce(error, kind, format) {
+    this.#failure = { error, label: label(kind, format) };
+    this.#dismissed = false;
+    this.requestUpdate();
+    this.dispatchEvent(new CustomEvent("error", { detail: { error, kind } }));
+  }
+
+  /**
+   * Render and download one export. The render is paid for wherever it
+   * settles; the download and the failure report are dropped once the element
+   * is disconnected — a discarded viewer never hands the reader a file.
+   *
+   * @param {any} target
+   */
+  async #export(target) {
+    let { type, label: format } = EXPORTS[target.name];
+    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));
+    } catch (error) {
+      this.#ifConnected(() => this.#announce(error, "export", format));
+    } finally {
+      this.#exporting.delete(target.name);
+      this.requestUpdate();
+    }
+  }
+}

package/lib/mark.js

@@ -0,0 +1,40 @@
+/**
+ * Unlicensed watermark layout for the continuous sheet: stamp centres along
+ * the sheet height, and PDF-like face geometry from the full page box (same
+ * atan2 / 75%-diagonal / size-at-54pt proportions as the PDF stamp). Pure
+ * numbers — the stage owns the DOM. Appearance is best-effort (ADR 0017).
+ */
+
+/** Reference face size in points — matches the PDF target's stamp probe. */
+export let FACE = 54;
+
+/**
+ * Centre Y of each stamp band covering `[0, sheetHeight)`. Bands are
+ * `pageHeight` tall; the last may be short. A short sheet still gets one stamp.
+ *
+ * @param {number} sheetHeight
+ * @param {number} pageHeight
+ * @returns {number[]}
+ */
+export let centres = (sheetHeight, pageHeight) => {
+  if (!(sheetHeight > 0) || !(pageHeight > 0)) return [];
+  let n = Math.max(1, Math.ceil(sheetHeight / pageHeight));
+  /** @type {number[]} */
+  let out = [];
+  for (let i = 0; i < n; i++) {
+    let top = i * pageHeight;
+    let bottom = Math.min((i + 1) * pageHeight, sheetHeight);
+    out.push((top + bottom) / 2);
+  }
+  return out;
+};
+
+/** @type {(width: number, height: number) => number} */
+export let angle = (width, height) => (Math.atan2(height, width) * 180) / Math.PI;
+
+/** @type {(width: number, height: number) => number} */
+export let span = (width, height) => Math.hypot(width, height) * 0.75;
+
+/** @type {(spanLength: number, textWidth: number, at?: number) => number} */
+export let size = (spanLength, textWidth, at = FACE) =>
+  textWidth > 0 ? (at * spanLength) / textWidth : at;