@annotorious/core 3.0.0-pre-alpha-43

package/README.md

@@ -0,0 +1,3 @@
+# @annotorious/core
+
+Annotorious core models and helpers.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@annotorious/core",
+  "version": "3.0.0-pre-alpha-43",
+  "description": "Experimental rewrite of Annotorious",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "echo 'Skipping build in @annotorious/formats package'",
+    "test": "vitest",
+    "coverage": "vitest run --coverage"
+  },
+  "author": "Rainer Simon",
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@tsconfig/svelte": "^3.0.0",
+    "@types/deep-equal": "^1.0.1",
+    "@types/uuid": "^9.0.1",
+    "svelte": "^3.58.0",
+    "typescript": "^4.9.5",
+    "vite": "^4.2.1",
+    "vite-plugin-dts": "^2.3.0",
+    "vitest": "^0.29.3"
+  },
+  "dependencies": {
+    "dequal": "^2.0.3",
+    "nanoevents": "^7.0.1",
+    "nanoid": "^4.0.1",
+    "uuid": "^9.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './lifecycle';
+export * from './model';
+export * from './presence';
+export * from './state';
+export * from './utils';

package/src/lifecycle/Lifecycle.ts

@@ -0,0 +1,192 @@
+import { dequal } from 'dequal/lite';
+import type { Annotation, FormatAdapter, W3CAnnotation } from '../model';
+import { Origin } from '../state';
+import type { HoverState, SelectionState, Store, ViewportState } from '../state';
+import type { LifecycleEvents } from './LifecycleEvents';
+
+export type Lifecycle<T extends Annotation> = ReturnType<typeof createLifecyleObserver<T>>;
+
+export const createLifecyleObserver = <T extends Annotation, A extends unknown = W3CAnnotation>(
+  store: Store<T>,
+  selectionState: SelectionState<T>, 
+  hoverState: HoverState<T>,
+  viewportState?: ViewportState,
+  adapter?: FormatAdapter<T, A>
+) => {
+  const observers = new Map<string, LifecycleEvents<A>[keyof LifecycleEvents<T>][]>();
+
+  // The currently selected annotations, in the state when they were selected 
+  let initialSelection: T[] = [];
+
+  let currentHover: string | undefined;
+
+  let idleTimeout: ReturnType<typeof setTimeout>;
+
+  const on = <E extends keyof LifecycleEvents<T>>(event: E, callback: LifecycleEvents<A>[E]) => {
+    if (observers.has(event)) {
+      observers.get(event).push(callback);
+    } else {
+      observers.set(event, [callback]);
+    }
+  }
+
+  const off = <E extends keyof LifecycleEvents<T>>(event: E, callback: LifecycleEvents<A>[E]) => {
+    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<T>, arg0: T | T[], arg1: T = null) => {
+    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 = arg1 && adapter.serialize(arg1);
+
+            callback(serialized0 as A & A[], serialized1); 
+          } else {
+            callback(arg0 as A & A[], arg1 as unknown as A);  
+          }
+        });
+      }, 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 => {
+    // Idleness update trigger
+    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,19 @@
+import type { Annotation } from '../model';
+
+export interface LifecycleEvents<T extends unknown = Annotation> {
+
+  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/FormatAdapter.ts

@@ -0,0 +1,36 @@
+import type { Annotation } from './core/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/core/Annotation.ts

@@ -0,0 +1,57 @@
+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?: string;
+
+  value: string;
+
+  creator?: User;
+
+  created?: Date;
+
+  updatedBy?: User;
+
+  updated?: Date;
+
+}

package/src/model/core/Annotator.ts

@@ -0,0 +1,47 @@
+import type { Annotation } from './Annotation';
+import type { User } from './User';
+import type { PresenceProvider } from '../../presence';
+import type { HoverState, SelectionState, Store, ViewportState } from '../../state';
+import type { LifecycleEvents } from '../../lifecycle';
+import type { W3CAnnotation } from '../w3c';
+import type { Formatter } from './Formatter';
+
+export interface Annotator<A extends Annotation = Annotation, T extends unknown = W3CAnnotation> {
+
+  addAnnotation(annotation: T): void;
+
+  getAnnotationById(id: string): T | undefined;
+
+  getAnnotations(): T[];
+
+  getUser(): User;
+
+  loadAnnotations(url: string): Promise<T[]>;
+
+  setAnnotations(annotations: T[]): void;
+
+  setFormatter(formatter: Formatter): void;
+
+  setUser(user: User): void;
+
+  setPresenceProvider?(provider: PresenceProvider): void;
+
+  on<E extends keyof LifecycleEvents<T>>(event: E, callback: LifecycleEvents<T>[E]): void;
+
+  off<E extends keyof LifecycleEvents<T>>(event: E, callback: LifecycleEvents<T>[E]): void;
+
+  state: AnnotatorState<A>;
+
+}
+
+export interface AnnotatorState<A extends Annotation> {
+
+  store: Store<A>;
+
+  selection: SelectionState<A>;
+
+  hover: HoverState<A>;
+
+  viewport?: ViewportState;
+
+}

package/src/model/core/Formatter.ts

@@ -0,0 +1,19 @@
+import type { Annotation } from './Annotation';
+
+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;
+
+}
+
+export type Formatter = <T extends Annotation = Annotation>(annotation: T, isSelected?: boolean) => DrawingStyle;

package/src/model/core/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() }
+}

package/src/model/core/index.ts

@@ -0,0 +1,4 @@
+export * from './Annotation';
+export * from './Annotator';
+export * from './Formatter';
+export * from './User';

package/src/model/index.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './w3c';
+export * from './FormatAdapter';

package/src/model/w3c/W3CAnnotation.ts

@@ -0,0 +1,73 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { AnnotationBody } from '../core';
+
+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 {
+
+  type?: string;
+
+  purpose?: string;
+
+  value?: string;
+
+  created?: Date;
+
+  creator?: {
+
+    id: string;
+
+    name?: string;
+
+  };
+
+}
+
+export interface W3CAnnotationTarget {
+
+  source: string;
+
+  selector?: W3CSelector | W3CSelector[];
+
+}
+
+export interface W3CSelector {
+
+  type: string;
+
+  conformsTo?: string;
+
+  value: string;
+}
+
+/**
+ * Helper to crosswalk the W3C annotation body to a list of core AnnotationBody objects.
+ */
+export const parseBodies = (
+  body: W3CAnnotationBody | W3CAnnotationBody[], 
+  annotationId: string
+): AnnotationBody[] => (Array.isArray(body) ? body : [body]).map(b => ({
+  id: uuidv4(),
+  annotation: annotationId,
+  type: b.type,
+  purpose: b.purpose,
+  value: b.value,
+  created: b.created,
+  creator: b.creator ? { ...b.creator } : undefined
+}));
+
+

package/src/model/w3c/index.ts

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

package/src/presence/Appearance.ts

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

package/src/presence/AppearanceProvider.ts

@@ -0,0 +1,53 @@
+import type { User } from '../model';
+import type { Appearance } from './Appearance';
+import type { PresentUser } from './PresentUser';
+import { DEFAULT_PALETTE } from './ColorPalette';
+
+export interface AppearanceProvider {
+
+  addUser(presenceKey: string, user: User): Appearance;
+
+  removeUser(user: PresentUser): void;
+
+}
+
+export const defaultColorProvider = () => {
+
+  const unassignedColors = [...DEFAULT_PALETTE];
+
+  const assignRandomColor = () => {
+    const rnd = Math.floor(Math.random() * unassignedColors.length);
+    const color = unassignedColors[rnd];
+
+    unassignedColors.splice(rnd, 1);
+
+    return color;
+  }
+
+  const releaseColor = (color: string) =>
+    unassignedColors.push(color);
+
+  return { assignRandomColor, releaseColor };
+
+}
+
+export const createDefaultAppearenceProvider = () => {
+
+  const colorProvider = defaultColorProvider();
+
+  const addUser = (presenceKey: string, user: User): Appearance => {
+    const color = colorProvider.assignRandomColor();
+
+    return {
+      label: user.name || user.id,
+      avatar: user.avatar,
+      color
+    };
+  }
+
+  const removeUser = (user: PresentUser) =>
+    colorProvider.releaseColor(user.appearance.color);
+
+  return { addUser, removeUser }
+  
+}

package/src/presence/ColorPalette.ts

@@ -0,0 +1,14 @@
+// SEABORN_BRIGHT
+export const DEFAULT_PALETTE: Palette = [
+  '#ff7c00', // orange
+  '#1ac938', // green
+  '#e8000b', // red
+  '#8b2be2', // purple
+  '#9f4800', // brown
+  '#f14cc1', // pink
+  '#ffc400', // khaki
+  '#00d7ff', // cyan
+  '#023eff'  // blue
+];
+
+export type Palette = string[];

package/src/presence/PresenceEvents.ts

@@ -0,0 +1,9 @@
+import type { PresentUser } from './PresentUser';
+
+export interface PresenceEvents {
+
+  presence: (users: PresentUser[]) => void;
+
+  selectionChange: (from: PresentUser, selection: string[] | null) => void;
+
+}

package/src/presence/PresenceProvider.ts

@@ -0,0 +1,7 @@
+import type { PresenceEvents } from './PresenceEvents';
+
+export interface PresenceProvider {
+
+  on<E extends keyof PresenceEvents>(event: E, callback: PresenceEvents[E]): void;
+
+}