@quario/viewer 0.1.0

package/lib/check.js

@@ -0,0 +1,154 @@
+/**
+ * What the host got wrong, named. The element's own mistakes — a report that
+ * is not compiled, a missing html target, a malformed option property — are
+ * definition-shaped: they describe the embedding, not the report, so each
+ * check here throws a `TypeError` naming the property and the expectation.
+ * The element rethrows them from its render task, which is how one channel
+ * (the error event and the panel) carries every failure a host can cause.
+ *
+ * Pure policy, no DOM: this module is what the Node suite pins.
+ */
+
+import { STEPS } from "./zoom.js";
+
+/** @type {(message: string) => never} */
+let fail = (message) => {
+  throw new TypeError("quario-viewer: " + message);
+};
+
+// The PdfPage vocabulary and defaults, mirrored from the pdf target: the
+// sheet is a visual stand-in for the page the host configured there, so the
+// same values must mean the same geometry.
+/** @type {Record<string, [number, number]>} */
+let SIZES = { A4: [595.28, 841.89], letter: [612, 792] };
+
+let REPORT = [
+  (/** @type {any} */ report) => report && typeof report === "object",
+  (/** @type {any} */ report) => typeof report.stream === "function",
+  (/** @type {any} */ report) => typeof report.render === "function",
+];
+
+/** @type {(report: any) => boolean} */
+let compiled = (report) => REPORT.every((check) => check(report));
+
+/** @type {(target: any) => boolean} */
+let htmlTarget = (target) => target?.name === "html";
+
+/**
+ * The target the sheet displays: the one named `"html"`, checked along with
+ * the shapes around it.
+ *
+ * @param {any} report
+ * @param {any} targets
+ * @returns {any} The html target.
+ */
+export let display = (report, targets) => {
+  if (!compiled(report)) fail("report: expected a compiled report from a quario instance");
+  if (!Array.isArray(targets)) fail("targets: expected an array of render targets");
+  let found = targets.find(htmlTarget);
+  if (!found) fail('targets: no "html" target — include html() to display');
+  return found;
+};
+
+/** @type {(size: unknown) => [number, number] | false} */
+let named = (size) =>
+  Object.hasOwn(SIZES, /** @type {string} */ (size)) && SIZES[/** @type {string} */ (size)];
+
+/** @type {(size: unknown) => any} */
+let measure = (size) => (Array.isArray(size) ? size : named(size));
+
+/** @type {(n: number) => boolean} */
+let positive = (n) => Number.isFinite(n) && n > 0;
+
+/** @type {(dimensions: any) => { width: number, height: number }} */
+let extents = (dimensions) => {
+  let width = +dimensions[0];
+  let height = +dimensions[1];
+  if (!positive(width) || !positive(height)) fail("page.size: expected finite positive dimensions");
+  return { width, height };
+};
+
+/** @type {(margin: number, width: number, height: number) => boolean} */
+let fits = (margin, width, height) =>
+  [Number.isFinite(margin), margin >= 0, 2 * margin < Math.min(width, height)].every(Boolean);
+
+/** @type {(page: any, width: number, height: number) => number} */
+let inset = (page, width, height) => {
+  let margin = page?.margin ?? 54;
+  if (!fits(margin, width, height))
+    fail("page.margin: expected a non-negative number smaller than half the page");
+  return margin;
+};
+
+/**
+ * The sheet's geometry from the `page` property. Width and margin size the
+ * sheet; height is the stamp period for the unlicensed watermark (full page
+ * box, same as the PDF target — margin does not shrink it).
+ *
+ * @param {any} page
+ * @returns {{ width: number, height: number, margin: number }}
+ */
+export let geometry = (page) => {
+  let size = page?.size ?? "A4";
+  let dimensions = measure(size);
+  if (!dimensions) fail('page.size: unknown page size "' + size + '"');
+  let { width, height } = extents(dimensions);
+  return { width, height, margin: inset(page, width, height) };
+};
+
+/** @type {(mode: any, floor: number, ceiling: number) => boolean} */
+let inRange = (mode, floor, ceiling) =>
+  [Number.isFinite(mode), mode >= floor, mode <= ceiling].every(Boolean);
+
+/**
+ * The zoom mode from the `zoom` property. Fit is the default: the host owns
+ * the box, and a report nobody can read until they touch a control is not
+ * much of a preview. A host may author any percentage from 25 to 200 —
+ * continuous, not one of the menu's own stops; fit itself computes anything
+ * at or below 100, so this deliberately validates less than the element can
+ * display.
+ *
+ * @param {any} zoom
+ * @returns {"fit" | number}
+ */
+export let level = (zoom) => {
+  let mode = zoom ?? "fit";
+  // The range is the menu's own ends, so the two cannot drift apart.
+  let [floor, ceiling] = [STEPS[0], STEPS[STEPS.length - 1]];
+  if (mode !== "fit" && !inRange(mode, floor, ceiling))
+    fail('zoom: expected "fit" or a percentage between ' + floor + " and " + ceiling);
+  return mode;
+};
+
+/** @type {(base: unknown) => boolean} */
+let nonempty = (base) => typeof base === "string" && Boolean(base);
+
+/**
+ * The export base name from the `filename` property, extensionless.
+ *
+ * @param {any} filename
+ * @returns {string}
+ */
+export let name = (filename) => {
+  let base = filename ?? "report";
+  if (!nonempty(base)) fail("filename: expected a non-empty string");
+  return base;
+};
+
+/** @type {Record<string, string>} */
+let SCHEME = { light: "light", dark: "dark", auto: "light dark" };
+
+/**
+ * The used `color-scheme` from the `colorScheme` property. Light is the
+ * default: embedding is the product, and following the OS would paint a light
+ * toolbar in a host that already chose dark. `"auto"` is the opt-in that
+ * follows, as CSS `light dark`.
+ *
+ * @param {any} colorScheme
+ * @returns {string}
+ */
+export let scheme = (colorScheme) => {
+  let pin = colorScheme ?? "light";
+  if (!Object.hasOwn(SCHEME, pin)) fail('colorScheme: expected "light", "dark", or "auto"');
+  return SCHEME[pin];
+};

package/lib/chrome.js

@@ -0,0 +1,187 @@
+/**
+ * The element's chrome: the backdrop, the bar, and the render indicator on
+ * its edge, under stable `qv-*` class names. The sheet is not here —
+ * `stage.js` keeps it paper.
+ *
+ * This module also owns the **default palette**: the `:host` block below is
+ * the one place a `--qv-*` fallback is written, and every sheet — this one
+ * included — paints from the `--_*` alias it declares. That is what makes a
+ * color one edit rather than a hunt, and `viewer.test.js` holds both halves:
+ * `--qv-` appears in no other module, and the aliases read are exactly the
+ * ones declared. The fallbacks are `light-dark()`, so a `color-scheme` pin on
+ * the host paints chrome without a class.
+ *
+ * The cost is that the other sheets no longer stand alone — they paint only
+ * where this one is adopted too. It is presence, not order: a custom property
+ * resolves down the inherited chain, so where CHROME sits in `static styles`
+ * does not matter, only that it is there.
+ *
+ * Host tokens always win, and `:host` is what makes that survive here. A
+ * `:host { --qv-border: … }` *default* would carry pseudo-class specificity
+ * and beat a host's own `quario-viewer` rule — the seam ADR 0018 declines to
+ * make a lie. A `var()` fallback applies only when the token is unset, so it
+ * loses to a host token at any specificity. The private half inverts that on
+ * purpose: `:host` outranks that same host rule, so nothing outside can
+ * shadow an alias by accident.
+ *
+ * Two of the sixteen are the sheet's rather than the chrome's: a color scheme
+ * paints chrome only (ADR 0018), so `--qv-sheet-shadow` is the sheet's edge
+ * against the backdrop and `--qv-mark` is scheme-free by design. They are in
+ * the block because it has no exceptions, not because they follow the pin.
+ * `--qv-focus` and `--qv-progress` repeat the accent rather than chain a third
+ * alias — a host is free to move one alone.
+ *
+ * What is not here is what another module owns: `stage.js` the surface a
+ * report is scaled on, `panel.js` the error panel, `button.js` the controls
+ * every group in the bar is built from. The element composes their templates
+ * and stylesheets; the imports run one way only.
+ */
+import { css, html, nothing } from "lit";
+
+export let CHROME = css`
+  /* The default palette. */
+  :host {
+    display: block;
+    color-scheme: light;
+
+    --_backdrop: var(--qv-backdrop, light-dark(#e9e9eb, #1c1c1e));
+    --_text: var(--qv-text, light-dark(#454548, #c7c7cc));
+    --_bar: var(--qv-bar, light-dark(#f8f8f9, #2c2c2e));
+    --_border: var(--qv-border, light-dark(#dededf, #3a3a3c));
+
+    --_icon: var(--qv-icon, light-dark(#58585c, #8e8e93));
+    --_icon-active: var(--qv-icon-active, light-dark(#212124, #f2f2f7));
+    --_hover: var(--qv-hover, light-dark(#ebebec, #3a3a3c));
+    --_active: var(--qv-active, light-dark(#e2e2e4, #48484a));
+    --_focus: var(--qv-focus, #4a90d9);
+
+    --_progress: var(--qv-progress, #4a90d9);
+
+    --_error: var(--qv-error, light-dark(#fdeded, #3b1c1c));
+    --_error-text: var(--qv-error-text, light-dark(#5f2120, #f5c6c6));
+    --_error-border: var(--qv-error-border, light-dark(#f1c5c5, #6b3434));
+    --_error-hover: var(--qv-error-hover, light-dark(#f7dcdc, #4a2626));
+
+    /* The sheet's, not the chrome's. */
+    --_sheet-shadow: var(
+      --qv-sheet-shadow,
+      0 1px 2px light-dark(rgba(0, 0, 0, 0.16), rgba(0, 0, 0, 0.5)),
+      0 6px 24px light-dark(rgba(0, 0, 0, 0.09), rgba(0, 0, 0, 0.45))
+    );
+    --_mark: var(--qv-mark, #999);
+  }
+
+  .qv-viewer {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    background: var(--_backdrop);
+    color: var(--_text);
+    font: 13px/1.4 system-ui, sans-serif;
+  }
+
+  /* Everything below the bar. It exists to be the box the error panel is
+   positioned against: anchored to the viewer instead, the panel would cover
+   the bar's own controls. */
+  .qv-body {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+    flex: 1;
+    min-height: 0;
+  }
+
+  .qv-bar {
+    position: relative;
+    display: flex;
+    justify-content: flex-end;
+    gap: 2px;
+    flex: none;
+    padding: 5px 10px;
+    background: var(--_bar);
+    border-bottom: 1px solid var(--_border);
+  }
+
+  /* The render indicator, lying over the bar's bottom border. It is positioned
+   rather than laid out for two reasons: nothing under it moves as renders come
+   and go, and it stays out of the width .qv-scroll reports, which the stage
+   fits against.
+   Showing is instant and hiding fades, which is the whole timing rule: a render
+   short enough for the fade to matter is one the reader never waited for. The
+   transition lives on the idle state alone, so the busy state has none to run
+   and the fade starts only on the way back. */
+  .qv-progress {
+    position: absolute;
+    inset: auto 0 -1px 0;
+    height: 2px;
+    overflow: hidden;
+    opacity: 0;
+    transition: opacity 200ms ease;
+  }
+
+  .qv-viewer[aria-busy="true"] .qv-progress {
+    opacity: 1;
+    transition: none;
+  }
+
+  /* The accent is the same in both schemes: it has to read on the light bar
+   and the dark one, and a second hue would be a second opinion. */
+  .qv-progress::after {
+    content: "";
+    display: block;
+    width: 35%;
+    height: 100%;
+    background: var(--_progress);
+    animation: qv-slide 1.1s ease-in-out infinite;
+  }
+
+  @keyframes qv-slide {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(385%);
+    }
+  }
+
+  /* Motion is the only thing the strip says; without it, say the same with a
+   filled bar rather than nothing at all. */
+  @media (prefers-reduced-motion: reduce) {
+    .qv-progress::after {
+      width: 100%;
+      opacity: 0.55;
+      animation: none;
+    }
+  }
+
+  /* The zoom group holds the left of the bar; the exports stay flush right.
+   Layout only: the menu inside it places itself against its own trigger, not
+   against this element. */
+  .qv-zoom {
+    display: flex;
+    margin-right: auto;
+  }
+
+  .qv-exports {
+    display: flex;
+    gap: 2px;
+  }
+`;
+
+/**
+ * The render indicator. Idle it stays out of the accessibility tree — an
+ * unstarted progressbar has nothing to announce — and the stylesheet above
+ * hooks on the viewer's `aria-busy` to show it.
+ *
+ * @param {boolean} busy
+ * @returns {import('lit').TemplateResult}
+ */
+export let progress = (busy) => html`
+  <div
+    class="qv-progress"
+    role="progressbar"
+    aria-label="Rendering report"
+    aria-hidden=${busy ? nothing : "true"}
+  ></div>
+`;

package/lib/index.d.ts

@@ -0,0 +1,130 @@
+import type { LitElement } from "lit";
+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.
+ */
+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;
+}
+
+/**
+ * A compiled report, from a quario instance's `report()`. The instance —
+ * and with it the license and the registry — stays the host's concern: the
+ * element takes the compiled artifact, never a schema.
+ */
+export type ViewableReport = CompiledReport;
+
+/** Which failure an `error` event names. */
+export type ViewerErrorKind = "mount-render" | "update-render" | "export";
+
+/** The `error` event's payload. */
+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
+   * be produced.
+   */
+  kind: ViewerErrorKind;
+}
+
+/**
+ * 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
+ * `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.
+ *
+ * Removing the element abandons in-flight work and releases its observers;
+ * the properties persist, and reconnecting re-renders from them. There is no
+ * `destroy()` — removal is destruction only in the garbage-collection sense,
+ * and reparenting is safe. An export settling after removal downloads
+ * nothing.
+ */
+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.
+   */
+  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
+   * 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;
+   * fit itself is unbounded below, so the viewer can display percentages
+   * this property would not accept. That asymmetry is deliberate: only fit
+   * computes them.
+   */
+  zoom: "fit" | number | undefined;
+  /** Sheet geometry. The preview approximates; exports are exact. */
+  page: ViewerPage | undefined;
+  /** Export download name, without extension. Default `'report'`. */
+  filename: string | undefined;
+  /**
+   * Chrome color scheme. `'light'` (the default) and `'dark'` pin; `'auto'`
+   * follows the OS via CSS `color-scheme`. The sheet stays white.
+   */
+  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.
+   */
+  get renderComplete(): Promise<boolean>;
+
+  addEventListener<K extends keyof QuarioViewerEventMap>(
+    type: K,
+    listener: (this: QuarioViewer, event: QuarioViewerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  removeEventListener<K extends keyof QuarioViewerEventMap>(
+    type: K,
+    listener: (this: QuarioViewer, event: QuarioViewerEventMap[K]) => void,
+    options?: boolean | EventListenerOptions,
+  ): void;
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ): void;
+}
+
+/** The element's events. Both are non-bubbling, like `<img>`'s. */
+export interface QuarioViewerEventMap {
+  /** A render reached the sheet — the mount and every update. */
+  rendered: CustomEvent<undefined>;
+  /** A failure the host should know about; `detail.kind` says which. */
+  error: CustomEvent<ViewerErrorDetail>;
+}
+
+/** The tag `@quario/viewer/register` defines the element under. */
+export const TAG: "quario-viewer";