@annotorious/core 3.0.0-pre-alpha-49 → 3.0.0-pre-alpha-50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@annotorious/core",
-  "version": "3.0.0-pre-alpha-49",
+  "version": "3.0.0-pre-alpha-50",
   "description": "Annotorious core types and functions",
   "author": "Rainer Simon",
   "license": "BSD-3-Clause",

package/src/index.ts

@@ -2,4 +2,4 @@ export * from './lifecycle';
 export * from './model';
 export * from './presence';
 export * from './state';
-export * from './utils';
+export * from './utils';

package/src/lifecycle/Lifecycle.ts

@@ -12,9 +12,10 @@ export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
   selectionState: SelectionState<I>, 
   hoverState: HoverState<I>,
   viewportState?: ViewportState,
-  adapter?: FormatAdapter<I, E>
+  adapter?: FormatAdapter<I, E>,
+  autoSave?: boolean
 ) => {
-  const observers = new Map<string, LifecycleEvents<E>[keyof LifecycleEvents<E>][]>();
+  const observers: Map<keyof LifecycleEvents, Function[]> = new Map();
 
   // The currently selected annotations, in the state when they were selected 
   let initialSelection: I[] = [];
@@ -23,7 +24,7 @@ export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
 
   let idleTimeout: ReturnType<typeof setTimeout>;
 
-  const on = <T extends keyof LifecycleEvents<E>>(event: T, callback: LifecycleEvents<E>[T]) => {
+  const on = <T extends keyof LifecycleEvents>(event: T, callback: LifecycleEvents<E>[T]) => {
     if (observers.has(event)) {
       observers.get(event).push(callback);
     } else {
@@ -40,7 +41,7 @@ export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
     }
   }
 
-  const emit = (event: keyof LifecycleEvents<E>, arg0: I | I[], arg1: I = null) => {
+  const emit = (event: keyof LifecycleEvents<E>, arg0: I | I[], arg1?: I | PointerEvent) => {
     if (observers.has(event)) {
       setTimeout(() => {
         observers.get(event).forEach(callback => { 
@@ -48,7 +49,8 @@ export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
             const serialized0 = Array.isArray(arg0) ? 
               arg0.map(a => adapter.serialize(a)) : adapter.serialize(arg0);
             
-            const serialized1 = arg1 && adapter.serialize(arg1);
+            const serialized1: E | PointerEvent | undefined =
+              arg1 ? arg1 instanceof PointerEvent ? arg1 : adapter.serialize(arg1) : undefined;
 
             callback(serialized0 as E & E[], serialized1); 
           } else {
@@ -140,11 +142,13 @@ export const createLifecyleObserver = <I extends Annotation, E extends unknown>(
     emit('viewportIntersect', ids.map(store.getAnnotation)));
 
   store.observe(event => {
-    // Idleness update trigger
-    if (idleTimeout)
-      clearTimeout(idleTimeout);
+    // autoSave option triggers update events on idleness
+    if (autoSave) {
+      if (idleTimeout)
+        clearTimeout(idleTimeout);
 
-    idleTimeout = setTimeout(onIdleUpdate, 1000);
+      idleTimeout = setTimeout(onIdleUpdate, 1000);
+    }
 
     // Local CREATE and DELETE events are applied immediately
     const { created, deleted } = event.changes;

package/src/lifecycle/LifecycleEvents.ts

@@ -2,6 +2,8 @@ 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;

package/src/model/Annotator.ts

@@ -1,9 +1,10 @@
 import type { Annotation } from './Annotation';
 import type { User } from './User';
 import type { PresenceProvider } from '../presence';
-import type { HoverState, SelectionState, Store, ViewportState } from '../state';
+import { Origin, type HoverState, type SelectionState, type Store, type ViewportState } from '../state';
 import type { LifecycleEvents } from '../lifecycle';
 import type { Formatter } from './Formatter';
+import { parseAll, type FormatAdapter } from './FormatAdapter';
 
 /**
  * Base annotator interface.
@@ -14,6 +15,8 @@ export interface Annotator<I extends Annotation = Annotation, E extends unknown
 
   addAnnotation(annotation: E): void;
 
+  clearAnnotations(): void;
+
   getAnnotationById(id: string): E | undefined;
 
   getAnnotations(): E[];
@@ -22,14 +25,20 @@ export interface Annotator<I extends Annotation = Annotation, E extends unknown
 
   loadAnnotations(url: string): Promise<E[]>;
 
+  removeAnnotation(arg: E | string): E;
+
   setAnnotations(annotations: E[]): void;
 
   setFormatter(formatter: Formatter): void;
 
-  setUser(user: User): void;
-
   setPresenceProvider?(provider: PresenceProvider): void;
 
+  setSelected(arg?: string | string[]): void;
+
+  setUser(user: User): 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;
@@ -48,4 +57,93 @@ export interface AnnotatorState<A extends Annotation> {
 
   viewport: ViewportState;
 
+}
+
+export const createBaseAnnotator = <I extends Annotation, E extends unknown>(
+  store: Store<I>, 
+  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,
+    removeAnnotation,
+    setAnnotations,
+    updateAnnotation
+  }
+
 }

package/src/model/{w3c/W3CAnnotation.ts → W3CAnnotation.ts}

@@ -1,5 +1,4 @@
-import { v4 as uuidv4 } from 'uuid';
-import type { AnnotationBody } from '../Annotation';
+import type { AnnotationBody } from './Annotation';
 
 export interface W3CAnnotation {
 
@@ -19,6 +18,8 @@ export interface W3CAnnotation {
 
 export interface W3CAnnotationBody {
 
+  id?: string;
+
   type?: string;
 
   purpose?: string;
@@ -29,6 +30,8 @@ export interface W3CAnnotationBody {
 
   creator?: {
 
+    type?: string;
+
     id: string;
 
     name?: string;
@@ -54,14 +57,34 @@ export interface W3CSelector {
   value: string;
 }
 
+// https://stackoverflow.com/questions/6122571/simple-non-secure-hash-function-for-javascript
+const hashCode = (obj: Object): string => {
+  const str = JSON.stringify(obj);
+
+  let hash = 0;
+
+  for (let i = 0, len = str.length; i < len; i++) {
+      let chr = str.charCodeAt(i);
+      hash = (hash << 5) - hash + chr;
+      hash |= 0; // Convert to 32bit integer
+  }
+
+  return `${hash}`;
+}
+
 /**
  * Helper to crosswalk the W3C annotation body to a list of core AnnotationBody objects.
  */
-export const parseBodies = (
+export const parseW3CBodies = (
   body: W3CAnnotationBody | W3CAnnotationBody[], 
   annotationId: string
 ): AnnotationBody[] => (Array.isArray(body) ? body : [body]).map(b => ({
-  id: uuidv4(),
+  // The internal model strictly requires IDs. (Because multi-user scenarios
+  // will have problems without them.) In the W3C model, bodys *may* have IDs.
+  // We'll create ad-hoc IDs for bodies without IDs, but want to make sure that
+  // generating the ID is idempotent: the same body should always get the same ID.
+  // This will avoid unexpected results when checking for equality.  
+  id: b.id || hashCode(b),
   annotation: annotationId,
   type: b.type,
   purpose: b.purpose,
@@ -73,3 +96,11 @@ export const parseBodies = (
 }));
 
 
+export const serializeW3CBodies = (bodies: AnnotationBody[]): W3CAnnotationBody[] => 
+  bodies.map(b => {
+    const w3c = { ...b };
+    delete w3c.annotation;
+    delete w3c.id;
+    return w3c;
+  });
+

package/src/model/index.ts

@@ -1,6 +1,6 @@
-export * from './w3c';
 export * from './Annotation';
 export * from './Annotator';
 export * from './FormatAdapter';
 export * from './Formatter';
-export * from './User';
+export * from './User';
+export * from './W3CAnnotation';

package/src/state/Selection.ts

@@ -26,7 +26,7 @@ const EMPTY: Selection = { selected: [] };
 
 export const createSelectionState = <T extends Annotation>(
   store: Store<T>,
-  selectAction: PointerSelectAction | ((a: Annotation) => PointerSelectAction)
+  selectAction: PointerSelectAction | ((a: Annotation) => PointerSelectAction) = PointerSelectAction.EDIT
 ) => {
   const { subscribe, set } = writable<Selection>(EMPTY);
 

package/src/state/Store.ts

@@ -8,6 +8,8 @@ type AnnotationBodyIdentifier = { id: string, annotation: string };
 
 export type Store<T extends Annotation> = ReturnType<typeof createStore<T>>;
 
+const isAnnotation = <T extends Annotation>(arg: any): arg is T => arg.id !== undefined;
+
 export const createStore = <T extends Annotation>() => {
 
   const annotationIndex = new Map<string, T>();
@@ -55,17 +57,30 @@ export const createStore = <T extends Annotation>() => {
     }
   }
 
-  const updateAnnotation = (annotation: T, origin = Origin.LOCAL) => {
-    const oldValue = annotationIndex.get(annotation.id);
+  const updateAnnotation = (arg1: string | T, arg2: T | Origin = Origin.LOCAL, arg3 = Origin.LOCAL) => {
+    const origin: Origin = isAnnotation(arg2) ? arg3 : arg2;
+
+    const updated: T = typeof arg1 === 'string' ? arg2 as T : arg1;
+
+    const oldId: string = typeof arg1 === 'string' ? arg1 : arg1.id;
+    const oldValue = annotationIndex.get(oldId);
 
     if (oldValue) {
-      const update: Update<T> = diffAnnotations(oldValue, annotation);
+      const update: Update<T> = diffAnnotations(oldValue, updated);
 
-      annotationIndex.set(annotation.id, annotation);
+      if (oldId === updated.id) {
+        annotationIndex.set(oldId, updated);
+      } else {
+        annotationIndex.delete(oldId);
+        annotationIndex.set(updated.id, updated);
+      }
+
+      oldValue.bodies.forEach(b => bodyIndex.delete(b.id));
+      updated.bodies.forEach(b => bodyIndex.set(b.id, updated.id));
 
       emit(origin, { updated: [update] })
     } else {
-      throw Error(`Cannot update annotation ${annotation.id} - does not exist`);
+      throw Error(`Cannot update annotation ${oldId} - does not exist`);
     }
   }
 
@@ -93,6 +108,11 @@ export const createStore = <T extends Annotation>() => {
 
   const all = () => [...annotationIndex.values()];
 
+  const clear = () => { 
+    annotationIndex.clear();
+    bodyIndex.clear();
+  }
+
   const bulkAddAnnotation = (annotations: T[], replace = true, origin = Origin.LOCAL) => {
     if (replace) {
       // Delete existing first
@@ -218,6 +238,11 @@ export const createStore = <T extends Annotation>() => {
 
       annotationIndex.set(oldAnnotation.id, newAnnotation);
 
+      if (oldBody.id !== newBody.id) {
+        bodyIndex.delete(oldBody.id);
+        bodyIndex.set(newBody.id, newAnnotation.id);
+      }
+
       return {
         oldValue: oldAnnotation, 
         newValue: newAnnotation,
@@ -283,6 +308,7 @@ export const createStore = <T extends Annotation>() => {
     bulkDeleteAnnotation,
     bulkUpdateBodies,
     bulkUpdateTargets,
+    clear,
     deleteAnnotation,
     deleteBody,
     getAnnotation,

package/src/model/w3c/index.ts

@@ -1 +0,0 @@
-export * from './W3CAnnotation';