@annotorious/core 3.0.0-rc.21 → 3.0.0-rc.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@annotorious/core",
-  "version": "3.0.0-rc.21",
+  "version": "3.0.0-rc.3",
   "description": "Annotorious core types and functions",
   "author": "Rainer Simon",
   "license": "BSD-3-Clause",
@@ -14,32 +14,29 @@
     "url": "https://github.com/annotorious/annotorious/issues"
   },
   "scripts": {
-    "build": "vite build",
+    "build": "echo 'Skipping build in @annotorious/core package'",
     "test": "vitest",
     "coverage": "vitest run --coverage"
   },
-  "main": "./dist/annotorious-core.es.js",
-  "module": "./dist/annotorious-core.es.js",
-  "types": "./dist/index.d.ts",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "files": [
-    "dist"
+    "src"
   ],
   "devDependencies": {
-    "@sveltejs/vite-plugin-svelte": "^3.0.2",
-    "@tsconfig/svelte": "^5.0.2",
-    "@types/deep-equal": "^1.0.4",
-    "@types/uuid": "^9.0.8",
-    "svelte": "^4.2.12",
-    "svelte-preprocess": "^5.1.3",
-    "typescript": "^5.3.3",
-    "vite": "^5.2.2",
-    "vite-plugin-dts": "^3.7.3",
-    "vitest": "^1.4.0"
+    "@tsconfig/svelte": "^3.0.0",
+    "@types/deep-equal": "^1.0.2",
+    "@types/uuid": "^9.0.4",
+    "svelte": "^3.59.2",
+    "typescript": "^4.9.5",
+    "vite": "^4.4.9",
+    "vite-plugin-dts": "^3.6.0",
+    "vitest": "^0.34.6"
   },
   "dependencies": {
     "dequal": "^2.0.3",
-    "nanoevents": "^9.0.0",
-    "nanoid": "^5.0.6",
+    "nanoevents": "^8.0.0",
+    "nanoid": "^5.0.1",
     "uuid": "^9.0.1"
   }
 }

package/{dist/index.d.ts → src/index.ts}

@@ -3,4 +3,3 @@ export * from './model';
 export * from './presence';
 export * from './state';
 export * from './utils';
-//# sourceMappingURL=index.d.ts.map

package/src/lifecycle/Lifecycle.ts

@@ -0,0 +1,197 @@
+import { dequal } from 'dequal/lite';
+import type { Annotation, FormatAdapter } from '../model';
+import { Origin } from '../state';
+import type { HoverState, SelectionState, Store, ViewportState } from '../state';
+import type { LifecycleEvents } from './LifecycleEvents';
+
+export type Lifecycle<I extends Annotation, E extends unknown> = 
+  ReturnType<typeof createLifecyleObserver<I, E>>;
+
+export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
+  store: Store<I>,
+  selectionState: SelectionState<I>, 
+  hoverState: HoverState<I>,
+  viewportState?: ViewportState,
+  adapter?: FormatAdapter<I, E>,
+  autoSave?: boolean
+) => {
+  const observers: Map<keyof LifecycleEvents, Function[]> = new Map();
+
+  // The currently selected annotations, in the state when they were selected 
+  let initialSelection: I[] = [];
+
+  let currentHover: string | undefined;
+
+  let idleTimeout: ReturnType<typeof setTimeout>;
+
+  const on = <T extends keyof LifecycleEvents>(event: T, callback: LifecycleEvents<E>[T]) => {
+    if (observers.has(event)) {
+      observers.get(event).push(callback);
+    } else {
+      observers.set(event, [callback]);
+    }
+  }
+
+  const off = <T extends keyof LifecycleEvents<E>>(event: T, callback: LifecycleEvents<E>[T]) => {
+    const callbacks = observers.get(event);
+    if (callbacks) {
+      const idx = callbacks.indexOf(callback);
+      if (idx > 0)
+        callbacks.splice(callbacks.indexOf(callback), 1);
+    }
+  }
+
+  const emit = (event: keyof LifecycleEvents<E>, arg0: I | I[], arg1?: I | PointerEvent) => {
+    if (observers.has(event)) {
+      setTimeout(() => {
+        observers.get(event).forEach(callback => { 
+          if (adapter) {
+            const serialized0 = Array.isArray(arg0) ? 
+              arg0.map(a => adapter.serialize(a)) : adapter.serialize(arg0);
+            
+            const serialized1: E | PointerEvent | undefined =
+              arg1 ? arg1 instanceof PointerEvent ? arg1 : adapter.serialize(arg1) : undefined;
+
+            callback(serialized0 as E & E[], serialized1); 
+          } else {
+            callback(arg0 as E & E[], arg1 as unknown as E);  
+          }
+        });
+      }, 1);
+    }
+  }
+
+  const onIdleUpdate = () => {
+    const { selected } = selectionState;
+
+    // User idle after activity - fire update events for selected
+    // annotations that changed
+    const updatedSelected = selected.map(({ id }) => store.getAnnotation(id));
+
+    updatedSelected.forEach(updated => {
+      const initial = initialSelection.find(a => a.id === updated.id);
+      if (!initial || !dequal(initial, updated)) {
+        emit('updateAnnotation', updated, initial);
+      }
+    });
+
+    initialSelection = initialSelection.map(initial => {
+      const updated = updatedSelected.find(({ id }) => id === initial.id);
+      return updated ? updated : initial
+    });
+  }
+
+  selectionState.subscribe(({ selected })=> {
+    if (initialSelection.length === 0 && selected.length === 0)
+      return;
+
+    if (initialSelection.length === 0 && selected.length > 0) {
+      // A new selection was made - store the editable annotation as initial state
+      initialSelection = selected.map(({ id }) => store.getAnnotation(id));
+    } else if (initialSelection.length > 0 && selected.length === 0) {
+      // Deselect!
+      initialSelection.forEach(initial => {
+        const updatedState = store.getAnnotation(initial.id);  
+        
+        if (updatedState && !dequal(updatedState, initial)) {
+          emit('updateAnnotation', updatedState, initial);
+        }
+      });
+
+      initialSelection = [];
+    } else {
+      // Changed selection
+      const initialIds = new Set(initialSelection.map(a => a.id));
+      const selectedIds = new Set(selected.map(({ id }) => id));
+
+      // Fire update events for deselected annotations that have changed
+      const deselected = initialSelection.filter(a => !selectedIds.has(a.id));
+      deselected.forEach(initial => {
+        const updatedState = store.getAnnotation(initial.id);
+
+        if (updatedState && !dequal(updatedState, initial))
+          emit('updateAnnotation', updatedState, initial);
+      });
+
+      initialSelection = [
+        // Remove annotations that were deselected
+        ...initialSelection.filter(a => selectedIds.has(a.id)),
+        // Add editable annotations that were selected
+        ...selected.filter(({ id }) => !initialIds.has(id))
+          .map(({ id }) => store.getAnnotation(id))
+      ];
+    }
+
+    emit('selectionChanged', initialSelection);
+  });
+
+  hoverState.subscribe(id => {
+    if (!currentHover && id) {
+      emit('mouseEnterAnnotation', store.getAnnotation(id));
+    } else if (currentHover && !id) {
+      emit('mouseLeaveAnnotation', store.getAnnotation(currentHover));
+    } else if (currentHover && id) {
+      emit('mouseLeaveAnnotation', store.getAnnotation(currentHover));
+      emit('mouseEnterAnnotation', store.getAnnotation(id));
+    }
+
+    currentHover = id;
+  });
+
+  viewportState?.subscribe(ids => 
+    emit('viewportIntersect', ids.map(store.getAnnotation)));
+
+  store.observe(event => {
+    // autoSave option triggers update events on idleness
+    if (autoSave) {
+      if (idleTimeout)
+        clearTimeout(idleTimeout);
+
+      idleTimeout = setTimeout(onIdleUpdate, 1000);
+    }
+
+    // Local CREATE and DELETE events are applied immediately
+    const { created, deleted } = event.changes;
+    created.forEach(a => emit('createAnnotation', a));
+    deleted.forEach(a => emit('deleteAnnotation', a));
+
+    // Updates are only applied immediately if they involve body changes
+    const updatesWithBody = event.changes.updated.filter(u => [
+      ...(u.bodiesCreated || []),
+      ...(u.bodiesDeleted || []),
+      ...(u.bodiesUpdated || [])
+    ].length > 0);
+
+    // Emit an update with the new annototation and the stored initial state
+    updatesWithBody.forEach(({ oldValue, newValue }) => {
+      const initial = initialSelection.find(a => a.id === oldValue.id) || oldValue;
+
+      // Record the update as the new last known state
+      initialSelection = initialSelection
+        .map(a => a.id === oldValue.id ? newValue : a);
+
+      emit('updateAnnotation', newValue, initial);
+    });
+  }, { origin: Origin.LOCAL });
+
+  // Track remote changes - these should update the initial state
+  store.observe(event => {
+    if (initialSelection) {
+      const selectedIds = new Set(initialSelection.map(a => a.id));
+
+      const relevantUpdates = event.changes.updated
+        .filter(({ newValue }) => selectedIds.has(newValue.id))
+        .map(({ newValue }) => newValue);
+
+      if (relevantUpdates.length > 0) {
+        initialSelection = initialSelection.map(selected => {
+          const updated = relevantUpdates.find(updated => updated.id === selected.id);
+          return updated ? updated : selected;
+        })
+      }
+    }
+  }, { origin: Origin.REMOTE });
+
+  return { on, off, emit }
+
+}

package/src/lifecycle/LifecycleEvents.ts

@@ -0,0 +1,21 @@
+import type { Annotation } from '../model';
+
+export interface LifecycleEvents<T extends unknown = Annotation> {
+
+  clickAnnotation: (annotation: T, originalEvent: PointerEvent) => void;
+
+  createAnnotation: (annotation: T) => void;
+
+  deleteAnnotation: (annotation: T) => void;
+
+  mouseEnterAnnotation: (annotation: T) => void;
+
+  mouseLeaveAnnotation: (annotation: T) => void;
+
+  selectionChanged: (annotation: T[]) => void;
+
+  updateAnnotation: (annotation: T, previous: T) => void;
+
+  viewportIntersect: (visible: T[]) => void;
+
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,2 @@
+export * from './Lifecycle';
+export * from './LifecycleEvents';

package/src/model/Annotation.ts

@@ -0,0 +1,73 @@
+import type { User } from './User';
+
+export interface Annotation {
+
+  id: string;
+
+  target: AnnotationTarget;
+
+  bodies: AnnotationBody[];
+
+  properties?: {
+
+    [key: string]: any;
+
+  }
+
+}
+
+export interface AnnotationTarget {
+
+  annotation: string;
+
+  selector: AbstractSelector;
+
+  creator?: User;
+
+  created?: Date;
+
+  updatedBy?: User;
+
+  updated?: Date;
+
+}
+
+export interface AbstractSelector { }
+
+export interface AnnotationBody {
+
+  id: string;
+
+  annotation: string;
+
+  type?: string;
+
+  purpose?: Purpose | string;
+
+  value?: string;
+
+  creator?: User;
+
+  created?: Date;
+
+  updatedBy?: User;
+
+  updated?: Date;
+
+}
+
+// Pre-defined purposes from https://www.w3.org/TR/annotation-model/#motivation-and-purpose
+export type Purpose = 
+  'assessing' |
+  'bookmarking' |
+  'classifying' |
+  'commenting' |
+  'describing' |
+  'editing' |
+  'highlighting' |
+  'identifying' |
+  'linking' |
+  'moderating' |
+  'questioning' |
+  'replying' |
+  'tagging';

package/src/model/Annotator.ts

@@ -0,0 +1,161 @@
+import type { Annotation } from './Annotation';
+import type { User } from './User';
+import type { PresenceProvider } from '../presence';
+import { Origin, type HoverState, type SelectionState, type Store, type UndoStack, type ViewportState } from '../state';
+import type { LifecycleEvents } from '../lifecycle';
+import { parseAll, type FormatAdapter } from './FormatAdapter';
+import type { DrawingStyle } from './DrawingStyle';
+import type { Filter } from './Filter';
+
+/**
+ * Base annotator interface.
+ * I ... internal core data model 
+ * E ... external adapted representation
+ */
+export interface Annotator<I extends Annotation = Annotation, E extends unknown = Annotation> {
+
+  addAnnotation(annotation: E): void;
+
+  clearAnnotations(): void;
+
+  destroy(): void;
+
+  getAnnotationById(id: string): E | undefined;
+
+  getAnnotations(): E[];
+
+  getUser(): User;
+
+  loadAnnotations(url: string): Promise<E[]>;
+
+  redo(): void;
+
+  removeAnnotation(arg: E | string): E;
+
+  setAnnotations(annotations: E[]): void;
+
+  setFilter(filter: Filter): void;
+
+  setPresenceProvider?(provider: PresenceProvider): void;
+
+  setSelected(arg?: string | string[]): void;
+
+  setStyle(arg: DrawingStyle | ((annotation: I) => DrawingStyle) | undefined): void;
+
+  setUser(user: User): void;
+
+  undo(): void;
+
+  updateAnnotation(annotation: E): 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;
+
+  state: AnnotatorState<I>;
+
+}
+
+export interface AnnotatorState<A extends Annotation> {
+
+  store: Store<A>;
+
+  selection: SelectionState<A>;
+
+  hover: HoverState<A>;
+
+  viewport: ViewportState;
+
+}
+
+export const createBaseAnnotator = <I extends Annotation, E extends unknown>(
+  store: Store<I>, 
+  undoStack: UndoStack,
+  adapter?: FormatAdapter<I, E>
+) => {
+
+  const addAnnotation = (annotation: E) => {
+    if (adapter) {
+      const { parsed, error } = adapter.parse(annotation);
+      if (parsed) {
+        store.addAnnotation(parsed, Origin.REMOTE);
+      } else {
+        console.error(error);
+      }
+    } else {
+      store.addAnnotation(annotation as unknown as I, Origin.REMOTE);
+    }
+  }
+
+  const clearAnnotations = () => store.clear();
+
+  const getAnnotationById = (id: string): E | undefined => {
+    const annotation = store.getAnnotation(id);
+    return (adapter && annotation) ?
+      adapter.serialize(annotation) as E : annotation as unknown as E;
+  }
+
+  const getAnnotations = () =>
+    (adapter ? store.all().map(adapter.serialize) : store.all()) as E[];
+
+  const loadAnnotations = (url: string) =>
+    fetch(url)
+      .then((response) => response.json())
+      .then((annotations) => {
+        setAnnotations(annotations);
+        return annotations;
+      });
+
+  const removeAnnotation = (arg: E | string): E => {
+    if (typeof arg === 'string') {
+      const annotation = store.getAnnotation(arg);
+      store.deleteAnnotation(arg);
+
+      return adapter ? adapter.serialize(annotation) : annotation as unknown as E;
+    } else {
+      const annotation = adapter ? adapter.parse(arg).parsed : (arg as unknown as I);
+      store.deleteAnnotation(annotation);
+      return arg;
+    }
+  }
+
+  const setAnnotations = (annotations: E[]) => {
+    if (adapter) {
+      const { parsed, failed } = parseAll(adapter)(annotations);
+
+      if (failed.length > 0)
+        console.warn(`Discarded ${failed.length} invalid annotations`, failed);
+
+      store.bulkAddAnnotation(parsed, true, Origin.REMOTE);
+    } else {
+      store.bulkAddAnnotation(annotations as unknown as I[], true, Origin.REMOTE);
+    }
+  }
+
+  const updateAnnotation = (updated: E): E => {
+    if (adapter) {
+      const crosswalked = adapter.parse(updated).parsed;
+      const previous = adapter.serialize(store.getAnnotation(crosswalked.id));
+      store.updateAnnotation(crosswalked);
+      return previous;
+    } else {
+      const previous = store.getAnnotation((updated as unknown as I).id);
+      store.updateAnnotation(updated as unknown as I);
+      return previous as unknown as E;
+    }
+  }
+
+  return { 
+    addAnnotation,
+    clearAnnotations,
+    getAnnotationById,
+    getAnnotations,
+    loadAnnotations,
+    redo: undoStack.redo,
+    removeAnnotation,
+    setAnnotations,
+    undo: undoStack.undo,
+    updateAnnotation
+  }
+
+}

package/{dist/model/DrawingStyle.d.ts → src/model/DrawingStyle.ts}

@@ -1,13 +1,19 @@
 type RGB = `rgb(${number}, ${number}, ${number})`;
+
 type RGBA = `rgba(${number}, ${number}, ${number}, ${number})`;
+
 type HEX = `#${string}`;
+
 export type Color = RGB | RGBA | HEX;
+
 export interface DrawingStyle {
-    fill?: Color;
-    fillOpacity?: number;
-    stroke?: Color;
-    strokeOpacity?: number;
-    strokeWidth?: number;
-}
-export {};
-//# sourceMappingURL=DrawingStyle.d.ts.map
+
+  fill?: Color;
+
+  fillOpacity?: number;
+
+  stroke?: Color;
+
+  strokeOpacity?: number;
+
+}

package/{dist/model/Filter.d.ts → src/model/Filter.ts}

@@ -1,3 +1,3 @@
 import type { Annotation } from './Annotation';
-export type Filter<T extends Annotation = Annotation> = (annotation: T) => boolean;
-//# sourceMappingURL=Filter.d.ts.map
+
+export type Filter<T extends Annotation = Annotation> = (annotation: T) => boolean;

package/src/model/FormatAdapter.ts

@@ -0,0 +1,36 @@
+import type { Annotation } from './Annotation';
+
+export interface FormatAdapter<A extends Annotation, T extends unknown> {
+
+  parse(serialized: T): ParseResult<A>;
+
+  serialize(core: A): T;
+
+}
+
+export interface ParseResult<A extends Annotation> {
+
+  parsed?: A;
+  
+  error?: Error;
+
+}
+
+export const serializeAll = 
+  <A extends Annotation, T extends unknown>(adapter: FormatAdapter<A, T>) =>
+    (annotations: A[]) => annotations.map(a => adapter.serialize(a));
+
+export const parseAll = 
+  <A extends Annotation, T extends unknown>(adapter: FormatAdapter<A, T>) =>
+    (serialized: T[]) => serialized.reduce((result, next) => {
+      const { parsed, error } = adapter.parse(next);
+
+      return error ? {
+        parsed: result.parsed,
+        failed: [...result.failed, next ]
+      } : {
+        parsed: [...result.parsed, parsed ],
+        failed: result.failed
+      }
+    }, { parsed: [], failed: [] });
+  

package/src/model/User.ts

@@ -0,0 +1,19 @@
+import { customAlphabet } from 'nanoid';
+
+export interface User {
+
+  id: string;
+
+  isGuest?: boolean;
+
+  name?: string;
+
+  avatar?: string;
+
+}
+
+export const createAnonymousGuest = () => {
+  const nanoid = customAlphabet('1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_', 20);
+  
+  return { isGuest: true, id: nanoid() }
+}