@quario/viewer 0.1.0

package/lib/menu.js

@@ -0,0 +1,318 @@
+/**
+ * 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 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.
+ *
+ * Native Popover API, so the top layer and light dismiss are the platform's:
+ * the menu escapes the bar without any ancestor having to allow it, and
+ * Escape or a click outside closes it. Three things the platform leaves to
+ * the author, each handled once here rather than per dismissal: placing the
+ * popover against its invoker (`place()` — anchor positioning would decide it
+ * in CSS, but not yet everywhere the viewer embeds); dismissing it when the
+ * viewport moves under it (`follow()` — a top-layer element does not travel
+ * with the invoker it was placed against, and a menu hanging off nothing is
+ * worse than one that closed); and handing focus back off a row that is about
+ * to stop being displayed (`leaving()`, on `beforetoggle`, the last moment
+ * that row is still focusable).
+ *
+ * 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
+ * viewer is fitting, whatever percentage that came out at, and a host-set
+ * percentage the menu does not offer checks nothing.
+ *
+ * Labels go in as template values, never as markup, so this module has no
+ * markup edge to escape at (hard constraint 4).
+ */
+import { css, html } from "lit";
+import { button } from "./button.js";
+import { STEPS } from "./zoom.js";
+
+/** The popover's id, scoped to the shadow root, so two viewers never collide. */
+let ID = "qv-zoom-menu";
+
+/** The gap between the trigger and the menu it opens, in px. */
+let OFFSET = 6;
+
+export let MENU = css`
+  /* Top-layer, so it is placed against the viewport: the UA's centring inset
+   is cleared here and \`place()\` writes the corner. Clearing it is also what
+   keeps the opening honest — \`place()\` runs from the queued toggle task, and
+   until it does, a fixed box with auto insets sits at its static position,
+   which is exactly where this element stands in the bar. \`display\` is
+   deliberately left alone: an author \`display\` would beat the UA rule that
+   hides a closed popover. */
+  .qv-menu {
+    position: fixed;
+    inset: auto;
+    margin: 0;
+    padding: 4px;
+    min-width: 150px;
+    border: 1px solid var(--_border);
+    border-radius: 8px;
+    background: var(--_bar);
+    box-shadow: 0 6px 20px light-dark(rgba(0, 0, 0, 0.14), rgba(0, 0, 0, 0.5));
+  }
+
+  .qv-menuitem {
+    display: flex;
+    align-items: center;
+    gap: 7px;
+    width: 100%;
+    padding: 5px 12px 5px 6px;
+    border: none;
+    border-radius: 5px;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-variant-numeric: tabular-nums;
+    text-align: left;
+    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);
+    outline-offset: -2px;
+  }
+
+  /* The check's slot is held whether or not a check is in it, so the labels
+   line up down the menu. */
+  .qv-tick {
+    display: inline-flex;
+    flex: none;
+    width: 13px;
+    height: 13px;
+  }
+
+  .qv-separator {
+    margin: 4px 2px;
+    border: none;
+    border-top: 1px solid var(--_border);
+  }
+`;
+
+/** @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
+ * control in the group, must not be able to repoint placement or the focus
+ * hand-back.
+ *
+ * @type {(menu: Element) => HTMLElement}
+ */
+let trigger = (menu) =>
+  /** @type {any} */ (menu.getRootNode()).querySelector('[popovertarget="' + ID + '"]');
+
+/** What has focus in the viewer's shadow root — not necessarily in the menu. */
+/** @type {(menu: Element) => Element | null} */
+let focused = (menu) => /** @type {ShadowRoot} */ (menu.getRootNode()).activeElement;
+
+/** @type {(menu: Element) => HTMLElement[]} */
+let items = (menu) => /** @type {HTMLElement[]} */ ([...menu.querySelectorAll(".qv-menuitem")]);
+
+/**
+ * Place the open menu under its trigger, or over it when there is no room
+ * below — the viewer is embedded, and a host is free to put its bar near the
+ * bottom of the window.
+ *
+ * @param {HTMLElement} menu
+ */
+let place = (menu) => {
+  let box = trigger(menu).getBoundingClientRect();
+  let below = box.bottom + OFFSET + menu.offsetHeight <= innerHeight;
+  menu.style.left = box.left + "px";
+  menu.style.top = (below ? box.bottom + OFFSET : box.top - OFFSET - menu.offsetHeight) + "px";
+};
+
+/**
+ * Where each key sends focus, from the row that has it.
+ *
+ * @type {Record<string, (list: HTMLElement[], at: number) => HTMLElement>}
+ */
+let MOVE = {
+  ArrowDown: (list, at) => list[(at + 1) % list.length],
+  ArrowUp: (list, at) => list[(at - 1 + list.length) % list.length],
+  Home: (list) => list[0],
+  End: (list) => list[list.length - 1],
+};
+
+/**
+ * Tab is the one key that closes rather than moves: a menu left open behind
+ * the focus ring is the state light dismiss does not cover, and closing it
+ * is what puts focus back on the trigger to carry on from.
+ *
+ * @param {KeyboardEvent} event
+ */
+let navigate = (event) => {
+  let menu = /** @type {HTMLElement} */ (event.currentTarget);
+  let move = MOVE[event.key];
+  if (!move && event.key !== "Tab") return;
+  event.preventDefault();
+  if (!move) return menu.hidePopover();
+  let list = items(menu);
+  move(list, list.indexOf(/** @type {any} */ (focused(menu)))).focus();
+};
+
+/**
+ * What is watching the viewport for each open menu, so closing can stop it.
+ * Keyed weakly on the menu, which is the element the listeners close.
+ *
+ * @type {WeakMap<Element, AbortController>}
+ */
+let watching = new WeakMap();
+
+/**
+ * Placement is written once, at opening, against the trigger's viewport box —
+ * so anything that moves that box while the menu is open leaves it pointing
+ * at nothing. Scrolling (in capture, so a scroll anywhere counts) and
+ * resizing dismiss it instead of dragging it along: the reader has already
+ * looked away from the control.
+ *
+ * @param {HTMLElement} menu
+ */
+let follow = (menu) => {
+  let stop = new AbortController();
+  // Guarded and `once`, not merely aborted on close: removing an open popover
+  // from the document hides it without firing `beforetoggle`, so a discarded
+  // viewer never reaches `leaving()`. `once` is what stops these listeners —
+  // and the menu they hold — outliving the first scroll or resize after that.
+  let close = () => menu.matches(":popover-open") && menu.hidePopover();
+  let once = { capture: true, once: true, signal: stop.signal };
+  addEventListener("scroll", close, once);
+  addEventListener("resize", close, once);
+  watching.set(menu, stop);
+};
+
+/**
+ * Opening puts focus on the row that is checked, so the arrow keys move from
+ * where the reader already is. Nothing is checked at an off-list percentage;
+ * then the first row takes it.
+ *
+ * @param {ToggleEvent} event
+ */
+let opened = (event) => {
+  if (event.newState !== "open") return;
+  let menu = /** @type {HTMLElement} */ (event.currentTarget);
+  place(menu);
+  follow(menu);
+  (/** @type {HTMLElement | null} */
+  (menu.querySelector('[aria-checked="true"]')) ?? items(menu)[0]).focus();
+};
+
+/**
+ * Whatever dismissed the menu — Escape, Tab, a chosen row — focus must not be
+ * left on a row that is about to stop being displayed. `beforetoggle` is
+ * where this belongs: by the time `toggle` runs the rows are gone and the
+ * browser has already put focus back on the document.
+ *
+ * @param {ToggleEvent} event
+ */
+let leaving = (event) => {
+  let menu = /** @type {HTMLElement} */ (event.currentTarget);
+  if (event.newState !== "closed") return;
+  watching.get(menu)?.abort();
+  if (menu.contains(focused(menu))) trigger(menu).focus();
+};
+
+/**
+ * Choosing a row closes the menu and reports the row. Whether that is a
+ * change is the element's to know, not this module's: `#setMode` is where the
+ * mode lives, and re-choosing the one already current settles there.
+ *
+ * @type {(value: "fit" | number, choose: (value: "fit" | number) => void)
+ *   => (event: Event) => void}
+ */
+let pick = (value, choose) => (event) => {
+  let target = /** @type {HTMLElement} */ (event.currentTarget);
+  /** @type {HTMLElement} */ (target.closest("[popover]")).hidePopover();
+  choose(value);
+};
+
+/**
+ * One menu row.
+ *
+ * @type {(label: string, value: "fit" | number, checked: boolean,
+ *   choose: (value: "fit" | number) => void) => import('lit').TemplateResult}
+ */
+let row = (label, value, checked, choose) => html`
+  <button
+    type="button"
+    class="qv-menuitem"
+    role="menuitemradio"
+    aria-checked=${String(checked)}
+    tabindex="-1"
+    data-zoom=${String(value)}
+    @click=${pick(value, choose)}
+  >
+    <span class="qv-tick">${checked ? tick : ""}</span>
+    ${label}
+  </button>
+`;
+
+/**
+ * The zoom group: the trigger and its menu. The trigger's name carries the
+ * percentage on screen, because that is the one control whose state a reader
+ * would otherwise have to open the menu to learn — and at an off-list fit
+ * percentage the menu could not tell them anyway.
+ *
+ * @param {{ mode: "fit" | number, percent: number,
+ *   choose: (value: "fit" | number) => void }} zoom
+ *   The live mode, the percentage actually on screen, and the element's own
+ *   handler for a chosen row.
+ * @returns {import('lit').TemplateResult}
+ */
+export let zoomMenu = ({ mode, percent, choose }) => html`
+  <div class="qv-zoom">
+    ${button({
+      title: "Zoom, " + percent + "%",
+      popover: ID,
+      content: magnifier,
+    })}
+    <div
+      id=${ID}
+      popover
+      class="qv-menu"
+      role="menu"
+      aria-label="Zoom"
+      @toggle=${opened}
+      @beforetoggle=${leaving}
+      @keydown=${navigate}
+    >
+      ${row("Fit sheet", "fit", mode === "fit", choose)}
+      <hr class="qv-separator" role="separator" />
+      ${STEPS.map((step) => row(step + "%", step, mode === step, choose))}
+    </div>
+  </div>
+`;

package/lib/panel.js

@@ -0,0 +1,126 @@
+/**
+ * The error panel: what a failed render or export looks like to the reader,
+ * rather than only to whoever is listening for the event. One panel serves
+ * every kind of failure, so the label is what tells them apart.
+ *
+ * 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.
+ *
+ * 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
+ * whatever it throws (hard constraint 4).
+ */
+import { css, html } from "lit";
+import { button } from "./button.js";
+
+export let PANEL = css`
+  /* Positioned rather than laid out, for the reason the progress strip is: a
+   panel that took layout would push the stage down and shorten it, so raising
+   and clearing it would rescale a fitted sheet every time an export failed.
+   Over the top of the stage, above the marking watermark's z-index. */
+  .qv-error {
+    position: absolute;
+    inset: 0 0 auto 0;
+    z-index: 2;
+    display: flex;
+    align-items: flex-start;
+    gap: 6px;
+    max-height: 45%;
+    padding: 9px 8px 11px 12px;
+    background: var(--_error);
+    color: var(--_error-text);
+    border-bottom: 1px solid var(--_error-border);
+  }
+
+  /* The wording scrolls; the dismiss control does not go with it. */
+  .qv-error-body {
+    flex: 1;
+    min-width: 0;
+    overflow: auto;
+  }
+
+  .qv-error-label {
+    margin: 0;
+    font-weight: 600;
+  }
+
+  /* The error's own words, which for a located diagnostic carry the schema path
+   and the offending source. It wraps rather than truncates: the path is the
+   most useful part and it is at the front, but the message is what says why. */
+  .qv-error-message {
+    margin: 3px 0 0;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+
+  /* The shared button is styled for the bar, where it sits on the chrome's own
+   palette. In here it takes the panel's. */
+  .qv-error .qv-button {
+    flex: none;
+    color: inherit;
+  }
+
+  .qv-error .qv-button:hover {
+    background: var(--_error-hover);
+    color: inherit;
+  }
+`;
+
+/**
+ * Which failure this was, in the panel's own wording. The update label earns
+ * its length: that failure leaves the previous report on the sheet, and
+ * silently stale content is the thing the panel exists to prevent.
+ *
+ * @param {"mount-render" | "update-render" | "export"} kind
+ * @param {string} [format] The export format's name, for that kind alone.
+ * @returns {string}
+ */
+export let label = (kind, format) =>
+  kind === "export"
+    ? "Could not export " + format
+    : kind === "update-render"
+      ? "Could not update the report — showing the previous version"
+      : "Could not render the report";
+
+/**
+ * What an error says. Not every throw is an `Error` — a host's registry
+ * function may throw anything, which `locate()` in the engine allows for too —
+ * so the value itself answers when there is no message to read, and an `Error`
+ * with an empty one falls through to its own `toString`.
+ *
+ * @param {unknown} error The caught value.
+ * @returns {string}
+ */
+let wording = (error) => String(/** @type {any} */ (error)?.message || error);
+
+/**
+ * The error panel, rendered only while there is a failure worth looking at:
+ * it is a state, not a log — the error event is the log, and it takes every
+ * failure whether or not one is drawn. Assertive rather than polite: a
+ * failure means the reader is looking at stale or empty content, which is
+ * worth interrupting for. What keeps the announcement rate down is that the
+ * panel replaces rather than stacks, and that a superseded render's failure
+ * is never drawn.
+ *
+ * @param {{ label: string, error: unknown }} failure The viewer's own label
+ *   and the caught value, printed as text and never markup.
+ * @param {() => void} dismiss Takes the panel down until the next failure.
+ * @returns {import('lit').TemplateResult}
+ */
+export let panel = (failure, dismiss) => html`
+  <div class="qv-error" role="alert">
+    <div class="qv-error-body">
+      <p class="qv-error-label">${failure.label}</p>
+      <p class="qv-error-message">${wording(failure.error)}</p>
+    </div>
+    ${button({ title: "Dismiss", label: "×", click: dismiss })}
+  </div>
+`;

package/lib/register.d.ts

@@ -0,0 +1,9 @@
+import { QuarioViewer } from "./index.js";
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "quario-viewer": QuarioViewer;
+  }
+}
+
+export {};

package/lib/register.js

@@ -0,0 +1,10 @@
+/**
+ * The one-line define, as its own entry so the main module stays
+ * side-effect-free: importing `@quario/viewer` gives you the class and
+ * defines nothing, importing `@quario/viewer/register` gives the tag to
+ * hosts that want the platform default. A host that wants its own tag calls
+ * `customElements.define` itself (docs/adr/0005-the-surfaces-are-custom-elements.md).
+ */
+import { QuarioViewer, TAG } from "./index.js";
+
+customElements.define(TAG, QuarioViewer);