@annotorious/react-manifold 0.0.2

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Annotorious
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,7 @@
+# Annotorious React Manifold
+
+A utility to manage multiple parallel Annotorious instances more efficiently.
+
+- Listen to annotation lifecycle events across all instances with just one listener.
+- Find, retrieve and manipulate annotations across instances easily.
+- Add multiple Annotorious instances with the same image, and let the Manifold handle live state sync.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@annotorious/react-manifold",
+  "version": "0.0.2",
+  "description": "A utility to manage multiple parallel Annotorious instances more efficiently",
+  "author": "Rainer Simon",
+  "license": "BSD-3-Clause",
+  "homepage": "https://github.com/annotorious/annotorious-react-manifold#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/annotorious/annotorious-react-manifold.git"
+  },
+  "bugs": {
+    "url": "https://github.com/annotorious/annotorious-react-manifold/issues"
+  },
+  "type": "module",
+  "scripts": {
+    "start": "vite",
+    "build": "tsc && vite build"
+  },
+  "main": "src/index.ts",
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/react": "^18.2.35",
+    "@types/react-dom": "^18.2.14",
+    "@vitejs/plugin-react": "^4.1.1",
+    "svelte": "^3.59.2",
+    "typescript": "^4.9.5",
+    "vite": "^4.5.0",
+    "vite-plugin-dts": "^3.6.3",
+    "vite-tsconfig-paths": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@annotorious/react": "^3.0.0-pre-alpha-55",
+    "react": "16.8.0 || >=17.x || >=18.x",
+    "react-dom": "16.8.0 || >=17.x || >=18.x"
+  },
+  "dependencies": {
+    "@annotorious/core": "^3.0.0-pre-alpha-55"
+  }
+}

package/src/Annotorious.tsx

@@ -0,0 +1,48 @@
+import { ReactNode, useContext, useEffect } from 'react';
+import { Annotation, Annotator, useAnnotator } from '@annotorious/react';
+import { Annotorious as AnnotoriousInstance } from '@annotorious/react';
+import { AnnotoriousManifoldContext } from './AnnotoriousManifold';
+
+interface AnnotoriousProps {
+
+  children: ReactNode;
+
+  source: string;
+
+}
+
+/**
+ * Consumes the standard Annotorious context, and passes the Annotator
+ * upwards to the manifold.
+ */
+const AnnotoriousInstanceShim = <I extends Annotation = Annotation, E extends unknown = Annotation>(props: AnnotoriousProps) => {
+
+  const anno = useAnnotator<Annotator<I, E>>();
+
+  const { connectAnnotator } = useContext(AnnotoriousManifoldContext);
+
+  useEffect(() => {
+    if (anno)
+      return connectAnnotator(props.source, anno);
+  }, [anno]);
+
+  return <>{props.children}</>;
+
+}
+
+/**
+ * An alternative <Annotorious /> component that mimicks the original
+ * from @annotorious/react, but injects the shim component, which connects
+ * the Annotator to the Manifold.
+ */
+export const Annotorious = (props: AnnotoriousProps) => {
+
+  return (
+    <AnnotoriousInstance>
+      <AnnotoriousInstanceShim source={props.source}>
+        {props.children}
+      </AnnotoriousInstanceShim>
+    </AnnotoriousInstance>
+  )
+
+}

package/src/AnnotoriousManifold.tsx

@@ -0,0 +1,140 @@
+import { ReactNode, createContext, useContext, useEffect, useRef, useState } from 'react';
+import type { Annotation, Annotator, StoreChangeEvent } from '@annotorious/core';
+import { AnnotoriousManifoldInstance, createManifoldInstance } from './AnnotoriousManifoldInstance';
+
+interface AnnotoriousManifoldContextValue {
+
+  annotators: Map<string, Annotator<any, unknown>>;
+
+  annotations: Map<string, Annotation[]>;
+
+  selection: ManifoldSelection;
+
+  connectAnnotator(source: string, anno: Annotator<any, unknown>): () => void;
+
+}
+
+interface ManifoldSelection<T extends Annotation = Annotation> {
+
+  source?: string;
+
+  selected: { annotation: T, editable?: boolean }[],
+
+  pointerEvent?: PointerEvent;
+
+}
+
+// @ts-ignore
+export const AnnotoriousManifoldContext = createContext<AnnotoriousManifoldContextValue>();
+
+export const AnnotoriousManifold = (props: { children: ReactNode }) => {
+
+  const [annotators, setAnnotators] = useState<Map<string, Annotator<any, unknown>>>(new Map());
+
+  const [annotations, setAnnotations] = useState<Map<string, Annotation[]>>(new Map());
+
+  const [selection, setSelection] = 
+    useState<ManifoldSelection>({ selected: [] });
+
+  // To prevent selection state updates when de-selecting other annotators
+  const muteSelectionEvents = useRef<boolean>(false);
+
+  const connectAnnotator = (source: string, anno: Annotator<any, unknown>) => {
+    // Add the annotator to the state
+    setAnnotators(m => new Map(m.entries()).set(source, anno))
+
+    const { store } = anno.state;
+    const selectionState = anno.state.selection;
+
+    // Add the annotations to the state
+    setAnnotations(m => new Map(m.entries()).set(source, store.all()));
+
+    const onStoreChange = () =>
+      setAnnotations(m => new Map(m.entries()).set(source, store.all()));
+
+    store.observe(onStoreChange);
+
+    // Track selection
+    let selectionStoreObserver: (event: StoreChangeEvent<Annotation>) => void;
+
+    const unsubscribeSelection = selectionState.subscribe(({ selected, pointerEvent }) => {
+      if (selectionStoreObserver) 
+        store.unobserve(selectionStoreObserver);
+
+      const resolved = (selected || [])
+        .map(({ id, editable }) => ({ annotation: store.getAnnotation(id), editable }));
+
+      // Set the new selection
+      if (!muteSelectionEvents.current)
+        setSelection({ source, selected: resolved, pointerEvent });
+
+      // Track the state of the selected annotations in the store
+      selectionStoreObserver = event => {
+        const { updated } = event.changes;
+
+        setSelection(({ source, selected }) => ({
+          source,
+          selected: selected.map(({ annotation, editable }) => {
+            const next = updated.find(u => u.oldValue.id === annotation.id);
+            return next ? { annotation: next.newValue, editable } : { annotation, editable };
+          }),
+          pointerEvent
+        }));
+      }
+
+      store.observe(selectionStoreObserver, { annotations: selected.map(({ id }) => id) });
+    });
+
+    return () => {
+      // Remove annotator
+      setAnnotators(m => new Map(Array.from(m.entries()).filter(([key, _]) => key !== source)));
+
+      // Remove & untrack annotations
+      setAnnotations(m => new Map(Array.from(m.entries()).filter(([key, _]) => key !== source)));
+      store.unobserve(onStoreChange);
+
+      // Un-track selection
+      unsubscribeSelection();
+    }
+  }
+
+  useEffect(() => {
+    if (selection.source) {
+      muteSelectionEvents.current = true;
+
+      Array.from(annotators.entries()).forEach(([source, anno]) => {
+        if (source !== selection.source)
+          anno.setSelected();
+      });
+
+      muteSelectionEvents.current = false;
+    }
+  }, [selection, annotators]);
+
+  return (
+    <AnnotoriousManifoldContext.Provider value={{   
+      annotators, 
+      annotations,
+      selection,
+      connectAnnotator 
+    }}>
+      {props.children}
+    </AnnotoriousManifoldContext.Provider>
+  )
+
+}
+
+export const useAnnotoriousManifold = <I extends Annotation = Annotation, E extends unknown = Annotation>() => {
+  const { annotators } = useContext(AnnotoriousManifoldContext);
+  return createManifoldInstance(annotators) as AnnotoriousManifoldInstance<I, E>;
+}
+
+export const useAnnotations = <T extends Annotation>() => {
+  const { annotations } = useContext(AnnotoriousManifoldContext);
+  return annotations as Map<string, T[]>;
+}
+
+export const useSelection = <T extends Annotation>() => {
+  const { selection } = useContext(AnnotoriousManifoldContext);
+  return selection as ManifoldSelection<T>;
+}

package/src/AnnotoriousManifoldInstance.ts

@@ -0,0 +1,95 @@
+import { 
+  Annotation, 
+  AnnotationBody, 
+  Annotator, 
+  LifecycleEvents,
+  Origin
+} from '@annotorious/core';
+
+export interface AnnotoriousManifoldInstance<I extends Annotation = Annotation, E extends unknown = Annotation> {
+
+  annotators: Annotator<I, E>[];
+
+  sources: string[];
+
+  // style: DrawingStyle | ((annotation: I) => DrawingStyle) | undefined;
+
+  addBody(body: AnnotationBody, origin?: Origin): void;
+
+  clear(origin: Origin): void;
+
+  deleteAnnotation(id: string, origin?: Origin): E | undefined;
+
+  destroy(): void;
+
+  getAnnotationById(id: string): E | undefined;
+
+  getAnnotations(): E[];
+  
+  on<T extends keyof LifecycleEvents<E>>(event: T, callback: LifecycleEvents<E>[T]): void;
+
+  off<T extends keyof LifecycleEvents<E>>(event: T, callback: LifecycleEvents<E>[T]): void;
+
+}
+
+export const createManifoldInstance = <I extends Annotation = Annotation, E extends unknown = Annotation>(
+  annotators: Map<string, Annotator<I, E>>
+): AnnotoriousManifoldInstance<I, E> => {
+
+  const find = (annotationId: string): { annotation?: E, annotator?: Annotator<I, E> } =>
+    Array.from(annotators.values()).reduce((found, annotator) => {
+      if (found)
+        return found;
+
+      const annotation = annotator.getAnnotationById(annotationId);
+      if (annotation) 
+        return { annotation, annotator };
+    }, undefined as { annotation: E, annotator: Annotator<I, E> } | undefined ) || 
+
+    { annotation: undefined, annotator: undefined };
+
+  /*********/
+  /** API **/
+  /*********/
+
+  const addBody = (body: AnnotationBody, origin = Origin.LOCAL) => {
+    const { annotator } = find(body.annotation);
+    if (annotator)
+      annotator.state.store.addBody(body, origin);
+  }
+
+  const clear = (origin = Origin.LOCAL) =>
+    Array.from(annotators.values()).forEach(a => a.state.store.clear(origin));
+
+  const deleteAnnotation = (id: string, origin = Origin.LOCAL) => {
+    const { annotation, annotator } = find(id);
+
+    if (annotator) {
+      annotator.state.store.deleteAnnotation(id, origin);
+      return annotation;
+    }
+  }
+
+  const destroy = () =>
+    Array.from(annotators.values()).forEach(a => a.destroy());
+
+  const getAnnotationById = (id: string) => 
+    find(id).annotation;
+
+  const getAnnotations = () => 
+    Array.from(annotators.values()).reduce((all, annotator) =>
+      [...all, ...annotator.getAnnotations()], [] as E[])
+
+  // @ts-ignore
+  return {
+    annotators: [...annotators.values()],
+    sources: [...annotators.keys()],
+    addBody,
+    clear,
+    deleteAnnotation,
+    destroy,
+    getAnnotationById,
+    getAnnotations
+  }
+
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './Annotorious';
+export * from './AnnotoriousManifold';
+export * from './AnnotoriousManifoldInstance';

package/src/synchronizeInstances.tsx

@@ -0,0 +1,11 @@
+import { Annotation, Annotator } from '@annotorious/core';
+
+export const synchronizeInstances = <I extends Annotation = Annotation, E extends unknown = Annotation>(
+  instances: Annotator<I, E>[]
+) => {
+
+  // TODO listen on all instances, broadcast changes on one instance to the others
+
+  return null;
+
+}

package/test/App.tsx

@@ -0,0 +1,50 @@
+import React, { useEffect } from 'react';
+import { OpenSeadragonAnnotator, OpenSeadragonViewer } from '@annotorious/react';
+import { Annotorious, useAnnotoriousManifold } from '../src';
+
+const ViewerTile = (props: { url: string }) => {
+
+  return (
+    <div className="viewer-tile">
+      <Annotorious source={props.url}>
+        <OpenSeadragonAnnotator>
+          <OpenSeadragonViewer
+            className="osd-container"
+            options={{
+              prefixUrl: 'https://cdn.jsdelivr.net/npm/openseadragon@3.1/build/openseadragon/images/', 
+              tileSources: {
+                type: 'image',
+                url: props.url
+              },
+              gestureSettingsMouse: {
+                clickToZoom: false
+              },
+              showRotationControl: true,
+              crossOriginPolicy: 'Anonymous'
+            }} />
+        </OpenSeadragonAnnotator>
+      </Annotorious>
+    </div>
+  )
+
+}
+
+export const App = () => {
+
+  const manifold = useAnnotoriousManifold();
+
+  useEffect(() => {
+    console.log('annotators', manifold.annotators);
+  }, [manifold.annotators]);
+
+  return (
+    <div className="container">
+      <ViewerTile url="33054-000002-0001.jpg" />
+      <ViewerTile url="33054-000002-0001.jpg" />
+      <ViewerTile url="33054-000002-0001.jpg" />
+      <ViewerTile url="33054-000002-0001.jpg" />
+    </div>
+  )
+
+}
+

package/test/index.css

@@ -0,0 +1,18 @@
+.container {
+  display: grid;
+  gap: 1.5vh;
+  grid-template-columns: 1fr 1fr;
+  height: 100%;
+  width: 100%;
+}
+
+.viewer-tile {
+  background-color: green;
+  height: 48vh;
+  position: relative;
+}
+
+.osd-container {
+  height: 100%;
+  width: 100%;
+}

package/test/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Annotorious React Manifold</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>

package/test/index.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import { AnnotoriousManifold } from '../src';
+import { App } from './App';
+
+import './index.css';
+
+const root = createRoot(document.getElementById('app') as Element);
+root.render(
+  <AnnotoriousManifold>
+    <App />
+  </AnnotoriousManifold>
+);

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "allowJs": false,
+    "allowSyntheticDefaultImports": true,
+    "baseUrl": ".",
+    "declaration": true,
+    "declarationDir": "types",
+    "declarationMap": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": false,
+    "jsx": "react-jsx",
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "noEmit": true,
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "target": "ESNext",
+    "useDefineForClassFields": true
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }],
+}

package/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "composite": true,
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+  },
+  "include": ["vite.config.ts", "package.json"]
+}

package/vite.config.js

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tsConfigPaths from 'vite-tsconfig-paths';
+import dts from 'vite-plugin-dts';
+
+import * as packageJson from './package.json';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tsConfigPaths(),
+    dts({
+      include: ['./src/'],
+      entryRoot: './src'
+    })
+  ],
+  server: {
+    open: '/test/index.html'
+  },
+  build: {
+    lib: {
+      entry: './src/index.ts',
+      formats: ['es'],
+      fileName: (format) => `annotorious-react-manifold.${format}.js`
+    },
+    rollupOptions: {
+      external: [
+        ...Object.keys(packageJson.peerDependencies)
+      ],
+      output: {
+        preserveModules: true,
+        assetFileNames: 'annotorious-react-manifold.[ext]',
+        globals: {
+          react: 'React'
+        }
+      }
+    },
+    sourcemap: true
+  }
+});