@plotwork.official/viewer 0.0.0-stage → 0.1.0

package/dist/element/define.d.ts

@@ -0,0 +1,7 @@
+/** The element's tag. */
+export declare const TAG_NAME = "plotwork-diagram";
+/**
+ * Registers `<plotwork-diagram>` once. Safe to call many times, from several copies of the package on one page, and where there is
+ * no `customElements` (a server render), where it does nothing.
+ */
+export declare function definePlotworkDiagram(tag?: string): void;

package/dist/element/define.js

@@ -0,0 +1,12 @@
+import { createPlotworkDiagramClass } from './plotwork-diagram.js';
+/** The element's tag. */
+export const TAG_NAME = 'plotwork-diagram';
+/**
+ * Registers `<plotwork-diagram>` once. Safe to call many times, from several copies of the package on one page, and where there is
+ * no `customElements` (a server render), where it does nothing.
+ */
+export function definePlotworkDiagram(tag = TAG_NAME) {
+    if (typeof customElements === 'undefined' || customElements.get(tag) !== undefined)
+        return;
+    customElements.define(tag, createPlotworkDiagramClass());
+}

package/dist/element/dom.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Building the element's own nodes with `createElement` and `createElementNS`, never from a string of HTML, so nothing a picture or
+ * a page supplies can become markup. Attribute values are set with `setAttribute`, and text with `textContent`.
+ */
+type Attributes = Readonly<Record<string, string | number | undefined>>;
+/** An HTML element of the element's own. */
+export declare function html<K extends keyof HTMLElementTagNameMap>(tag: K, attributes?: Attributes, ...children: (Node | string)[]): HTMLElementTagNameMap[K];
+/** An SVG element of the element's own. */
+export declare function svg<K extends keyof SVGElementTagNameMap>(tag: K, attributes?: Attributes, ...children: (Node | string)[]): SVGElementTagNameMap[K];
+/** An icon: a 20 by 20 SVG of one or more paths, hidden from assistive technology because its button has a name. */
+export declare function icon(paths: readonly string[]): SVGSVGElement;
+export {};

package/dist/element/dom.js

@@ -0,0 +1,25 @@
+/**
+ * Building the element's own nodes with `createElement` and `createElementNS`, never from a string of HTML, so nothing a picture or
+ * a page supplies can become markup. Attribute values are set with `setAttribute`, and text with `textContent`.
+ */
+const SVG_NS = 'http://www.w3.org/2000/svg';
+function apply(element, attributes, children) {
+    for (const [name, value] of Object.entries(attributes))
+        if (value !== undefined)
+            element.setAttribute(name, String(value));
+    for (const child of children)
+        element.append(child);
+    return element;
+}
+/** An HTML element of the element's own. */
+export function html(tag, attributes = {}, ...children) {
+    return apply(document.createElement(tag), attributes, children);
+}
+/** An SVG element of the element's own. */
+export function svg(tag, attributes = {}, ...children) {
+    return apply(document.createElementNS(SVG_NS, tag), attributes, children);
+}
+/** An icon: a 20 by 20 SVG of one or more paths, hidden from assistive technology because its button has a name. */
+export function icon(paths) {
+    return svg('svg', { viewBox: '0 0 20 20', width: 20, height: 20, 'aria-hidden': 'true', focusable: 'false' }, ...paths.map((d) => svg('path', { d })));
+}

package/dist/element/events.d.ts

@@ -0,0 +1,39 @@
+import type { LoadFailure } from '../core/picture-loader.js';
+/**
+ * The events `<plotwork-diagram>` sends. Each is a `CustomEvent` that bubbles and crosses the shadow boundary (`composed`), so a
+ * page listens on the element or on anything that holds it.
+ */
+/** A picture is shown for the first time, or again after `src`, `svg` or `theme` changed. */
+export interface LoadDetail {
+    fingerprint: string;
+    /** True when the picture carries its source, which `source()` returns. */
+    hasSource: boolean;
+}
+/** A live picture changed on the server, and the new version is shown. */
+export interface ChangeDetail {
+    fingerprint: string;
+    previous: string;
+}
+/** The picture cannot be shown, and the notice says why. `empty` is an element with neither `src` nor `svg`. */
+export interface ErrorDetail {
+    reason: LoadFailure | 'empty';
+}
+/** A box that names a part of its series (`part=`) was pressed. The page decides what opens. */
+export interface DrillDetail {
+    id: string;
+    part: number;
+    name: string;
+}
+/** A box is traced (its id), or nothing is (null). */
+export interface TraceDetail {
+    id: string | null;
+}
+export interface PlotworkEventMap {
+    'plotwork-load': CustomEvent<LoadDetail>;
+    'plotwork-change': CustomEvent<ChangeDetail>;
+    'plotwork-error': CustomEvent<ErrorDetail>;
+    'plotwork-drill': CustomEvent<DrillDetail>;
+    'plotwork-trace': CustomEvent<TraceDetail>;
+}
+/** Sends one of the element's events from it. */
+export declare function emit<K extends keyof PlotworkEventMap>(target: EventTarget, type: K, detail: PlotworkEventMap[K]['detail']): void;

package/dist/element/events.js

@@ -0,0 +1,4 @@
+/** Sends one of the element's events from it. */
+export function emit(target, type, detail) {
+    target.dispatchEvent(new CustomEvent(type, { detail, bubbles: true, composed: true }));
+}

package/dist/element/gestures.d.ts

@@ -0,0 +1,28 @@
+import type { Point, Size, View, WheelMode } from '../core/canvas-view.js';
+/**
+ * What moves the picture: the wheel, a drag, a two-finger pinch, a double press, and the keys. Every handler reads the latest view
+ * from the controller, because a pointer reports several times a frame, and hands back a view the arithmetic already held inside
+ * the rules. A press that did not move counts as a press, so the element can trace or drill.
+ */
+/** What the gestures need from the element. */
+export interface CanvasController {
+    view(): View;
+    setView(view: View, glide?: boolean): void;
+    /** The canvas and the picture, or null before the picture has a size. */
+    sizes(): {
+        viewport: Size;
+        picture: Size;
+    } | null;
+    wheelMode(): WheelMode;
+    /** The pointer is over this canvas point, or has left (null). */
+    hover(point: Point | null): void;
+    /** A press that did not move, at this canvas point. */
+    press(point: Point): void;
+    /** A plain wheel was left to the page: tell the reader how to zoom. */
+    hintWheel(): void;
+    fit(): void;
+    /** Escape: let go of a trace. */
+    release(): void;
+}
+/** Wires the gestures to a canvas; the function it returns removes them. */
+export declare function attachGestures(canvas: HTMLElement, control: CanvasController): () => void;

package/dist/element/gestures.js

@@ -0,0 +1,142 @@
+import { middleOf, mouseWheelZoomFactor, panBy, pinchView, toggledScale, wheelIntent, wheelPixels, wheelZoomFactor, zoomAt, isMouseWheel } from '../core/canvas-view.js';
+import { PRESS_SLOP_PX, VIEWER_PAN_STEP, VIEWER_ZOOM_STEP } from '../core/limits.js';
+/** Wires the gestures to a canvas; the function it returns removes them. */
+export function attachGestures(canvas, control) {
+    const pointers = new Map();
+    let drag = null;
+    let pinch = null;
+    const local = (event) => {
+        const rect = canvas.getBoundingClientRect();
+        return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+    };
+    const pair = () => {
+        const [a, b] = [...pointers.values()];
+        if (a === undefined || b === undefined)
+            return null;
+        return { mid: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, distance: Math.hypot(a.x - b.x, a.y - b.y) };
+    };
+    const onDown = (event) => {
+        if (event.button !== 0)
+            return;
+        canvas.setPointerCapture?.(event.pointerId);
+        const point = local(event);
+        pointers.set(event.pointerId, point);
+        const both = pair();
+        if (both !== null) {
+            pinch = { view: control.view(), ...both };
+            drag = null;
+        }
+        else
+            drag = { start: point, last: point, moved: false };
+    };
+    const onMove = (event) => {
+        const point = local(event);
+        if (!pointers.has(event.pointerId)) {
+            if (event.pointerType !== 'touch')
+                control.hover(point);
+            return;
+        }
+        pointers.set(event.pointerId, point);
+        const sizes = control.sizes();
+        if (sizes === null)
+            return;
+        const both = pair();
+        if (pinch !== null && both !== null) {
+            control.setView(pinchView(pinch, both, sizes.viewport, sizes.picture));
+            return;
+        }
+        if (drag === null)
+            return;
+        if (!drag.moved && Math.hypot(point.x - drag.start.x, point.y - drag.start.y) < PRESS_SLOP_PX)
+            return;
+        if (!drag.moved)
+            canvas.setAttribute('data-dragging', '');
+        drag.moved = true;
+        control.setView(panBy(control.view(), point.x - drag.last.x, point.y - drag.last.y, sizes.viewport, sizes.picture));
+        drag.last = point;
+    };
+    const onUp = (event) => {
+        if (!pointers.delete(event.pointerId))
+            return;
+        if (drag !== null && !drag.moved && pinch === null)
+            control.press(local(event));
+        if (pointers.size < 2)
+            pinch = null;
+        drag = null;
+        canvas.removeAttribute('data-dragging');
+    };
+    const onLeave = () => {
+        if (pointers.size === 0)
+            control.hover(null);
+    };
+    const onWheel = (event) => {
+        const sizes = control.sizes();
+        if (sizes === null)
+            return;
+        const intent = wheelIntent(event, control.wheelMode());
+        if (intent === 'page') {
+            control.hintWheel();
+            return;
+        }
+        event.preventDefault();
+        const view = control.view();
+        if (intent === 'pan') {
+            control.setView(panBy(view, -wheelPixels(event.deltaX, event.deltaMode, sizes.viewport.width), -wheelPixels(event.deltaY, event.deltaMode, sizes.viewport.height), sizes.viewport, sizes.picture));
+            return;
+        }
+        const delta = wheelPixels(event.deltaY, event.deltaMode, sizes.viewport.height);
+        const factor = isMouseWheel(event) && !event.ctrlKey ? mouseWheelZoomFactor(delta) : wheelZoomFactor(delta);
+        control.setView(zoomAt(view, local(event), view.scale * factor, sizes.viewport, sizes.picture));
+    };
+    const onDouble = (event) => {
+        const sizes = control.sizes();
+        if (sizes === null)
+            return;
+        const view = control.view();
+        control.setView(zoomAt(view, local(event), toggledScale(view, sizes.viewport, sizes.picture), sizes.viewport, sizes.picture), true);
+    };
+    const onKey = (event) => {
+        if (event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const sizes = control.sizes();
+        if (sizes === null)
+            return;
+        const view = control.view();
+        const zoom = (factor) => control.setView(zoomAt(view, middleOf(sizes.viewport), view.scale * factor, sizes.viewport, sizes.picture), true);
+        const pan = (dx, dy) => control.setView(panBy(view, dx, dy, sizes.viewport, sizes.picture), true);
+        const keys = {
+            '+': () => zoom(VIEWER_ZOOM_STEP),
+            '=': () => zoom(VIEWER_ZOOM_STEP),
+            '-': () => zoom(1 / VIEWER_ZOOM_STEP),
+            '0': () => control.fit(),
+            ArrowLeft: () => pan(VIEWER_PAN_STEP, 0),
+            ArrowRight: () => pan(-VIEWER_PAN_STEP, 0),
+            ArrowUp: () => pan(0, VIEWER_PAN_STEP),
+            ArrowDown: () => pan(0, -VIEWER_PAN_STEP),
+            Escape: () => control.release(),
+        };
+        const action = keys[event.key];
+        if (action === undefined)
+            return;
+        event.preventDefault();
+        action();
+    };
+    canvas.addEventListener('pointerdown', onDown);
+    canvas.addEventListener('pointermove', onMove);
+    canvas.addEventListener('pointerup', onUp);
+    canvas.addEventListener('pointercancel', onUp);
+    canvas.addEventListener('pointerleave', onLeave);
+    canvas.addEventListener('wheel', onWheel, { passive: false });
+    canvas.addEventListener('dblclick', onDouble);
+    canvas.addEventListener('keydown', onKey);
+    return () => {
+        canvas.removeEventListener('pointerdown', onDown);
+        canvas.removeEventListener('pointermove', onMove);
+        canvas.removeEventListener('pointerup', onUp);
+        canvas.removeEventListener('pointercancel', onUp);
+        canvas.removeEventListener('pointerleave', onLeave);
+        canvas.removeEventListener('wheel', onWheel);
+        canvas.removeEventListener('dblclick', onDouble);
+        canvas.removeEventListener('keydown', onKey);
+    };
+}

package/dist/element/plotwork-diagram.d.ts

@@ -0,0 +1,21 @@
+import type { ViewerLabels } from './copy.js';
+/** The attributes the element reads. */
+export declare const OBSERVED_ATTRIBUTES: readonly ['src', 'theme', 'live', 'interval', 'fingerprint', 'wheel', 'label'];
+/** What a page can call and set on `<plotwork-diagram>`, besides its attributes. */
+export interface PlotworkDiagramElement extends HTMLElement {
+    /** The picture's text, for a page that already holds it (a bundler import). It wins over `src`. */
+    svg: string | null;
+    /** Words in the page's language, over the English defaults. */
+    labels: Partial<ViewerLabels> | undefined;
+    /** The fingerprint of the picture shown, or null. */
+    readonly fingerprint: string | null;
+    /** The source the picture carries, or null when it carries none. */
+    source(): string | null;
+    fit(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Loads the picture again, checking the server's copy. */
+    reload(): Promise<void>;
+}
+/** The element's class, made on first use so that importing the package where there is no `HTMLElement` (a server render) is safe. */
+export declare function createPlotworkDiagramClass(): CustomElementConstructor;