@embedpdf/plugin-annotation 1.0.6 → 1.0.8

package/dist/index.d.ts

@@ -1,82 +1,266 @@
 import { BasePluginConfig, EventHook, Action, BasePlugin, PluginRegistry, PluginManifest, PluginPackage } from '@embedpdf/core';
-import { Task, PdfAnnotationObject, PdfErrorReason, PdfAlphaColor, PdfAnnotationSubtype, PdfEngine } from '@embedpdf/models';
+import { PdfAnnotationSubtype, WebAlphaColor, Task, PdfAnnotationObject, PdfErrorReason, Rotation, AppearanceMode, ImageConversionTypes, PdfEngine } from '@embedpdf/models';
 
-interface AnnotationState {
-    annotations: Record<number, PdfAnnotationObject[]>;
-    selectedAnnotation: SelectedAnnotation | null;
-    annotationMode: PdfAnnotationSubtype | null;
+type CommitState = 'new' | 'dirty' | 'deleted' | 'synced' | 'ignored';
+interface TrackedAnnotation {
+    /** A stable, client-side unique identifier for history and state management. */
+    localId: number;
+    /**
+     * If the engine has already created the annotation in the PDF
+     * this is the definitive id coming from the engine.
+     * It is **never** cleared once set.
+     */
+    pdfId?: number;
+    /** local commit bookkeeping */
+    commitState: CommitState;
+    /** the actual annotation object */
+    object: PdfAnnotationObject;
 }
-interface SelectedAnnotation {
+interface RenderAnnotationOptions {
     pageIndex: number;
-    annotationId: number;
     annotation: PdfAnnotationObject;
+    scaleFactor?: number;
+    rotation?: Rotation;
+    dpr?: number;
+    mode?: AppearanceMode;
+    imageType?: ImageConversionTypes;
+}
+interface BaseAnnotationDefaults extends WebAlphaColor {
+    interaction: {
+        mode: string;
+        exclusive: boolean;
+        cursor?: string;
+    };
+    textSelection?: boolean;
+}
+interface HighlightDefaults extends BaseAnnotationDefaults {
+    name: 'Highlight';
+}
+interface UnderlineDefaults extends BaseAnnotationDefaults {
+    name: 'Underline';
+}
+interface StrikeoutDefaults extends BaseAnnotationDefaults {
+    name: 'Strikeout';
+}
+interface SquigglyDefaults extends BaseAnnotationDefaults {
+    name: 'Squiggly';
+}
+interface InkDefaults extends BaseAnnotationDefaults {
+    name: 'Ink';
+    strokeWidth: number;
+}
+type AnnotationDefaults = HighlightDefaults | UnderlineDefaults | StrikeoutDefaults | SquigglyDefaults | InkDefaults;
+type ToolDefaultsBySubtype = {
+    [PdfAnnotationSubtype.HIGHLIGHT]: HighlightDefaults;
+    [PdfAnnotationSubtype.UNDERLINE]: UnderlineDefaults;
+    [PdfAnnotationSubtype.STRIKEOUT]: StrikeoutDefaults;
+    [PdfAnnotationSubtype.SQUIGGLY]: SquigglyDefaults;
+    [PdfAnnotationSubtype.INK]: InkDefaults;
+};
+type StylableSubtype = keyof ToolDefaultsBySubtype;
+type ToolDefaults<S extends PdfAnnotationSubtype> = ToolDefaultsBySubtype[Extract<S, keyof ToolDefaultsBySubtype>];
+type ActiveTool = {
+    mode: null;
+    defaults: null;
+} | {
+    [K in StylableSubtype]: {
+        mode: K;
+        defaults: ToolDefaultsBySubtype[K];
+    };
+}[StylableSubtype];
+interface AnnotationState {
+    pages: Record<number, string[]>;
+    byUid: Record<string, TrackedAnnotation>;
+    selectedUid: string | null;
+    annotationMode: StylableSubtype | null;
+    toolDefaults: ToolDefaultsBySubtype;
+    colorPresets: string[];
+    hasPendingChanges: boolean;
 }
 interface AnnotationPluginConfig extends BasePluginConfig {
+    toolDefaults?: Partial<ToolDefaultsBySubtype>;
+    colorPresets?: string[];
+    /**
+     * When `false` mutations are kept in memory and must be
+     * flushed with `commitPendingChanges()`.
+     */
+    autoCommit?: boolean;
 }
 interface AnnotationCapability {
     getPageAnnotations: (options: GetPageAnnotationsOptions) => Task<PdfAnnotationObject[], PdfErrorReason>;
+    getSelectedAnnotation: () => TrackedAnnotation | null;
     selectAnnotation: (pageIndex: number, annotationId: number) => void;
     deselectAnnotation: () => void;
-    updateAnnotationColor: (color: PdfAlphaColor) => Promise<boolean>;
-    setAnnotationMode: (mode: PdfAnnotationSubtype | null) => void;
+    getAnnotationMode: () => StylableSubtype | null;
+    setAnnotationMode: (mode: StylableSubtype | null) => void;
+    /** strongly typed – only sub-types we have defaults for */
+    getToolDefaults: <S extends StylableSubtype>(subtype: S) => ToolDefaultsBySubtype[S];
+    /** Partially patch a single tool’s defaults */
+    setToolDefaults: <S extends StylableSubtype>(subtype: S, patch: Partial<ToolDefaultsBySubtype[S]>) => void;
+    /** current palette – UI just reads this */
+    getColorPresets: () => string[];
+    /** append a swatch (deduped by RGBA) */
+    addColorPreset: (color: string) => void;
+    createAnnotation: (pageIndex: number, annotation: PdfAnnotationObject) => void;
+    updateAnnotation: (pageIndex: number, annotationId: number, patch: Partial<PdfAnnotationObject>) => void;
+    deleteAnnotation: (pageIndex: number, annotationId: number) => void;
+    renderAnnotation: (options: RenderAnnotationOptions) => Task<Blob, PdfErrorReason>;
+    /** undo / redo */
     onStateChange: EventHook<AnnotationState>;
+    onModeChange: EventHook<StylableSubtype | null>;
+    onActiveToolChange: EventHook<ActiveTool>;
+    commit: () => void;
+}
+interface SelectedAnnotation {
+    pageIndex: number;
+    localId: number;
+    annotation: PdfAnnotationObject;
 }
 interface GetPageAnnotationsOptions {
     pageIndex: number;
 }
-interface UpdateAnnotationColorOptions {
+interface UpdateAnnotationColorOptions extends WebAlphaColor {
     pageIndex: number;
     annotationId: number;
-    color: PdfAlphaColor;
 }
 
-declare const SET_ANNOTATIONS = "SET_ANNOTATIONS";
-declare const SELECT_ANNOTATION = "SELECT_ANNOTATION";
-declare const DESELECT_ANNOTATION = "DESELECT_ANNOTATION";
-declare const SET_ANNOTATION_MODE = "SET_ANNOTATION_MODE";
-declare const UPDATE_ANNOTATION_COLOR = "UPDATE_ANNOTATION_COLOR";
+declare const SET_ANNOTATIONS = "ANNOTATION/SET_ANNOTATIONS";
+declare const REINDEX_PAGE_ANNOTATIONS = "ANNOTATION/REINDEX_PAGE";
+declare const SELECT_ANNOTATION = "ANNOTATION/SELECT_ANNOTATION";
+declare const DESELECT_ANNOTATION = "ANNOTATION/DESELECT_ANNOTATION";
+declare const SET_ANNOTATION_MODE = "ANNOTATION/SET_ANNOTATION_MODE";
+declare const UPDATE_TOOL_DEFAULTS = "ANNOTATION/UPDATE_TOOL_DEFAULTS";
+declare const ADD_COLOR_PRESET = "ANNOTATION/ADD_COLOR_PRESET";
+declare const CREATE_ANNOTATION = "ANNOTATION/CREATE_ANNOTATION";
+declare const PATCH_ANNOTATION = "ANNOTATION/PATCH_ANNOTATION";
+declare const DELETE_ANNOTATION = "ANNOTATION/DELETE_ANNOTATION";
+declare const COMMIT_PENDING_CHANGES = "ANNOTATION/COMMIT";
+declare const STORE_PDF_ID = "ANNOTATION/STORE_PDF_ID";
+declare const PURGE_ANNOTATION = "ANNOTATION/PURGE_ANNOTATION";
 interface SetAnnotationsAction extends Action {
     type: typeof SET_ANNOTATIONS;
     payload: Record<number, PdfAnnotationObject[]>;
 }
+interface ReindexPageAnnotationsAction extends Action {
+    type: typeof REINDEX_PAGE_ANNOTATIONS;
+    payload: {
+        pageIndex: number;
+    };
+}
 interface SelectAnnotationAction extends Action {
     type: typeof SELECT_ANNOTATION;
-    payload: SelectedAnnotation;
+    payload: {
+        pageIndex: number;
+        localId: number;
+    };
 }
 interface DeselectAnnotationAction extends Action {
     type: typeof DESELECT_ANNOTATION;
 }
 interface SetAnnotationModeAction extends Action {
     type: typeof SET_ANNOTATION_MODE;
-    payload: PdfAnnotationSubtype | null;
+    payload: StylableSubtype | null;
+}
+interface UpdateToolDefaultsAction extends Action {
+    type: typeof UPDATE_TOOL_DEFAULTS;
+    payload: {
+        subtype: StylableSubtype;
+        patch: Partial<ToolDefaultsBySubtype[StylableSubtype]>;
+    };
+}
+interface AddColorPresetAction extends Action {
+    type: typeof ADD_COLOR_PRESET;
+    payload: string;
+}
+interface CreateAnnotationAction extends Action {
+    type: typeof CREATE_ANNOTATION;
+    payload: {
+        pageIndex: number;
+        localId: number;
+        annotation: PdfAnnotationObject;
+    };
+}
+interface PatchAnnotationAction extends Action {
+    type: typeof PATCH_ANNOTATION;
+    payload: {
+        pageIndex: number;
+        localId: number;
+        patch: Partial<PdfAnnotationObject>;
+    };
 }
-interface UpdateAnnotationColorAction extends Action {
-    type: typeof UPDATE_ANNOTATION_COLOR;
+interface DeleteAnnotationAction extends Action {
+    type: typeof DELETE_ANNOTATION;
     payload: {
         pageIndex: number;
-        annotationId: number;
-        color: PdfAlphaColor;
+        localId: number;
     };
 }
-type AnnotationAction = SetAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | SetAnnotationModeAction | UpdateAnnotationColorAction;
+interface CommitAction extends Action {
+    type: typeof COMMIT_PENDING_CHANGES;
+}
+interface StorePdfIdAction extends Action {
+    type: typeof STORE_PDF_ID;
+    payload: {
+        uid: string;
+        pdfId: number;
+    };
+}
+interface PurgeAnnotationAction extends Action {
+    type: typeof PURGE_ANNOTATION;
+    payload: {
+        uid: string;
+    };
+}
+type AnnotationAction = SetAnnotationsAction | ReindexPageAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | SetAnnotationModeAction | UpdateToolDefaultsAction | AddColorPresetAction | CreateAnnotationAction | PatchAnnotationAction | DeleteAnnotationAction | CommitAction | StorePdfIdAction | PurgeAnnotationAction;
 
 declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig, AnnotationCapability, AnnotationState, AnnotationAction> {
     static readonly id: "annotation";
+    private readonly ANNOTATION_HISTORY_TOPIC;
+    private readonly config;
     private engine;
     private readonly state$;
-    constructor(id: string, registry: PluginRegistry, engine: PdfEngine);
+    private readonly interactionManager;
+    private readonly selection;
+    private readonly history;
+    /** Map <subtype> → <modeId>.  Filled once in `initialize()`. */
+    private readonly modeBySubtype;
+    /** The inverse map for quick lookup in onModeChange().          */
+    private readonly subtypeByMode;
+    private readonly modeChange$;
+    private readonly activeTool$;
+    constructor(id: string, registry: PluginRegistry, engine: PdfEngine, config: AnnotationPluginConfig);
     initialize(): Promise<void>;
+    private registerTool;
     protected buildCapability(): AnnotationCapability;
-    onStoreUpdated(_prevState: AnnotationState, newState: AnnotationState): void;
+    private createActiveTool;
+    private emitActiveTool;
+    onStoreUpdated(prev: AnnotationState, next: AnnotationState): void;
     private getAllAnnotations;
     private getPageAnnotations;
+    private renderAnnotation;
     private selectAnnotation;
-    private updateSelectedAnnotationColor;
+    private createAnnotation;
+    private updateAnnotation;
+    private deleteAnnotation;
+    private commit;
 }
 
 declare const ANNOTATION_PLUGIN_ID = "annotation";
 declare const manifest: PluginManifest<AnnotationPluginConfig>;
 
+/** All annotations _objects_ on a single page (order preserved). */
+declare const getAnnotationsByPageIndex: (s: AnnotationState, page: number) => TrackedAnnotation[];
+/** Shortcut: every page → list of annotation objects. */
+declare const getAnnotations: (s: AnnotationState) => Record<number, TrackedAnnotation[]>;
+/** The full `TrackedAnnotation` for the current selection. */
+declare const getSelectedAnnotation: (s: AnnotationState) => TrackedAnnotation | null;
+declare const getSelectedAnnotationWithPageIndex: (s: AnnotationState) => SelectedAnnotation | null;
+declare const getSelectedAnnotationByPageIndex: (s: AnnotationState, pageIndex: number) => TrackedAnnotation | null;
+declare const isInAnnotationMode: (s: AnnotationState) => boolean;
+declare const getSelectedAnnotationMode: (s: AnnotationState) => keyof ToolDefaultsBySubtype | null;
+/** Check if a given anno on a page is the current selection. */
+declare const isAnnotationSelected: (s: AnnotationState, page: number, id: number) => boolean;
+
 declare const AnnotationPluginPackage: PluginPackage<AnnotationPlugin, AnnotationPluginConfig, AnnotationState, AnnotationAction>;
 
-export { ANNOTATION_PLUGIN_ID, type AnnotationCapability, AnnotationPlugin, type AnnotationPluginConfig, AnnotationPluginPackage, type AnnotationState, type GetPageAnnotationsOptions, type SelectedAnnotation, type UpdateAnnotationColorOptions, manifest };
+export { ANNOTATION_PLUGIN_ID, type ActiveTool, type AnnotationCapability, type AnnotationDefaults, AnnotationPlugin, type AnnotationPluginConfig, AnnotationPluginPackage, type AnnotationState, type BaseAnnotationDefaults, type CommitState, type GetPageAnnotationsOptions, type HighlightDefaults, type InkDefaults, type RenderAnnotationOptions, type SelectedAnnotation, type SquigglyDefaults, type StrikeoutDefaults, type StylableSubtype, type ToolDefaults, type ToolDefaultsBySubtype, type TrackedAnnotation, type UnderlineDefaults, type UpdateAnnotationColorOptions, getAnnotations, getAnnotationsByPageIndex, getSelectedAnnotation, getSelectedAnnotationByPageIndex, getSelectedAnnotationMode, getSelectedAnnotationWithPageIndex, isAnnotationSelected, isInAnnotationMode, manifest };