@laminapdf/viewer 0.2.0-alpha.4 → 0.2.0-alpha.5

package/dist/view/viewer.js

@@ -12,16 +12,19 @@ import { pagePixels } from "@laminapdf/render";
 import { BitmapCache } from "../canvas/cache.js";
 import { CanvasPool } from "../canvas/pool.js";
 import { FindController } from "../find/controller.js";
+import { NavigationHistory } from "../history/history.js";
 import { HighlightLayer } from "../layers/highlight-layer.js";
+import { LinkLayer } from "../layers/link-layer.js";
 import { TextLayer } from "../layers/text-layer.js";
 import { isRotation, PageLayout, rotated } from "../layout/page-layout.js";
 import { range } from "../layout/range.js";
-import { renderKey, renderKeyFields } from "../protocol.js";
+import { appearanceField, appearanceKey, renderKey, renderKeyFields, } from "../protocol.js";
 import { backdropRatio, bounds, contains, lowScale, sharpScale, tilesFor } from "../render/tiles.js";
 import { destinationView } from "../zoom/destination.js";
 import { contentPosition, percentOfScale, pointAt, scaleFor, scrollToPoint, } from "../zoom/zoom.js";
 import { deviceHints, viewerBudgets } from "./budgets.js";
 import { TouchGestures } from "./touch.js";
+import { setUserSelect } from "./user-select.js";
 /** The built-in layer slots, bottom to top, above the canvas. */
 const SLOTS = ["text", "annot", "highlight"];
 /** The tallest scroll space browsers handle (Firefox stops near 17.9 M CSS px). */
@@ -29,6 +32,19 @@ const MAX_HEIGHT = 16_000_000;
 function isAbort(e) {
     return e instanceof DOMException && e.name === "AbortError";
 }
+/** The state before a document opens. */
+function emptyState(zoom) {
+    return {
+        pageCount: 0,
+        currentPage: 0,
+        zoom,
+        percent: 100,
+        rotation: 0,
+        appearance: "original",
+        scrollTop: 0,
+        visibleRange: { first: 0, last: -1 },
+    };
+}
 /** What a painted canvas depends on: a zoom or a rotation makes it stale. */
 function geometryOf(layout) {
     return `${layout.scale}:${layout.rotation}`;
@@ -64,10 +80,22 @@ export class Viewer {
     /** The text layer, unless `text: false`. */
     #text;
     #highlights;
+    /** The link layer, unless `links: false`. */
+    #links;
     /** Find in this viewer's document: query, options, matches, next and previous. */
     find;
+    /**
+     * Back and forward through the places jumped from and to: links, `jumpToPage`,
+     * `jumpToDestination` and find's matches record a jump; scrolling doesn't.
+     */
+    history;
     /** Pages kept mounted whatever the scroll (`keepMounted`): those a selection touches. */
     #pinned = new Set();
+    #regions;
+    /** The page a jump landed on, focused once it is mounted. */
+    #focusTarget;
+    /** True while a jump that leaves focus where it is (a find match) runs. */
+    #keepFocus = false;
     #listeners = new Set();
     #events = new Map();
     #cleanup = [];
@@ -114,31 +142,28 @@ export class Viewer {
         this.#spacer.className = "lamina-viewer-content";
         Object.assign(this.#spacer.style, { position: "relative" });
         this.#root.append(this.#spacer);
-        this.#state = {
-            pageCount: 0,
-            currentPage: 0,
-            zoom: this.#zoom,
-            percent: 100,
-            rotation: 0,
-            scrollTop: 0,
-            visibleRange: { first: 0, last: -1 },
-        };
+        this.#state = emptyState(this.#zoom);
         this.#listen();
-        if (options.text !== false) {
-            const host = {
-                root: this.#root,
-                client: this.#client,
-                rotation: () => this.#rotation,
-                keepMounted: (pages) => this.keepMounted(pages),
-            };
-            this.#text = new TextLayer(host, options.text === true || options.text === undefined ? {} : options.text);
+        this.#text = this.#textLayer(options.text);
+        if (this.#text !== undefined)
             this.addLayer(this.#text);
+        this.history = new NavigationHistory({ place: () => this.#place(), show: (p) => this.#show(p) }, options.history);
+        this.#regions = options.pages ?? {};
+        if (this.#regions.focusOnJump === true) {
+            this.history.onEntry((entry, replaced) => {
+                if (replaced || this.#keepFocus)
+                    return;
+                this.#focusTarget = entry.point.page;
+                this.#schedule();
+            });
         }
         this.find = new FindController({
             find: (query, find, pages, signal) => this.#client.find(query, find, pages, { signal }),
             pageCount: () => this.#sizes.length,
             currentPage: () => this.#state.currentPage,
-            reveal: (page, quads) => this.#reveal(page, quads),
+            // Each match find moves to is a jump, so Back returns to where the search started.
+            // A match is a jump too, but focus stays in the find field.
+            reveal: (page, quads) => this.#jumpKeepingFocus(() => this.#reveal(page, quads)),
             redraw: (pages) => this.#highlights.refresh(pages),
         });
         this.#highlights = new HighlightLayer({
@@ -147,6 +172,7 @@ export class Viewer {
             rotation: () => this.#rotation,
         });
         this.addLayer(this.#highlights);
+        this.#links = this.#linkLayer(options.links);
     }
     /** The scroll container (append it, or use {@link mount}). */
     get element() {
@@ -163,7 +189,9 @@ export class Viewer {
         this.#cache.clear();
         this.#document = document;
         this.#pinned = new Set();
+        this.#focusTarget = undefined;
         this.find.reset();
+        this.history.reset();
         this.#text?.open(document);
         this.#sizes = document.pages.map((p) => ({ width: p.width, height: p.height }));
         this.#layout = undefined;
@@ -192,6 +220,23 @@ export class Viewer {
         set.add(l);
         return () => set.delete(l);
     }
+    /**
+     * Copies the text selection to the clipboard: by paragraph in reading order, or exact, as laid
+     * out. Call it in a user gesture (a click, a key). Resolves false when nothing is selected or
+     * the clipboard refused.
+     */
+    copySelection(mode = "paragraph") {
+        return this.#text?.copy(mode) ?? Promise.resolve(false);
+    }
+    /** Whether a plain drag selects a rectangle, as an Alt/Option-drag does (column selection). */
+    get columnSelect() {
+        return this.#text?.columnMode ?? false;
+    }
+    /** Turns column selection by plain drag on or off; Alt/Option-drag selects a rectangle either way. */
+    set columnSelect(on) {
+        if (this.#text !== undefined)
+            this.#text.columnMode = on;
+    }
     /**
      * Keeps `pages` mounted wherever the view scrolls, until the next call replaces them: the pages
      * a text selection touches, so scrolling never takes the selection away. A pinned page out of
@@ -253,6 +298,14 @@ export class Viewer {
             this.#root.scrollLeft = Math.max(0, at.x);
         this.#schedule();
     }
+    /** {@link goToPage} as a history jump: Back returns to where the view was. */
+    jumpToPage(index) {
+        this.history.jump(() => this.goToPage(index));
+    }
+    /** {@link goToDestination} as a history jump: Back returns to where the view was. */
+    jumpToDestination(target) {
+        this.history.jump(() => this.goToDestination(target));
+    }
     /**
      * Sets the zoom (a mode, or a percentage clamped to 10–800 %), keeping the document point at
      * `anchor` (viewport CSS px; default its centre) where it is.
@@ -275,6 +328,33 @@ export class Viewer {
         // A half turn keeps every page's size, so no layer hears of it from a resize.
         this.#text?.refresh();
         this.#highlights.refresh();
+        this.#links?.refresh();
+    }
+    /**
+     * Draws the pages in `appearance` (Sepia, Dark, High contrast or their own colours), keeping the
+     * scroll position: pages in view paint again, a quick pass then sharp tiles, and none of their
+     * old pixels is kept; other pages give their canvas back and paint when they come into view.
+     * The thumbnails follow.
+     */
+    setAppearance(appearance) {
+        if (appearanceKey(appearance) === appearanceKey(this.#state.appearance))
+            return;
+        const { first, last } = this.#state.visibleRange;
+        for (const view of [...this.#pages.values()]) {
+            this.#abort(view);
+            view.tiles.clear();
+            view.detail?.tiles.clear();
+            if (view.index >= first && view.index <= last) {
+                view.appearance = appearanceKey(appearance);
+                view.painted = "";
+            }
+            else {
+                // Its shell shows the new paper until it is seen (`#readyForAppearance`).
+                this.#releaseCanvas(view);
+            }
+        }
+        this.#setState({ appearance });
+        this.#schedule();
     }
     /** The document point at viewport position (`x`, `y`) in CSS px. */
     pointAt(x, y) {
@@ -321,11 +401,53 @@ export class Viewer {
         this.#cache.clear();
         this.find.reset();
         this.#text?.destroy();
+        this.#links?.destroy();
         for (const f of this.#cleanup.splice(0))
             f();
         this.#root.remove();
     }
     // --- internals ---
+    /** The link layer, added to every page, unless `links` is `false`. */
+    #linkLayer(links) {
+        if (links === false)
+            return undefined;
+        const layer = new LinkLayer({
+            root: this.#root,
+            client: this.#client,
+            points: (page) => this.#sizes[page],
+            rotation: () => this.#rotation,
+            pageCount: () => this.#sizes.length,
+            goTo: (target) => this.jumpToDestination(target),
+            goToPage: (page) => this.jumpToPage(page),
+        }, links === true || links === undefined ? {} : links);
+        this.addLayer(layer);
+        return layer;
+    }
+    /**
+     * Where the view is, for the history: the document point a gap below the viewport's top-left (so
+     * a page that `goToPage` put at the top, half a gap down, is the one named), and the zoom.
+     */
+    #place() {
+        const layout = this.#layout;
+        if (layout === undefined || layout.pageCount === 0)
+            return undefined;
+        return { point: pointAt(layout, this.#root.clientWidth, this.#scroll(), { x: 0, y: this.#gap }), zoom: this.#zoom };
+    }
+    /** Puts the view back at a history `place`: its zoom, then its point a gap below the viewport's top-left. */
+    #show(place) {
+        this.#touch.stopMomentum();
+        if (place.zoom !== this.#zoom) {
+            this.#zoom = place.zoom;
+            this.#rezoom(undefined);
+        }
+        const layout = this.#layout;
+        if (layout === undefined || place.point.page >= layout.pageCount)
+            return;
+        const at = contentPosition(layout, this.#root.clientWidth, place.point);
+        this.#root.scrollTop = Math.max(0, at.y - this.#gap);
+        this.#root.scrollLeft = Math.max(0, at.x);
+        this.#schedule();
+    }
     /**
      * Scrolls so that `quads` (a find match, in page `page`'s points) are in view: nothing moves
      * when they already are, else they come to the viewport's centre.
@@ -370,6 +492,25 @@ export class Viewer {
     #viewport() {
         return { width: this.#root.clientWidth || 800, height: this.#root.clientHeight || 600 };
     }
+    /** The text layer `option` asks for, or none (`false`); it reports the selection as an event too. */
+    #textLayer(option) {
+        if (option === false)
+            return undefined;
+        const host = {
+            root: this.#root,
+            client: this.#client,
+            rotation: () => this.#rotation,
+            keepMounted: (pages) => this.keepMounted(pages),
+        };
+        const textOptions = option === true || option === undefined ? {} : option;
+        return new TextLayer(host, {
+            ...textOptions,
+            onSelection: (selection) => {
+                textOptions.onSelection?.(selection);
+                this.#emit("selectionchange", { selection });
+            },
+        });
+    }
     #emit(event, data) {
         for (const l of this.#events.get(event) ?? [])
             l(data);
@@ -480,6 +621,7 @@ export class Viewer {
         const [first, last] = this.#mountRange(frame);
         // Writes.
         this.#placeShells(frame, first, last);
+        this.#focusJumpTarget();
         this.#setState({
             currentPage: layout.pageAt(frame.top + frame.height / 2),
             scrollTop: frame.top,
@@ -516,6 +658,24 @@ export class Viewer {
         if (this.#pages.size > this.#peakMounted)
             this.#peakMounted = this.#pages.size;
     }
+    #jumpKeepingFocus(go) {
+        this.#keepFocus = true;
+        try {
+            this.history.jump(go);
+        }
+        finally {
+            this.#keepFocus = false;
+        }
+    }
+    /** Focuses the page the last jump landed on, once it is mounted, keeping the scroll where it is. */
+    #focusJumpTarget() {
+        const target = this.#focusTarget;
+        const view = target === undefined ? undefined : this.#pages.get(target);
+        if (view === undefined)
+            return;
+        this.#focusTarget = undefined;
+        view.shell.focus({ preventScroll: true });
+    }
     #notifyResize(view, width, height) {
         for (const layer of this.#layers)
             layer.onZoom?.(view.index, this.#slot(view, layer.name), { width, height });
@@ -533,7 +693,17 @@ export class Viewer {
         const shell = document.createElement("div");
         shell.className = "lamina-page";
         shell.dataset.pageIndex = String(index);
-        Object.assign(shell.style, { position: "absolute", contain: "strict", background: "#fff" });
+        // A region for assistive technology, and a place focus can land after a jump.
+        shell.setAttribute("role", "region");
+        shell.setAttribute("aria-roledescription", this.#regions.roleDescription ?? "page");
+        shell.setAttribute("aria-label", this.#pageName(index));
+        shell.tabIndex = -1;
+        // The paper shows before the page is drawn: white, or the page appearance's (--lamina-page-paper).
+        Object.assign(shell.style, {
+            position: "absolute",
+            contain: "strict",
+            background: "var(--lamina-page-paper, #fff)",
+        });
         this.#spacer.append(shell);
         const view = {
             index,
@@ -543,6 +713,7 @@ export class Viewer {
             controller: new AbortController(),
             state: "placeholder",
             painted: "",
+            appearance: appearanceKey(this.#state.appearance),
             scale: 0,
             tiles: new Set(),
             detail: undefined,
@@ -565,9 +736,13 @@ export class Viewer {
             slot.className = `lamina-layer-${name}`;
             Object.assign(slot.style, { position: "absolute", inset: "0" });
             // The slots above the text cover the whole page: taking the pointer, they would sit between
-            // every press and the spans, and no drag could select text.
-            if (name !== "text")
+            // every press and the spans, and no drag could select text. Nor are they part of a selection:
+            // each element the viewer adds that holds nothing to select sets `none` itself, never an
+            // ancestor of the spans (user-select.ts).
+            if (name !== "text") {
                 slot.style.pointerEvents = "none";
+                setUserSelect(slot, "none");
+            }
             view.slots.set(name, slot);
             view.shell.append(slot);
         }
@@ -580,6 +755,10 @@ export class Viewer {
         view.pass++;
         view.busy = false;
     }
+    #pageName(index) {
+        const count = this.#sizes.length;
+        return this.#regions.name?.(index, count) ?? `Page ${index + 1} of ${count}`;
+    }
     #unmount(view) {
         this.#abort(view);
         for (const layer of this.#layers)
@@ -635,7 +814,7 @@ export class Viewer {
     }
     /** The tile `clip` of page `index` at `scale`: its render request and cache key. */
     #tile(index, layout, scale, clip) {
-        const request = { page: index, scale, rotation: layout.rotation, clip };
+        const request = { page: index, scale, rotation: layout.rotation, clip, ...appearanceField(this.#state.appearance) };
         return { clip, request, key: renderKey(request, this.#document?.id ?? 0) };
     }
     /** The device px per pt of a sharp tile: the layout's scale × the device pixel ratio. */
@@ -665,6 +844,42 @@ export class Viewer {
             return false;
         return tiles.every((t) => detail.tiles.has(t.key));
     }
+    /**
+     * Whether `view` may paint now, catching it up with the appearance: a page out of view when the
+     * appearance changed waits until it is seen (`prefetch` doesn't paint it), then starts afresh.
+     */
+    #readyForAppearance(view, priority) {
+        const appearance = appearanceKey(this.#state.appearance);
+        if (view.appearance === appearance)
+            return true;
+        if (priority === "prefetch")
+            return false;
+        view.appearance = appearance;
+        view.painted = "";
+        return true;
+    }
+    /**
+     * Whether `view`'s canvas needs nothing for `frame`: painted at its geometry and, in view, with
+     * every tile in view drawn (then it is sharp). A margin page painted at its geometry waits.
+     */
+    #upToDate(view, priority, frame) {
+        if (view.painted !== geometryOf(frame.layout))
+            return false;
+        if (priority === "prefetch")
+            return true;
+        // Sharp means every tile now in view is drawn: scrolling down a tall page sharpens the rest.
+        if (view.scale > 0 && this.#sharpInView(view, frame)) {
+            if (view.state !== "sharp") {
+                view.state = "sharp";
+                this.#emit("renderstats", this.stats());
+            }
+            return true;
+        }
+        // Tiles in view are missing (the page scrolled): it is no longer sharp until they are drawn.
+        if (view.state === "sharp")
+            view.state = "low";
+        return false;
+    }
     /** Starts page `index`'s pass if it isn't busy and its canvas isn't done for `frame` yet. */
     #paint(index, priority, frame) {
         const view = this.#pages.get(index);
@@ -674,22 +889,8 @@ export class Viewer {
         if (view === undefined || this.#document === undefined || view.busy || view.waiting || view.state === "error") {
             return;
         }
-        const { layout } = frame;
-        if (view.painted === geometryOf(layout)) {
-            if (priority === "prefetch")
-                return;
-            // Sharp means every tile now in view is drawn: scrolling down a tall page sharpens the rest.
-            if (view.scale > 0 && this.#sharpInView(view, frame)) {
-                if (view.state !== "sharp") {
-                    view.state = "sharp";
-                    this.#emit("renderstats", this.stats());
-                }
-                return;
-            }
-            // Tiles in view are missing (the page scrolled): it is no longer sharp until they are drawn.
-            if (view.state === "sharp")
-                view.state = "low";
-        }
+        if (!this.#readyForAppearance(view, priority) || this.#upToDate(view, priority, frame))
+            return;
         view.busy = true;
         const pass = view.pass;
         void this.#pass(view, pass, priority, frame)
@@ -744,7 +945,12 @@ export class Viewer {
         const cssW = layout.widths[index];
         const cssH = layout.heights[index];
         const shown = rotated(this.#sizes[index], layout.rotation);
-        const request = { page: index, scale: lowScale(layout.scale * dpr, shown.width), rotation: layout.rotation };
+        const request = {
+            page: index,
+            scale: lowScale(layout.scale * dpr, shown.width),
+            rotation: layout.rotation,
+            ...appearanceField(this.#state.appearance),
+        };
         const low = await this.#bitmap(request, renderKey(request, this.#document?.id ?? 0), priority, signal);
         if (!live()) {
             this.#drop(low);
@@ -921,6 +1127,7 @@ export class Viewer {
         });
         if (old === undefined) {
             canvas.className = "lamina-page-detail";
+            setUserSelect(canvas, "none");
             if (view.canvas === undefined)
                 view.shell.prepend(canvas);
             else
@@ -1010,6 +1217,7 @@ export class Viewer {
         if (canvas === undefined)
             return undefined;
         canvas.className = "lamina-page-canvas";
+        setUserSelect(canvas, "none");
         Object.assign(canvas.style, { position: "absolute", inset: "0", width: "100%", height: "100%" });
         view.shell.prepend(canvas);
         view.canvas = canvas;