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

package/src/lifecycle/Lifecycle.ts

@@ -1,197 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

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

package/src/model/Annotation.ts

@@ -1,73 +0,0 @@
-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

@@ -1,161 +0,0 @@
-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/src/model/DrawingStyle.ts

@@ -1,19 +0,0 @@
-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;
-
-}

package/src/model/Filter.ts

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

package/src/model/FormatAdapter.ts

@@ -1,36 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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() }
-}

package/src/model/W3CAnnotation.ts

@@ -1,118 +0,0 @@
-import type { AnnotationBody } from './Annotation';
-
-export interface W3CAnnotation {
-
-  '@context': 'http://www.w3.org/ns/anno.jsonld';
-
-  type: 'Annotation';
-
-  id: string;
-
-  body: W3CAnnotationBody | W3CAnnotationBody[]
-
-  target: W3CAnnotationTarget | W3CAnnotationTarget[];
-
-  [key: string]: any;
-
-}
-
-export interface W3CAnnotationBody {
-
-  id?: string;
-
-  type?: string;
-
-  purpose?: string;
-
-  value?: string;
-
-  source?: string;
-
-  created?: Date;
-
-  creator?: {
-
-    type?: string;
-
-    id: string;
-
-    name?: string;
-
-  };
-
-}
-
-export interface W3CAnnotationTarget {
-
-  source: string;
-
-  selector?: W3CSelector | W3CSelector[];
-
-}
-
-export interface W3CSelector {
-
-  type: string;
-
-  conformsTo?: string;
-
-  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 parseW3CBodies = (
-  body: W3CAnnotationBody | W3CAnnotationBody[], 
-  annotationId: string
-): AnnotationBody[] => (Array.isArray(body) ? body : [body]).map(body => {
-
-  // Exctract properties that conform to the internal model, but keep custom props
-  const { id, type, purpose, value, created, creator, ...rest } = body;
-
-  // 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.  
-  return {
-    id: id || `temp-${hashCode(body)}`,
-    annotation: annotationId,
-    type,
-    purpose,
-    value,
-    created,
-    creator: creator ? 
-      typeof creator === 'object' ? { ...creator }: creator :
-      undefined,
-    ...rest
-  }
-
-});
-
-/** Serialization helper to remove core-specific fields from the annotation body **/
-export const serializeW3CBodies = (bodies: AnnotationBody[]): W3CAnnotationBody[] => 
-  bodies.map(b => {
-    const w3c = { ...b };
-    delete w3c.annotation;
-
-    if (w3c.id?.startsWith('temp-'))
-      delete w3c.id;
-  
-    return w3c;
-  });

package/src/presence/Appearance.ts

@@ -1,9 +0,0 @@
-export interface Appearance {
-
-  label: string;
-
-  color: string;
-
-  avatar?: string;
-
-}