@embedpdf/plugin-annotation 1.1.0 → 1.2.0

package/dist/lib/actions.d.ts

@@ -1,17 +1,18 @@
 import { Action } from '@embedpdf/core';
 import { PdfAnnotationObject } from '@embedpdf/models';
-import { AnnotationDefaults } from './types';
+import { AnnotationTool } from './tools/types';
 export declare const SET_ANNOTATIONS = "ANNOTATION/SET_ANNOTATIONS";
 export declare const SELECT_ANNOTATION = "ANNOTATION/SELECT_ANNOTATION";
 export declare const DESELECT_ANNOTATION = "ANNOTATION/DESELECT_ANNOTATION";
-export declare const UPDATE_TOOL_DEFAULTS = "ANNOTATION/UPDATE_TOOL_DEFAULTS";
 export declare const ADD_COLOR_PRESET = "ANNOTATION/ADD_COLOR_PRESET";
 export declare const CREATE_ANNOTATION = "ANNOTATION/CREATE_ANNOTATION";
 export declare const PATCH_ANNOTATION = "ANNOTATION/PATCH_ANNOTATION";
 export declare const DELETE_ANNOTATION = "ANNOTATION/DELETE_ANNOTATION";
 export declare const COMMIT_PENDING_CHANGES = "ANNOTATION/COMMIT";
 export declare const PURGE_ANNOTATION = "ANNOTATION/PURGE_ANNOTATION";
-export declare const SET_ACTIVE_VARIANT = "ANNOTATION/SET_ACTIVE_VARIANT";
+export declare const SET_ACTIVE_TOOL_ID = "ANNOTATION/SET_ACTIVE_TOOL_ID";
+export declare const SET_TOOL_DEFAULTS = "ANNOTATION/SET_TOOL_DEFAULTS";
+export declare const ADD_TOOL = "ANNOTATION/ADD_TOOL";
 export interface SetAnnotationsAction extends Action {
     type: typeof SET_ANNOTATIONS;
     payload: Record<number, PdfAnnotationObject[]>;
@@ -26,13 +27,6 @@ export interface SelectAnnotationAction extends Action {
 export interface DeselectAnnotationAction extends Action {
     type: typeof DESELECT_ANNOTATION;
 }
-export interface UpdateToolDefaultsAction extends Action {
-    type: typeof UPDATE_TOOL_DEFAULTS;
-    payload: {
-        variantKey: string;
-        patch: Partial<AnnotationDefaults>;
-    };
-}
 export interface AddColorPresetAction extends Action {
     type: typeof ADD_COLOR_PRESET;
     payload: string;
@@ -68,19 +62,31 @@ export interface PurgeAnnotationAction extends Action {
         uid: string;
     };
 }
-export interface SetActiveVariantAction extends Action {
-    type: typeof SET_ACTIVE_VARIANT;
+export interface SetActiveToolIdAction extends Action {
+    type: typeof SET_ACTIVE_TOOL_ID;
     payload: string | null;
 }
-export type AnnotationAction = SetAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | UpdateToolDefaultsAction | AddColorPresetAction | CreateAnnotationAction | PatchAnnotationAction | DeleteAnnotationAction | CommitAction | PurgeAnnotationAction | SetActiveVariantAction;
+export interface SetToolDefaultsAction extends Action {
+    type: typeof SET_TOOL_DEFAULTS;
+    payload: {
+        toolId: string;
+        patch: Partial<any>;
+    };
+}
+export interface AddToolAction extends Action {
+    type: typeof ADD_TOOL;
+    payload: AnnotationTool;
+}
+export type AnnotationAction = SetAnnotationsAction | SelectAnnotationAction | DeselectAnnotationAction | AddColorPresetAction | CreateAnnotationAction | PatchAnnotationAction | DeleteAnnotationAction | CommitAction | PurgeAnnotationAction | SetActiveToolIdAction | SetToolDefaultsAction | AddToolAction;
 export declare const setAnnotations: (p: Record<number, PdfAnnotationObject[]>) => SetAnnotationsAction;
 export declare const selectAnnotation: (pageIndex: number, id: string) => SelectAnnotationAction;
 export declare const deselectAnnotation: () => DeselectAnnotationAction;
-export declare const updateToolDefaults: (variantKey: string, patch: Partial<AnnotationDefaults>) => UpdateToolDefaultsAction;
 export declare const addColorPreset: (c: string) => AddColorPresetAction;
 export declare const createAnnotation: (pageIndex: number, annotation: PdfAnnotationObject) => CreateAnnotationAction;
 export declare const patchAnnotation: (pageIndex: number, id: string, patch: Partial<PdfAnnotationObject>) => PatchAnnotationAction;
 export declare const deleteAnnotation: (pageIndex: number, id: string) => DeleteAnnotationAction;
 export declare const commitPendingChanges: () => CommitAction;
 export declare const purgeAnnotation: (uid: string) => PurgeAnnotationAction;
-export declare const setActiveVariant: (k: string | null) => SetActiveVariantAction;
+export declare const setActiveToolId: (id: string | null) => SetActiveToolIdAction;
+export declare const setToolDefaults: (toolId: string, patch: Partial<any>) => SetToolDefaultsAction;
+export declare const addTool: (tool: AnnotationTool) => AddToolAction;

package/dist/lib/annotation-plugin.d.ts

@@ -1,6 +1,9 @@
 import { BasePlugin, PluginRegistry } from '@embedpdf/core';
+import { PdfAnnotationObject } from '@embedpdf/models';
 import { AnnotationCapability, AnnotationPluginConfig, AnnotationState } from './types';
 import { AnnotationAction } from './actions';
+import { AnnotationTool } from './tools/types';
+import { AnyPreviewState, HandlerServices } from './handlers/types';
 export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig, AnnotationCapability, AnnotationState, AnnotationAction> {
     static readonly id: "annotation";
     private readonly ANNOTATION_HISTORY_TOPIC;
@@ -9,25 +12,45 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private readonly interactionManager;
     private readonly selection;
     private readonly history;
-    private readonly modeByVariant;
-    private readonly variantByMode;
     private pendingContexts;
-    private readonly activeVariantChange$;
+    private handlerFactories;
     private readonly activeTool$;
+    private readonly events$;
+    private readonly patchRegistry;
+    private isInitialLoadComplete;
+    private importQueue;
     constructor(id: string, registry: PluginRegistry, config: AnnotationPluginConfig);
+    private registerHandlerFactories;
+    private registerBuiltInPatches;
     initialize(): Promise<void>;
-    private registerTool;
+    private registerInteractionForTool;
     protected buildCapability(): AnnotationCapability;
-    private createActiveTool;
-    private emitActiveTool;
     onStoreUpdated(prev: AnnotationState, next: AnnotationState): void;
+    private registerPatchFunction;
+    private transformAnnotation;
+    registerPageHandlers(pageIndex: number, scale: number, callbacks: {
+        services: HandlerServices;
+        onPreview: (toolId: string, state: AnyPreviewState | null) => void;
+    }): () => void;
     private getAllAnnotations;
     private getPageAnnotations;
     private renderAnnotation;
-    private selectAnnotation;
+    private importAnnotations;
+    private processImportQueue;
+    private processImportItems;
     private createAnnotation;
     private buildPatch;
     private updateAnnotation;
     private deleteAnnotation;
+    private selectAnnotation;
+    getActiveTool(): AnnotationTool | null;
+    setActiveTool(toolId: string | null): void;
+    getTool<T extends AnnotationTool>(toolId: string): T | undefined;
+    findToolForAnnotation(annotation: PdfAnnotationObject): AnnotationTool | null;
     private commit;
+    /**
+     * Gets the effective behavior setting for a tool, checking tool-specific config first,
+     * then falling back to plugin config.
+     */
+    private getToolBehavior;
 }

package/dist/lib/handlers/circle.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfCircleAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const circleHandlerFactory: HandlerFactory<PdfCircleAnnoObject>;

package/dist/lib/handlers/click-detector.d.ts

@@ -0,0 +1,27 @@
+import { PdfAnnotationObject } from '@embedpdf/models';
+import { AnnotationTool } from '../tools/types';
+interface ClickDetectorOptions<T extends PdfAnnotationObject> {
+    threshold?: number;
+    getTool: () => AnnotationTool<T> | undefined;
+    onClickDetected: (pos: {
+        x: number;
+        y: number;
+    }, tool: AnnotationTool<T>) => void;
+}
+export declare function useClickDetector<T extends PdfAnnotationObject>({ threshold, getTool, onClickDetected, }: ClickDetectorOptions<T>): {
+    onStart: (pos: {
+        x: number;
+        y: number;
+    }) => void;
+    onMove: (pos: {
+        x: number;
+        y: number;
+    }) => void;
+    onEnd: (pos: {
+        x: number;
+        y: number;
+    }) => void;
+    hasMoved: () => boolean;
+    reset: () => void;
+};
+export {};

package/dist/lib/handlers/free-text.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfFreeTextAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const freeTextHandlerFactory: HandlerFactory<PdfFreeTextAnnoObject>;

package/dist/lib/handlers/index.d.ts

@@ -0,0 +1,8 @@
+export * from './ink.handler';
+export * from './free-text.handler';
+export * from './line.handler';
+export * from './polyline.handler';
+export * from './polygon.handler';
+export * from './square.handler';
+export * from './stamp.handler';
+export * from './circle.handler';

package/dist/lib/handlers/ink.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfInkAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const inkHandlerFactory: HandlerFactory<PdfInkAnnoObject>;

package/dist/lib/handlers/line.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfLineAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const lineHandlerFactory: HandlerFactory<PdfLineAnnoObject>;

package/dist/lib/handlers/polygon.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfPolygonAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const polygonHandlerFactory: HandlerFactory<PdfPolygonAnnoObject>;

package/dist/lib/handlers/polyline.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfPolylineAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const polylineHandlerFactory: HandlerFactory<PdfPolylineAnnoObject>;

package/dist/lib/handlers/square.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfSquareAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const squareHandlerFactory: HandlerFactory<PdfSquareAnnoObject>;

package/dist/lib/handlers/stamp.handler.d.ts

@@ -0,0 +1,3 @@
+import { PdfStampAnnoObject } from '@embedpdf/models';
+import { HandlerFactory } from './types';
+export declare const stampHandlerFactory: HandlerFactory<PdfStampAnnoObject>;

package/dist/lib/handlers/types.d.ts

@@ -0,0 +1,139 @@
+import { PointerEventHandlersWithLifecycle } from '@embedpdf/plugin-interaction-manager';
+import { PdfAnnotationObject, PdfAnnotationSubtype, Rect, Size, AnnotationCreateContext, PdfAnnotationBorderStyle, Position, LineEndings, PdfInkListObject, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment } from '@embedpdf/models';
+import { AnnotationTool } from '../tools/types';
+export interface CirclePreviewData {
+    rect: Rect;
+    color: string;
+    opacity: number;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray: number[];
+}
+interface SquarePreviewData extends CirclePreviewData {
+}
+export interface PolygonPreviewData {
+    rect: Rect;
+    vertices: Position[];
+    currentVertex: Position;
+    color?: string;
+    opacity?: number;
+    strokeWidth: number;
+    strokeColor?: string;
+    strokeStyle?: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+}
+export interface PolylinePreviewData {
+    rect: Rect;
+    vertices: Position[];
+    currentVertex: Position;
+    color: string;
+    strokeColor: string;
+    opacity: number;
+    strokeWidth: number;
+    lineEndings?: LineEndings;
+}
+export interface LinePreviewData {
+    rect: Rect;
+    linePoints: {
+        start: Position;
+        end: Position;
+    };
+    strokeWidth: number;
+    color: string;
+    strokeColor: string;
+    opacity: number;
+    lineEndings?: LineEndings;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray: number[];
+}
+export interface InkPreviewData {
+    rect: Rect;
+    inkList: PdfInkListObject[];
+    strokeWidth: number;
+    color: string;
+    opacity: number;
+}
+export interface FreeTextPreviewData {
+    rect: Rect;
+    fontColor?: string;
+    opacity?: number;
+    fontSize?: number;
+    fontFamily?: PdfStandardFont;
+    backgroundColor?: string;
+    textAlign?: PdfTextAlignment;
+    verticalAlign?: PdfVerticalAlignment;
+    contents?: string;
+}
+/**
+ * Map types to their preview data
+ */
+export interface PreviewDataMap {
+    [PdfAnnotationSubtype.CIRCLE]: CirclePreviewData;
+    [PdfAnnotationSubtype.SQUARE]: SquarePreviewData;
+    [PdfAnnotationSubtype.POLYGON]: PolygonPreviewData;
+    [PdfAnnotationSubtype.POLYLINE]: PolylinePreviewData;
+    [PdfAnnotationSubtype.LINE]: LinePreviewData;
+    [PdfAnnotationSubtype.INK]: InkPreviewData;
+    [PdfAnnotationSubtype.FREETEXT]: FreeTextPreviewData;
+}
+/**
+ * Typed preview state - constrain T to keys that exist in PreviewDataMap
+ */
+export type TypedPreviewState<T extends keyof PreviewDataMap> = {
+    type: T;
+    bounds: Rect;
+    data: PreviewDataMap[T];
+};
+/**
+ * Union of all preview states
+ */
+export type AnyPreviewState = {
+    [K in keyof PreviewDataMap]: TypedPreviewState<K>;
+}[keyof PreviewDataMap];
+/**
+ * Generic version for handlers - use conditional type for safety
+ */
+export interface PreviewState<T extends PdfAnnotationSubtype = PdfAnnotationSubtype> {
+    type: T;
+    bounds: Rect;
+    data: T extends keyof PreviewDataMap ? PreviewDataMap[T] : any;
+}
+/**
+ * Defines the DOM-based services that the UI layer must provide to the handlers.
+ * This is the bridge that keeps the core logic framework-agnostic.
+ */
+export interface HandlerServices {
+    requestFile(options: {
+        accept: string;
+        onFile: (file: File) => void;
+    }): void;
+    processImage(options: {
+        source: string | File;
+        maxWidth?: number;
+        maxHeight?: number;
+        onComplete: (result: {
+            imageData: ImageData;
+            width: number;
+            height: number;
+        }) => void;
+    }): void;
+}
+/**
+ * The context object passed to a handler factory when creating a handler.
+ * It contains all the necessary information and callbacks.
+ */
+export interface HandlerFactory<A extends PdfAnnotationObject> {
+    annotationType: PdfAnnotationSubtype;
+    create(context: HandlerContext<A>): PointerEventHandlersWithLifecycle;
+}
+export interface HandlerContext<A extends PdfAnnotationObject> {
+    getTool: () => AnnotationTool<A> | undefined;
+    pageIndex: number;
+    pageSize: Size;
+    scale: number;
+    services: HandlerServices;
+    onPreview: (state: AnyPreviewState | null) => void;
+    onCommit: (annotation: A, context?: AnnotationCreateContext<A>) => void;
+}
+export {};

package/dist/lib/helpers.d.ts

@@ -1,5 +1,5 @@
 import { PdfAnnotationSubtype, PdfAnnotationObject } from '@embedpdf/models';
-import { TrackedAnnotation, AnnotationDefaults, HighlightDefaults, UnderlineDefaults, StrikeoutDefaults, SquigglyDefaults } from './types';
+import { TrackedAnnotation } from './types';
 export type AnnoOf<S extends PdfAnnotationSubtype> = Extract<PdfAnnotationObject, {
     type: S;
 }>;
@@ -22,8 +22,3 @@ export declare function isFreeText(a: TrackedAnnotation): a is TrackedAnnotation
 export declare function isStamp(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.STAMP>>;
 export declare function isText(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.TEXT>>;
 export declare function isSidebarAnnotation(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<SidebarSubtype>>;
-export declare function isHighlightDefaults(defaults: AnnotationDefaults): defaults is HighlightDefaults;
-export declare function isUnderlineDefaults(defaults: AnnotationDefaults): defaults is UnderlineDefaults;
-export declare function isStrikeoutDefaults(defaults: AnnotationDefaults): defaults is StrikeoutDefaults;
-export declare function isSquigglyDefaults(defaults: AnnotationDefaults): defaults is SquigglyDefaults;
-export declare function isTextMarkupDefaults(defaults: AnnotationDefaults): defaults is HighlightDefaults | UnderlineDefaults | StrikeoutDefaults | SquigglyDefaults;

package/dist/lib/index.d.ts

@@ -7,6 +7,8 @@ export * from './annotation-plugin';
 export * from './types';
 export * from './manifest';
 export * from './selectors';
-export * from './variant-key';
 export * from './helpers';
+export * from './handlers/types';
+export * from './tools/types';
+export * from './tools/tools-utils';
 export * as patching from './patching';

package/dist/lib/patching/index.d.ts

@@ -1,4 +1,4 @@
-export * from './derived-rect';
 export * from './patch-utils';
 export * from './line-ending-handlers';
 export * from './line-endings';
+export * from './patch-registry';

package/dist/lib/patching/patch-registry.d.ts

@@ -0,0 +1,27 @@
+import { PdfAnnotationObject, PdfAnnotationSubtype } from '@embedpdf/models';
+export interface TransformContext<T extends PdfAnnotationObject = PdfAnnotationObject> {
+    /** The type of transformation being applied */
+    type: 'move' | 'resize' | 'vertex-edit' | 'property-update';
+    /** The changes being applied - can be any properties of the annotation */
+    changes: Partial<T>;
+    /** Optional metadata about the transformation */
+    metadata?: {
+        maintainAspectRatio?: boolean;
+        [key: string]: any;
+    };
+}
+export type PatchFunction<T extends PdfAnnotationObject> = (original: T, context: TransformContext<T>) => Partial<T>;
+/**
+ * Registry for annotation-specific patch functions.
+ * Each patch function knows how to transform its annotation type.
+ */
+export declare class PatchRegistry {
+    private patches;
+    register<T extends PdfAnnotationObject>(type: PdfAnnotationSubtype, patchFn: PatchFunction<T>): void;
+    /**
+     * Transform an annotation based on the context.
+     * Returns the transformed properties or just the changes if no patch function exists.
+     */
+    transform<T extends PdfAnnotationObject>(annotation: T, context: TransformContext<T>): Partial<T>;
+}
+export declare const patchRegistry: PatchRegistry;

package/dist/lib/patching/patches/index.d.ts

@@ -0,0 +1,4 @@
+export * from './ink.patch';
+export * from './line.patch';
+export * from './polyline.patch';
+export * from './polygon.patch';

package/dist/lib/patching/patches/ink.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfInkAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchInk: PatchFunction<PdfInkAnnoObject>;

package/dist/lib/patching/patches/line.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfLineAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchLine: PatchFunction<PdfLineAnnoObject>;

package/dist/lib/patching/patches/polygon.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfPolygonAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchPolygon: PatchFunction<PdfPolygonAnnoObject>;

package/dist/lib/patching/patches/polyline.patch.d.ts

@@ -0,0 +1,3 @@
+import { PdfPolylineAnnoObject } from '@embedpdf/models';
+import { PatchFunction } from '../patch-registry';
+export declare const patchPolyline: PatchFunction<PdfPolylineAnnoObject>;

package/dist/lib/selectors.d.ts

@@ -1,4 +1,5 @@
-import { AnnotationDefaults, AnnotationState, SidebarAnnotationEntry, TrackedAnnotation } from './types';
+import { AnnotationState, SidebarAnnotationEntry, TrackedAnnotation } from './types';
+import { ToolMap } from './tools/tools-utils';
 /** All annotations _objects_ on a single page (order preserved). */
 export declare const getAnnotationsByPageIndex: (s: AnnotationState, page: number) => TrackedAnnotation<import('@embedpdf/models').PdfAnnotationObject>[];
 /** Shortcut: every page → list of annotation objects. */
@@ -6,22 +7,17 @@ export declare const getAnnotations: (s: AnnotationState) => Record<number, Trac
 /** The full `TrackedAnnotation` for the current selection. */
 export declare const getSelectedAnnotation: (s: AnnotationState) => TrackedAnnotation<import('@embedpdf/models').PdfAnnotationObject> | null;
 export declare const getSelectedAnnotationByPageIndex: (s: AnnotationState, pageIndex: number) => TrackedAnnotation<import('@embedpdf/models').PdfAnnotationObject> | null;
-export declare const isInAnnotationVariant: (s: AnnotationState) => boolean;
-export declare const getSelectedAnnotationVariant: (s: AnnotationState) => string | null;
 /** Check if a given anno on a page is the current selection. */
 export declare const isAnnotationSelected: (s: AnnotationState, id: string) => boolean;
 /**
- * Return the tool-defaults for a given subtype and (optionally) intent.
- * If the exact variant (subtype + intent) is not present, it gracefully
- * falls back to the plain subtype variant.
+ * Returns the current defaults for a specific tool by its ID.
+ * This is fully type-safe and infers the correct return type.
  *
- * The return type is inferred so that you always get the concrete default
- * interface for the supplied subtype (e.g. `InkDefaults` for `INK`,
- * `CircleDefaults` for `CIRCLE`, …).
+ * @param state The annotation plugin's state.
+ * @param toolId The ID of the tool (e.g., 'highlight', 'pen').
+ * @returns The tool's current `defaults` object, or `undefined` if not found.
  */
-export declare function getToolDefaultsBySubtypeAndIntent<S extends AnnotationState, TSub extends AnnotationDefaults['subtype']>(state: S, subtype: TSub, intent?: string | null): Extract<AnnotationDefaults, {
-    subtype: TSub;
-}>;
+export declare function getToolDefaultsById<K extends keyof ToolMap>(state: AnnotationState, toolId: K): ToolMap[K]['defaults'] | undefined;
 /**
  * Collect every sidebar-eligible annotation and attach its TEXT replies,
  * grouped by page for efficient rendering.