@recogito/text-annotator 4.1.1 → 4.2.1

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export * from './utils/highlight';
 export * from './selection-handler';
 export * from './text-annotator';
 export * from './text-annotator-options';
-export type { Annotation, AnnotationBody, AnnotationTarget, Annotator, AnnotatorState, Color, Filter, FormatAdapter, HoverState, Selection, SelectionState, Store, StoreChangeEvent, StoreObserver, ParseResult, User, UserSelectActionExpression, ViewportState, W3CAnnotation, W3CAnnotationBody, W3CAnnotationTarget } from '@annotorious/core';
+export type { Annotation, AnnotationBody, AnnotationTarget, Annotator, AnnotatorState, Filter, FormatAdapter, HoverState, Selection, SelectionState, Store, StoreChangeEvent, StoreObserver, ParseResult, User, UserSelectActionExpression, ViewportState, W3CAnnotation, W3CAnnotationBody, W3CAnnotationTarget } from '@annotorious/core';
 export { createBody, Origin, UserSelectAction } from '@annotorious/core';

package/dist/model/core/text-annotation.d.ts

@@ -1,18 +1,14 @@
 import type { Annotation, AnnotationTarget } from '@annotorious/core';
-export interface TextAnnotation extends Annotation {
-    target: TextAnnotationTarget;
-}
-export interface TextAnnotationTarget extends AnnotationTarget {
-    selector: TextSelector[];
-}
-export interface TextSelector {
-    id?: string;
-    quote: string;
-    start: number;
-    end: number;
-    range: Range;
-    offsetReference?: HTMLElement;
-}
+/**
+ * The Text Annotator model is becoming slightly complex. But it seems
+ * justified since we need to dealing with two orthogonal issues:
+ *
+ * - Annotations come in "revived" and "unrevived" states (with or without
+ *   resolved DOM elements: Range and offset element)
+ * - Annotations can be "plain" HTML/text annotations with `start` and `end`
+ *   character offset fields, or annotations from extensions (TEI/XML, PDF)
+ *   which handle the serializable anchoring differently (XPath, pages)
+ */
 export interface TextAnnotationLike extends Annotation {
     target: TextAnnotationTargetLike;
 }
@@ -22,6 +18,39 @@ export interface TextAnnotationTargetLike extends AnnotationTarget {
 export interface TextSelectorLike {
     id?: string;
     quote: string;
-    range: Range;
     offsetReference?: HTMLElement;
 }
+export interface RevivedTextSelectorLike extends TextSelectorLike {
+    range: Range;
+}
+/**
+ * Core classes - this is what most parts of the core deal with:
+ * a TextAnnotationLike with all-revived selectors
+ */
+export type RevivedTextAnnotationLike<T extends TextAnnotationLike = TextAnnotationLike> = T & {
+    target: RevivedTextAnnotationTargetLike<T['target']>;
+};
+export type RevivedTextAnnotationTargetLike<T extends TextAnnotationTargetLike = TextAnnotationTargetLike> = Omit<T, 'selector'> & {
+    selector: RevivedTextSelectorLike[];
+};
+/**
+ * Default specialization of TextAnnotationLike
+ */
+export interface TextAnnotation extends TextAnnotationLike {
+    target: TextAnnotationTarget;
+}
+export interface TextAnnotationTarget extends TextAnnotationTargetLike {
+    selector: TextSelector[];
+}
+export interface TextSelector extends TextSelectorLike {
+    start: number;
+    end: number;
+}
+export type RevivedTextSelector = TextSelector & RevivedTextSelectorLike;
+/**
+ * Utility type guards
+ */
+export declare const isRevivedAnnotation: (annotation: TextAnnotationLike) => annotation is RevivedTextAnnotationLike;
+export declare const isRevivedTarget: (target: TextAnnotationTargetLike) => target is RevivedTextAnnotationTargetLike;
+export declare function isRevived(selector: TextSelectorLike): selector is RevivedTextSelectorLike;
+export declare function isRevived(selectors: TextSelectorLike[]): selectors is RevivedTextSelectorLike[];

package/dist/model/w3c/w3c-text-format-adapter.d.ts

@@ -1,12 +1,12 @@
-import type { TextAnnotation } from '../core';
+import type { TextAnnotationLike } from '../core';
 import type { W3CTextAnnotation } from './';
 import { type FormatAdapter, type ParseResult } from '@annotorious/core';
-export type W3CTextFormatAdapter<I extends TextAnnotation = TextAnnotation, E extends W3CTextAnnotation = W3CTextAnnotation> = FormatAdapter<I, E>;
+export type W3CTextFormatAdapter<I extends TextAnnotationLike = TextAnnotationLike, E extends W3CTextAnnotation = W3CTextAnnotation> = FormatAdapter<I, E>;
 /**
  * @param source - the IRI of the annotated content
  * @param container - the HTML container of the annotated content,
  *                    Required to locate the content's `range` within the DOM
  */
-export declare const W3CTextFormat: <I extends TextAnnotation = TextAnnotation, E extends W3CTextAnnotation = W3CTextAnnotation>(source: string, container?: HTMLElement) => W3CTextFormatAdapter<I, E>;
-export declare const parseW3CTextAnnotation: <I extends TextAnnotation = TextAnnotation, E extends W3CTextAnnotation = W3CTextAnnotation>(annotation: E) => ParseResult<I>;
-export declare const serializeW3CTextAnnotation: <I extends TextAnnotation = TextAnnotation, E extends W3CTextAnnotation = W3CTextAnnotation>(annotation: I, source: string, container?: HTMLElement) => E;
+export declare const W3CTextFormat: <I extends TextAnnotationLike = TextAnnotationLike, E extends W3CTextAnnotation = W3CTextAnnotation>(source: string, container?: HTMLElement) => W3CTextFormatAdapter<I, E>;
+export declare const parseW3CTextAnnotation: <I extends TextAnnotationLike = TextAnnotationLike, E extends W3CTextAnnotation = W3CTextAnnotation>(annotation: E) => ParseResult<I>;
+export declare const serializeW3CTextAnnotation: <I extends TextAnnotationLike = TextAnnotationLike, E extends W3CTextAnnotation = W3CTextAnnotation>(annotation: I, source: string, container?: HTMLElement) => E;

package/dist/rendering/base-renderer.d.ts

@@ -10,7 +10,7 @@ export interface Renderer {
     destroy(): void;
     on: <E extends keyof RendererEvents>(event: E, callback: RendererEvents[E]) => Unsubscribe;
     redraw(force?: boolean): void;
-    setStyle(style?: HighlightStyleExpression, id?: string): void;
+    setStyle<I extends TextAnnotationLike = TextAnnotationLike>(style?: HighlightStyleExpression<I>, id?: string): void;
     setFilter(filter?: Filter<any>): void;
     setVisible(visible: boolean): void;
 }

package/dist/rendering/highlight-style.d.ts

@@ -1,13 +1,16 @@
-import type { AnnotationState, Color, DrawingStyle } from '@annotorious/core';
+import type { AnnotationState } from '@annotorious/core';
 import type { TextAnnotationLike } from '../model';
 import type { Highlight } from './';
-export interface HighlightStyle extends Pick<DrawingStyle, 'fill' | 'fillOpacity'> {
+export type CSSColor = string;
+export interface HighlightStyle {
+    fill?: CSSColor;
+    fillOpacity?: number;
     underlineStyle?: string;
-    underlineColor?: Color;
+    underlineColor?: CSSColor;
     underlineOffset?: number;
     underlineThickness?: number;
 }
-export type HighlightStyleExpression = HighlightStyle | (<I extends TextAnnotationLike = TextAnnotationLike>(annotation: I, state: AnnotationState, zIndex?: number) => HighlightStyle | undefined);
+export type HighlightStyleExpression<I extends TextAnnotationLike = TextAnnotationLike> = HighlightStyle | ((annotation: I, state: AnnotationState, zIndex?: number) => HighlightStyle | undefined);
 export declare const DEFAULT_STYLE: HighlightStyle;
 export declare const DEFAULT_SELECTED_STYLE: HighlightStyle;
 export declare const getBackgroundColor: (style?: HighlightStyle) => string;

package/dist/rendering/highlight.d.ts

@@ -1,6 +1,6 @@
 import type { AnnotationState } from '@annotorious/core';
-import type { TextAnnotationLike } from '../model';
+import type { RevivedTextAnnotationLike } from '../model';
 import type { AnnotationRects } from '../state';
-export interface Highlight extends AnnotationRects<TextAnnotationLike> {
+export interface Highlight extends AnnotationRects<RevivedTextAnnotationLike> {
     state: AnnotationState;
 }

package/dist/rendering/renderer-css-highlight/css-highlight-renderer.d.ts

@@ -1,7 +1,7 @@
-import type { TextAnnotation } from '../../model';
+import type { TextAnnotationLike } from '../../model';
 import { type Painter, type RendererFactory } from '../';
 /**
  * EXPERIMENTAL!
  */
 export declare const createCSSHighlightPainter: () => Painter;
-export declare const createCSSHighlightRenderer: RendererFactory<TextAnnotation>;
+export declare const createCSSHighlightRenderer: RendererFactory<TextAnnotationLike>;

package/dist/selection-handler.d.ts

@@ -1,9 +1,9 @@
 import type { Filter, Lifecycle, User } from '@annotorious/core';
 import type { TextAnnotatorState } from './state';
-import type { TextAnnotation } from './model';
+import type { RevivedTextAnnotationLike, TextAnnotationLike } from './model';
 import type { AnnotatingMode } from './text-annotator';
 import type { TextAnnotatorOptions } from './text-annotator-options';
-export declare const createSelectionHandler: <T extends TextAnnotation>(container: HTMLElement, state: TextAnnotatorState<TextAnnotation, any>, lifecycle: Lifecycle<TextAnnotation, any>, options: TextAnnotatorOptions<TextAnnotation, any>) => {
+export declare const createSelectionHandler: (container: HTMLElement, state: TextAnnotatorState<RevivedTextAnnotationLike, any>, lifecycle: Lifecycle<TextAnnotationLike, any>, options: TextAnnotatorOptions<TextAnnotationLike, any>) => {
     destroy: () => void;
     setFilter: (filter?: Filter<any>) => Filter<any>;
     setUser: (user?: User) => User;

package/dist/state/spatial-tree.d.ts

@@ -1,7 +1,7 @@
 import type { Store } from '@annotorious/core';
 import { type Unsubscribe } from 'nanoevents';
-import type { TextAnnotationLike, TextAnnotationTarget } from '../model';
 import type { AnnotationRects } from '../state/text-annotation-store';
+import type { RevivedTextAnnotationLike, RevivedTextSelectorLike, TextAnnotationLike, TextAnnotationTargetLike } from '../model';
 interface IndexedHighlightRect {
     minX: number;
     minY: number;
@@ -15,19 +15,19 @@ interface IndexedHighlightRect {
 export interface SpatialTreeEvents {
     recalculate(): void;
 }
-export declare const createSpatialTree: <T extends TextAnnotationLike>(store: Store<T>, container: HTMLElement, hMergeTolerance?: number, vMergeTolerance?: number) => {
+export declare const createSpatialTree: <T extends TextAnnotationLike>(store: Store<T>, container: HTMLElement, hMergeTolerance?: number, vMergeTolerance?: number, selectorReviveFn?: (arg: T["target"]["selector"][number], container: HTMLElement) => RevivedTextSelectorLike) => {
     all: () => IndexedHighlightRect[][];
     clear: () => void;
     getAt: (x: number, y: number, all?: boolean) => string[];
     getAnnotationBounds: (id: string) => DOMRect | undefined;
     getAnnotationRects: (id: string) => DOMRect[];
-    getIntersecting: (minX: number, minY: number, maxX: number, maxY: number) => AnnotationRects<T>[];
-    insert: (target: TextAnnotationTarget) => void;
+    getIntersecting: (minX: number, minY: number, maxX: number, maxY: number) => AnnotationRects<RevivedTextAnnotationLike<T>>[];
+    insert: (target: TextAnnotationTargetLike) => void;
     recalculate: () => void;
-    remove: (target: TextAnnotationTarget) => void;
-    set: (targets: TextAnnotationTarget[], replace?: boolean) => void;
+    remove: (target: TextAnnotationTargetLike) => void;
+    set: (targets: TextAnnotationTargetLike[], replace?: boolean) => void;
     size: () => number;
-    update: (target: TextAnnotationTarget) => void;
+    update: (target: TextAnnotationTargetLike) => void;
     on: <E extends keyof SpatialTreeEvents>(event: E, callback: SpatialTreeEvents[E]) => Unsubscribe;
 };
 export {};

package/dist/state/text-annotation-store.d.ts

@@ -1,6 +1,6 @@
 import type { Unsubscribe } from 'nanoevents';
 import type { Filter, Origin, Store } from '@annotorious/core';
-import type { TextAnnotation, TextAnnotationLike } from '../model';
+import type { RevivedTextAnnotationLike, TextAnnotation, TextAnnotationLike } from '../model';
 import type { SpatialTreeEvents } from '../state/spatial-tree';
 export interface TextAnnotationStore<T extends TextAnnotationLike = TextAnnotation> extends Omit<Store<T>, 'addAnnotation' | 'bulkAddAnnotations' | 'bulkUpsertAnnotations'> {
     addAnnotation(annotation: T, origin?: Origin): boolean;
@@ -9,10 +9,10 @@ export interface TextAnnotationStore<T extends TextAnnotationLike = TextAnnotati
     getAnnotationRects(id: string): DOMRect[];
     getAnnotationBounds(id: string): DOMRect | undefined;
     getAnnotationRects(id: string): DOMRect[];
-    getAt(x: number, y: number, all: true, filter?: Filter): T[] | undefined;
-    getAt(x: number, y: number, all: false, filter?: Filter): T | undefined;
-    getAt(x: number, y: number, all?: boolean, filter?: Filter): T | T[] | undefined;
-    getIntersecting(minX: number, minY: number, maxX: number, maxY: number): AnnotationRects<T>[];
+    getAt(x: number, y: number, all: true, filter?: Filter): RevivedTextAnnotationLike<T>[] | undefined;
+    getAt(x: number, y: number, all: false, filter?: Filter): RevivedTextAnnotationLike<T> | undefined;
+    getAt(x: number, y: number, all?: boolean, filter?: Filter): RevivedTextAnnotationLike<T> | RevivedTextAnnotationLike<T>[] | undefined;
+    getIntersecting(minX: number, minY: number, maxX: number, maxY: number): AnnotationRects<RevivedTextAnnotationLike<T>>[];
     recalculatePositions(): void;
     onRecalculatePositions(callback: SpatialTreeEvents['recalculate']): Unsubscribe;
 }

package/dist/state/text-annotator-state.d.ts

@@ -3,10 +3,10 @@ import type { AnnotatorState, SelectionState, HoverState } from '@annotorious/co
 import type { TextAnnotation, TextAnnotationLike } from '../model';
 import type { TextAnnotationStore } from '../state/text-annotation-store';
 import type { TextAnnotatorOptions } from '../text-annotator-options';
-export interface TextAnnotatorState<I extends TextAnnotationLike = TextAnnotation, E extends unknown = TextAnnotation> extends Omit<AnnotatorState<I, E>, 'store'> {
+export interface TextAnnotatorState<I extends TextAnnotationLike = TextAnnotationLike, E extends unknown = TextAnnotation> extends Omit<AnnotatorState<I, E>, 'store'> {
     store: TextAnnotationStore<I>;
     selection: SelectionState<I, E>;
     hover: HoverState<I>;
     viewport: ViewportState;
 }
-export declare const createTextAnnotatorState: <I extends TextAnnotation = TextAnnotation, E extends unknown = TextAnnotation>(container: HTMLElement, opts: TextAnnotatorOptions<I, E>) => TextAnnotatorState<I, E>;
+export declare const createTextAnnotatorState: <I extends TextAnnotationLike = TextAnnotation, E extends unknown = TextAnnotation>(container: HTMLElement, opts: TextAnnotatorOptions<I, E>) => TextAnnotatorState<I, E>;

package/dist/text-annotator-options.d.ts

@@ -1,10 +1,15 @@
 import type { FormatAdapter, UserSelectActionExpression, User } from '@annotorious/core';
 import type { HighlightStyleExpression, RendererFactory } from './rendering';
-import type { TextAnnotation, TextAnnotationLike } from './model';
+import type { RevivedTextSelectorLike, TextAnnotation, TextAnnotationLike } from './model';
 export interface TextAnnotatorOptions<I extends TextAnnotationLike = TextAnnotation, E extends unknown = TextAnnotation> {
     adapter?: FormatAdapter<I, E>;
     allowModifierSelect?: boolean;
     annotatingEnabled?: boolean;
+    /**
+     * Custom function that turns a stored selector into a revived one (with a live DOM `range`).
+     * Used by sub-formats such as PDF to map their selector shape to a text range.
+     */
+    selectorReviveFn?: (arg: I['target']['selector'][number], container: HTMLElement) => RevivedTextSelectorLike;
     /**
      * Determines whether an active selection should be dismissed
      * when a user ends their interaction (click, selection)
@@ -24,7 +29,7 @@ export interface TextAnnotatorOptions<I extends TextAnnotationLike = TextAnnotat
     offsetReferenceSelector?: string;
     renderer?: RendererType | RendererFactory<I>;
     selectionMode?: 'shortest' | 'all';
-    style?: HighlightStyleExpression;
+    style?: HighlightStyleExpression<I>;
     user?: User;
     userSelectAction?: UserSelectActionExpression<E>;
 }

package/dist/text-annotator.d.ts

@@ -7,7 +7,7 @@ import './text-annotator.css';
 export interface TextAnnotator<I extends TextAnnotationLike = TextAnnotation, E extends unknown = TextAnnotation> extends Omit<Annotator<I, E>, 'setStyle' | 'state'> {
     element: HTMLElement;
     renderer: Renderer;
-    setStyle(style?: HighlightStyleExpression, id?: string): void;
+    setStyle(style?: HighlightStyleExpression<I>, id?: string): void;
     scrollIntoView(annotationOrId: I | string, scrollParentOrId?: string | Element): boolean;
     setAnnotatingEnabled(enabled?: boolean): void;
     setAnnotatingMode(mode?: AnnotatingMode): void;