New: Annotation Support

Adds support for annotations on manifests, and provisional support for an annotation server.

Refs #568

Author: ahankinson

Makefile

@@ -6,6 +6,7 @@ TS_ESM_SRC := src/diva-esm.ts
 TS_VE_SRC := src/viewer-element.ts
 TS_FT_SRC := src/filters.ts
 TS_AUTH_SRC := src/auth.ts
+TS_UTILS_SRC := src/image-utils.ts
 CSS_SRC := $(wildcard src/styles/*.css)
 DIVA_CSS := cache/diva.css
 ELM_OUT := cache/elm.js
@@ -69,14 +70,14 @@ $(ELM_ESM): $(ELM_OUT) $(ELM_ESM_SCRIPT)
 $(DIVA_CSS): $(CSS_SRC) scripts/minify-css.mjs
 	node ./scripts/minify-css.mjs
 
-$(DIVA_DEBUG): $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(DIVA_CSS) $(ELM_ESM)
+$(DIVA_DEBUG): $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(TS_UTILS_SRC) $(DIVA_CSS) $(ELM_ESM)
 	mkdir -p public
 	$(ESBUILD) $(TS_SRC) $(ESBUILD_COMMON_FLAGS) --format=iife --outfile=$(DIVA_DEBUG)
 
-$(DIVA_IIFE_BUNDLE): $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(DIVA_CSS) $(ELM_ESM)
+$(DIVA_IIFE_BUNDLE): $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(TS_UTILS_SRC) $(DIVA_CSS) $(ELM_ESM)
 	@$(ESBUILD) $(TS_SRC) $(ESBUILD_COMMON_FLAGS) --format=iife --outfile=$(DIVA_IIFE_BUNDLE)
 
-$(DIVA_ESM_BUNDLE): $(TS_ESM_SRC) $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(DIVA_CSS) $(ELM_ESM)
+$(DIVA_ESM_BUNDLE): $(TS_ESM_SRC) $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(TS_UTILS_SRC) $(DIVA_CSS) $(ELM_ESM)
 	@$(ESBUILD) $(TS_ESM_SRC) $(ESBUILD_COMMON_FLAGS) --format=esm --outfile=$(DIVA_ESM_BUNDLE)
 
 $(DIVA_JS): $(DIVA_IIFE_BUNDLE) .swcrc
@@ -87,7 +88,7 @@ $(DIVA_ESM): $(DIVA_ESM_BUNDLE) .swcrc
 	@mkdir -p build
 	@$(SWC) $(DIVA_ESM_BUNDLE) --out-file $(DIVA_ESM)
 
-$(DIVA_TYPES): $(TS_ESM_SRC) $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) src/public-api.ts tsconfig.json
+$(DIVA_TYPES): $(TS_ESM_SRC) $(TS_SRC) $(TS_VE_SRC) $(TS_FT_SRC) $(TS_AUTH_SRC) $(TS_UTILS_SRC) src/public-api.ts tsconfig.json
 	@mkdir -p build
 	@yarn -s tsc -p tsconfig.json --declaration --emitDeclarationOnly --outDir build
 

browser-tests/public-api.spec.ts

@@ -122,6 +122,42 @@ test("exposes immutable IIIF page metadata and state", async ({page}) => {
     expect(result.state).toMatchObject({ready : true, pageCount : 4, resourceUrl : `${origin}/api/first/manifest`});
 });
 
+test("returns the IIIF Image API region for an API-supplied rectangle annotation", async ({page}) => {
+    const result = await page.evaluate((canvasId) => {
+        const diva = (window as any).diva;
+        diva.setAnnotation({
+            id : "api-region",
+            type : "Annotation",
+            body : {type : "TextualBody", value : "Region"},
+            target : {
+                type : "SpecificResource",
+                source : canvasId,
+                selector : {type : "FragmentSelector", value : "xywh=10.2,20.8,30.1,40.1"}
+            }
+        });
+        return diva.getImageRegionForAnnotation("api-region");
+    }, `${origin}/api/first/canvas/1`);
+
+    expect(result).toBe(`${origin}/api/first/image/1/10,20,31,41/!320,320/0/default.jpg`);
+});
+
+test("returns null when an annotation has no IIIF Image API region", async ({page}) => {
+    const result = await page.evaluate(() => (window as any).diva.getImageRegionForAnnotation("missing"));
+    expect(result).toBeNull();
+});
+
+test("recreates scrollbar references after its viewer element is reattached", async ({page}) => {
+    const attached = await page.evaluate(() => {
+        const viewer = document.querySelector("osd-viewer") as HTMLElement & {scrollbarTrack?: HTMLElement|null};
+        const parent = viewer.parentElement!;
+        viewer.remove();
+        parent.appendChild(viewer);
+        return Boolean(viewer.scrollbarTrack);
+    });
+
+    expect(attached).toBe(true);
+});
+
 test("labels modal close buttons", async ({page}) => {
     for (const opener of [ "Manifest Info", "Page View" ])
     {

build/auth.d.ts

@@ -1,10 +1,6 @@
 import type { DivaStaticImageCorsPolicy } from "./public-api";
-export type TileSourceDescriptor = {
-    sourceId: string;
-    url: string;
-    isStatic: boolean;
-};
-export type ResolvedTileSource = string | Record<string, unknown>;
+import { type ResolvedTileSource, type TileSourceDescriptor } from "./image-utils";
+export type { ResolvedTileSource, TileSourceDescriptor } from "./image-utils";
 type SendPort<T> = {
     send: (value: T) => void;
 };
@@ -106,6 +102,8 @@ export declare class AuthBrowser {
     invalidateSources(sourceIds: string[]): void;
     useNonCorsStaticSource(sourceId: string): void;
     destroy(): void;
+    private cancelBrowserWork;
+    private closePopups;
     private succeed;
     private fail;
     private startResolution;
@@ -120,4 +118,3 @@ export declare class AuthBrowser {
     private startFrame;
     private cancelFrame;
 }
-export {};

build/diva.d.ts

@@ -1,6 +1,6 @@
 import "./viewer-element";
-import type { DivaEventMap, DivaLayoutMode, DivaOptions, DivaPage, DivaPageSelector, DivaRegion, DivaState, ZoomToRegionOptions } from "./public-api";
-export type { DivaEventMap, DivaImage, DivaLayoutMode, DivaOptions, DivaPage, DivaPageSelector, DivaPageTarget, DivaRegion, DivaSidebarPanel, DivaStaticImageCorsPolicy, DivaState, DivaViewingDirection, ZoomToRegionOptions } from "./public-api";
+import type { DivaEventMap, DivaAnnotation, DivaLayoutMode, DivaOptions, DivaPage, DivaPageSelector, DivaRegion, DivaState, ZoomToRegionOptions } from "./public-api";
+export type { DivaEventMap, DivaAnnotation, DivaImage, DivaLayoutMode, DivaOptions, DivaPage, DivaPageSelector, DivaPageTarget, DivaRegion, DivaSidebarPanel, DivaStaticImageCorsPolicy, DivaState, DivaViewingDirection, ZoomToRegionOptions } from "./public-api";
 /**
  * A browser viewer for IIIF Presentation manifests and collections.
  *
@@ -64,6 +64,11 @@ export declare class Diva extends EventTarget {
     private pages;
     private readonly pagesByCanvasId;
     private readonly pagesByLabel;
+    private readonly manifestAnnotationsByCanvas;
+    private readonly apiAnnotationsByCanvas;
+    private readonly clearedAnnotationCanvases;
+    private readonly annotationImageServicesByCanvas;
+    private annotationResourceId;
     private state;
     private readyResolve;
     private readyReject;
@@ -110,6 +115,9 @@ export declare class Diva extends EventTarget {
     private bindPorts;
     private ensureMainViewer;
     private copyPage;
+    private effectiveAnnotationsForCanvas;
+    private applyAnnotationsForCanvas;
+    private findStoredAnnotation;
     private rebuildPageIndexes;
     private pageForSelector;
     private copyState;
@@ -160,6 +168,26 @@ export declare class Diva extends EventTarget {
      * @returns Pages in zero-based display order. Auth tokens and resolved loading URLs are never included.
      */
     getPages(): readonly DivaPage[];
+    /** Add or replace one API-supplied Web Annotation on a loaded Canvas. */
+    setAnnotation(annotation: DivaAnnotation): void;
+    /** Replace the API-supplied annotation set for the loaded manifest. */
+    setAnnotations(annotations: readonly DivaAnnotation[]): void;
+    /** Return defensive Web Annotation snapshots for one Canvas. */
+    getAnnotationsForCanvas(uri: string): readonly DivaAnnotation[];
+    /** Return defensive Web Annotation snapshots for the loaded manifest. */
+    getAllAnnotations(): readonly DivaAnnotation[];
+    /** Clear both manifest and API-supplied annotations for one Canvas. */
+    clearAnnotationsForCanvas(uri: string): void;
+    /** Clear both manifest and API-supplied annotations for every Canvas. */
+    clearAllAnnotations(): void;
+    /**
+     * Return the IIIF Image API extract URL for an annotation, when available.
+     *
+     * @returns The extract URL, or `null` when the annotation is unknown or has no usable image region.
+     */
+    getImageRegionForAnnotation(annotationId: string): string | null;
+    /** Return an annotation body's textual or HTML value, if present. */
+    getAnnotationBody(annotationId: string): string | undefined;
     /**
      * Find a displayed page by Canvas identifier or localized display label.
      *