@annotorious/core 3.0.0-pre-alpha-43

package/src/state/StoreObserver.ts

@@ -0,0 +1,149 @@
+import type { Annotation, AnnotationBody, AnnotationTarget } from '../model';
+
+/** Interface for listening to changes in the annotation store **/
+export interface StoreObserver<T extends Annotation> { 
+
+  onChange: { (event: StoreChangeEvent<T>): void };
+
+  options: StoreObserveOptions;
+
+}
+
+/** A change event fired when the store state changes **/
+export interface StoreChangeEvent<T extends Annotation> {
+
+  origin: Origin;
+
+  changes: ChangeSet<T>;
+
+  state: T[];
+
+}
+
+export interface ChangeSet<T extends Annotation> {
+
+  created?: T[];
+
+  deleted?: T[];
+
+  updated?: Update<T>[];
+
+}
+
+export interface Update<T extends Annotation> {
+
+  oldValue: T;
+
+  newValue: T;
+
+  bodiesCreated?: AnnotationBody[];
+
+  bodiesDeleted?: AnnotationBody[];
+
+  bodiesUpdated?: Array<{ oldBody: AnnotationBody, newBody: AnnotationBody }>;
+
+  targetUpdated?: { oldTarget: AnnotationTarget, newTarget: AnnotationTarget};
+
+}
+
+/** Options to control which events the observer wants to get notified about **/
+export interface StoreObserveOptions {
+
+  // Observe changes on targets, bodies or both?
+  ignore?: Ignore;
+
+  // Observe changes on one more specific annotations
+  annotations?: string | string[];
+
+  // Observer changes only for a specific origin
+  origin?: Origin
+
+}
+
+/** Allows the observer to ignore certain event types **/
+export enum Ignore { 
+
+  // Don't notify this observer for changes that involve bodies only
+  BODY_ONLY = 'BODY_ONLY',
+
+  // Don't notify for changes on targets only
+  TARGET_ONLY = 'TARGET_ONLY'
+
+}
+
+/** Allows the observer to listen only for events that originated locally or from a remote source **/
+export enum Origin { 
+  
+  LOCAL = 'LOCAL', 
+  
+  REMOTE = 'REMOTE' 
+
+}
+
+/** Tests if this observer should be notified about this event **/
+export const shouldNotify = <T extends Annotation>(observer: StoreObserver<T>, event: StoreChangeEvent<T>) => {
+  const { changes, origin } = event;
+
+  const isRelevantOrigin = 
+    !observer.options.origin || observer.options.origin === origin;
+
+  if (!isRelevantOrigin)
+    return false;
+
+  if (observer.options.ignore) {
+    const { ignore } = observer.options;
+
+    // Shorthand
+    const has = (arg: any[]) => arg?.length > 0;
+
+    const hasAnnotationChanges =
+      has(changes.created) || has(changes.deleted);
+
+    if (!hasAnnotationChanges) {
+      const hasBodyChanges =
+        changes.updated?.some(u => has(u.bodiesCreated) || has(u.bodiesDeleted) || has(u.bodiesUpdated));
+    
+      const hasTargetChanges = 
+        changes.updated?.some(u => u.targetUpdated);
+
+      if (ignore === Ignore.BODY_ONLY && hasBodyChanges && !hasTargetChanges)
+        return false;
+
+      if (ignore === Ignore.TARGET_ONLY && hasTargetChanges && !hasBodyChanges)
+        return false;
+    }
+  }
+
+  if (observer.options.annotations) {
+    // This observer has a filter set on specific annotations - check affected
+    const affectedAnnotations = new Set([
+      ...changes.created.map(a => a.id),
+      ...changes.deleted.map(a => a.id),
+      ...changes.updated.map(({ oldValue }) => oldValue.id)
+    ]);
+
+    const observed = Array.isArray(observer.options.annotations) ?
+      observer.options.annotations : [ observer.options.annotations ];
+
+    return Boolean(observed.find(id => affectedAnnotations.has(id)));
+  } else {
+    return true;
+  }
+
+}
+
+export const mergeChanges = <T extends Annotation>(event: StoreChangeEvent<T>, toMerge: StoreChangeEvent<T>) => {
+  if (event.origin !== toMerge.origin)
+    throw 'Cannot merge events from different origins';
+
+  return {
+    origin: toMerge.origin,
+    changes: {
+      // TODO filter created that were deleted in the same go
+      created: [...(event.changes.created || []), ...(toMerge.changes.created || []) ],
+      deleted: [...(event.changes.deleted || []), ...(toMerge.changes.deleted || []) ] 
+      // TODO merge updates
+    },
+    state: toMerge.state
+  }
+}

package/src/state/SvelteStore.ts

@@ -0,0 +1,38 @@
+import type { Annotation } from '../model';
+import { createStore } from './Store';
+import type { StoreChangeEvent } from './StoreObserver';
+
+type Subscriber = <T extends Annotation>(annotation: T[]) => void; 
+
+/** 
+ * A simple wrapper around the event-based store implementation
+ * that adds a Svelte shim, for use with the reactive '$' notation.
+ * Other frameworks might not actually need this. But it's pretty
+ * convenient for everyone using Svelte, as well as for the
+ * basic (Svelte-based) Annotorious standard implementation.
+ */
+export const createSvelteStore = <T extends Annotation>() => {
+
+  const store = createStore<T>();
+
+  const subscribe = (onChange: Subscriber) => {
+
+    // Register a store observer on behalf of the subscriber
+    const shim = (event: StoreChangeEvent<T>) => onChange(event.state);
+    store.observe(shim);
+
+    // Immediately call the subscriber function with the
+    // current store value, according to the Svelte contract.
+    // https://stackoverflow.com/questions/68220955/how-does-svelte-unsubscribe-actually-work
+    onChange(store.all());
+
+    // Return the unsubscribe function
+    return () => store.unobserve(shim);
+  }
+
+  return {
+    ...store,
+    subscribe
+  }
+
+}

package/src/state/Viewport.ts

@@ -0,0 +1,19 @@
+import { writable } from 'svelte/store';
+
+export type ViewportState = ReturnType<typeof createViewportState>;
+
+export const createViewportState = () => {
+
+  const { subscribe, set } = writable<string[]>([]);
+
+  let inViewport: string[] = [];
+
+  subscribe(updated => inViewport = updated);
+
+  return { 
+    get inViewport() { return [...inViewport] },
+    subscribe, 
+    set 
+  };
+
+}

package/src/state/index.ts

@@ -0,0 +1,6 @@
+export * from './Hover';
+export * from './Selection';
+export * from './Store';
+export * from './StoreObserver';
+export * from './SvelteStore';
+export * from './Viewport';

package/src/utils/bodyUtils.ts

@@ -0,0 +1,23 @@
+import { v4 as uuidv4 } from 'uuid';
+import type { Annotation, AnnotationBody, User } from '../model';
+
+export interface HasValue {
+
+  value: string;
+
+  [key:string]: any;
+
+}
+
+export const createBody = (
+  annotation: Annotation, 
+  payload: HasValue,
+  created?: Date,
+  creator?: User
+): AnnotationBody => ({
+  id: uuidv4(),
+  annotation: annotation.id,
+  created: created || new Date(),
+  creator,
+  ...payload
+});

package/src/utils/collaboratorUtils.ts

@@ -0,0 +1,19 @@
+import type { Annotation, User } from '../model';
+
+/**
+ * Returns all users listed as creators or updaters in any parts of this
+ * annotation.
+ */
+export const getCollaborators = (annotation: Annotation): User[] => {
+  const { creator, updatedBy } = annotation.target;
+
+  const bodyCollaborators = annotation.bodies.reduce((users, body) =>  (
+    [...users, body.creator, body.updatedBy]
+  ), [] as User[]);
+
+  return [
+    creator,
+    updatedBy,
+    ...bodyCollaborators
+  ].filter(u => u); // Remove undefined
+}

package/src/utils/diffAnnotations.ts

@@ -0,0 +1,33 @@
+import { dequal } from 'dequal/lite';
+import type { Update } from '../state';
+import type { Annotation } from '../model';
+
+const getAddedBodies = (oldValue: Annotation, newValue: Annotation) => {
+  const oldBodyIds = new Set(oldValue.bodies.map(b => b.id));
+  return newValue.bodies.filter(b => !oldBodyIds.has(b.id));
+}
+
+const getRemovedBodies = (oldValue: Annotation, newValue: Annotation) => {
+  const newBodyIds = new Set(newValue.bodies.map(b => b.id));
+  return oldValue.bodies.filter(b => !newBodyIds.has(b.id));
+}
+
+const getChangedBodies = (oldValue: Annotation, newValue: Annotation) => 
+  newValue.bodies
+    .map(newBody => {
+      const oldBody = oldValue.bodies.find(b => b.id === newBody.id);
+      return { newBody, oldBody: oldBody && !dequal(oldBody, newBody) ? oldBody : undefined }
+    })
+    .filter(({ oldBody }) => oldBody);
+
+const hasTargetChanged = (oldValue: Annotation, newValue: Annotation) => 
+  !dequal(oldValue.target, newValue.target);
+
+export const diffAnnotations = <T extends Annotation = Annotation>(oldValue: T, newValue: T): Update<T> => ({
+  oldValue, 
+  newValue,
+  bodiesCreated: getAddedBodies(oldValue, newValue),
+  bodiesDeleted: getRemovedBodies(oldValue, newValue),
+  bodiesUpdated: getChangedBodies(oldValue, newValue),
+  targetUpdated: hasTargetChanged(oldValue, newValue) ? { oldTarget: oldValue.target, newTarget: newValue.target } : undefined
+});

package/src/utils/index.ts

@@ -0,0 +1,4 @@
+export * from './bodyUtils';
+export * from './collaboratorUtils';
+export * from './diffAnnotations';
+

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />