@embedpdf/plugin-annotation 2.10.0 → 2.11.0

package/dist/lib/actions.d.ts

@@ -86,6 +86,7 @@ export interface SetActiveToolIdAction extends Action {
     payload: {
         documentId: string;
         toolId: string | null;
+        context?: Record<string, unknown>;
     };
 }
 export interface CreateAnnotationAction extends Action {
@@ -177,7 +178,7 @@ export declare const deselectAnnotation: (documentId: string) => DeselectAnnotat
 export declare const addToSelection: (documentId: string, pageIndex: number, id: string) => AddToSelectionAction;
 export declare const removeFromSelection: (documentId: string, id: string) => RemoveFromSelectionAction;
 export declare const setSelection: (documentId: string, ids: string[]) => SetSelectionAction;
-export declare const setActiveToolId: (documentId: string, toolId: string | null) => SetActiveToolIdAction;
+export declare const setActiveToolId: (documentId: string, toolId: string | null, context?: Record<string, unknown>) => SetActiveToolIdAction;
 export declare const createAnnotation: (documentId: string, pageIndex: number, annotation: PdfAnnotationObject) => CreateAnnotationAction;
 export declare const patchAnnotation: (documentId: string, pageIndex: number, id: string, patch: Partial<PdfAnnotationObject>) => PatchAnnotationAction;
 export declare const moveAnnotation: (documentId: string, pageIndex: number, id: string, patch: Partial<PdfAnnotationObject>) => MoveAnnotationAction;

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

@@ -7,6 +7,7 @@ import { PreviewState, HandlerServices } from './handlers/types';
 export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig, AnnotationCapability, AnnotationState, AnnotationAction> {
     static readonly id: "annotation";
     private readonly ANNOTATION_HISTORY_TOPIC;
+    private static readonly defaultHandlerFactories;
     readonly config: AnnotationPluginConfig;
     private readonly state$;
     private readonly interactionManager;
@@ -242,7 +243,7 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private moveAnnotationsMethod;
     private moveAnnotationMethod;
     getActiveTool(documentId?: string): AnnotationTool | null;
-    setActiveTool(toolId: string | null, documentId?: string): void;
+    setActiveTool(toolId: string | null, documentId?: string, context?: Record<string, unknown>): void;
     getTool<TId extends ToolId<AnnotationToolMap>>(toolId: TId): (ToolById<AnnotationToolMap, TId> & AnnotationTool) | undefined;
     getTool(toolId: string): AnnotationTool | undefined;
     findToolForAnnotation(annotation: PdfAnnotationObject): AnnotationTool | null;

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

@@ -11,7 +11,7 @@ export interface CirclePreviewData {
     strokeStyle: PdfAnnotationBorderStyle;
     strokeDashArray: number[];
 }
-interface SquarePreviewData extends CirclePreviewData {
+export interface SquarePreviewData extends CirclePreviewData {
 }
 export interface PolygonPreviewData {
     rect: Rect;
@@ -129,16 +129,29 @@ export interface HandlerServices {
         }) => void;
     }): void;
 }
+/**
+ * Extensible map from tool ID to per-activation context data.
+ * Plugins extend this via declaration merging to provide typed context
+ * for their custom tools (e.g. stamp appearance data, ghost image URL).
+ */
+export interface ToolContextMap {
+}
+/**
+ * Resolves the tool context type for a given tool ID.
+ * Returns the mapped type if known, otherwise a generic record.
+ */
+export type ResolvedToolContext<TId extends string> = TId extends keyof ToolContextMap ? ToolContextMap[TId] : Record<string, unknown>;
 /**
  * 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> {
+export interface HandlerFactory<A extends PdfAnnotationObject, TId extends string = string> {
     annotationType: PdfAnnotationSubtype;
-    create(context: HandlerContext<A>): PointerEventHandlersWithLifecycle;
+    create(context: HandlerContext<A, TId>): PointerEventHandlersWithLifecycle;
 }
-export interface HandlerContext<A extends PdfAnnotationObject> {
+export interface HandlerContext<A extends PdfAnnotationObject, TId extends string = string> {
     getTool: () => AnnotationTool<A> | undefined;
+    getToolContext: () => ResolvedToolContext<TId> | undefined;
     pageIndex: number;
     pageSize: Size;
     /** Effective page rotation (page intrinsic + document rotation), as a quarter-turn value (0-3). */
@@ -159,4 +172,3 @@ export interface SelectionHandlerFactory<A extends PdfAnnotationObject = PdfAnno
     toolId: string;
     handle(context: SelectionHandlerContext<A>, selections: FormattedSelection[], getText: () => Promise<string | undefined>): void;
 }
-export {};

package/dist/lib/index.d.ts

@@ -15,6 +15,7 @@ export * from './tools/tools-utils';
 export * from './geometry';
 export * as patching from './patching';
 export type { PatchFunction, TransformContext } from './patching/patch-registry';
+export * from './patching/insert-upright';
 export { initialState, initialDocumentState } from './reducer';
 export { useState } from './utils/use-state';
 export { useClickDetector } from './handlers/click-detector';

package/dist/lib/tools/default-tools.d.ts

@@ -162,7 +162,7 @@ export declare const defaultTools: ({
         smartLineThreshold?: undefined;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject, string>;
 } | {
     id: "inkHighlighter";
     name: string;
@@ -192,7 +192,7 @@ export declare const defaultTools: ({
         smartLineThreshold: number;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject, string>;
 } | {
     id: "circle";
     name: string;
@@ -223,7 +223,7 @@ export declare const defaultTools: ({
         };
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfCircleAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfCircleAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfCircleAnnoObject, string>;
 } | {
     id: "square";
     name: string;
@@ -254,7 +254,7 @@ export declare const defaultTools: ({
         };
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfSquareAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfSquareAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfSquareAnnoObject, string>;
 } | {
     id: "line";
     name: string;
@@ -285,7 +285,7 @@ export declare const defaultTools: ({
         defaultAngle: number;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfLineAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject, string>;
 } | {
     id: "lineArrow";
     name: string;
@@ -319,7 +319,7 @@ export declare const defaultTools: ({
         defaultAngle: number;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfLineAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject, string>;
 } | {
     id: "polyline";
     name: string;
@@ -343,7 +343,7 @@ export declare const defaultTools: ({
         strokeColor: string;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolylineAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolylineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolylineAnnoObject, string>;
 } | {
     id: "polygon";
     name: string;
@@ -367,7 +367,7 @@ export declare const defaultTools: ({
         strokeColor: string;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolygonAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolygonAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolygonAnnoObject, string>;
 } | {
     id: "textComment";
     name: string;
@@ -389,7 +389,7 @@ export declare const defaultTools: ({
     behavior: {
         selectAfterCreate: true;
     };
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfTextAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfTextAnnoObject, string>;
 } | {
     id: "freeText";
     name: string;
@@ -430,7 +430,7 @@ export declare const defaultTools: ({
         selectAfterCreate: true;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfFreeTextAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfFreeTextAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfFreeTextAnnoObject, string>;
 } | {
     id: "stamp";
     name: string;
@@ -453,7 +453,7 @@ export declare const defaultTools: ({
         useAppearanceStream: false;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfStampAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfStampAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfStampAnnoObject, string>;
 } | {
     id: "link";
     name: string;
@@ -480,7 +480,7 @@ export declare const defaultTools: ({
             height: number;
         };
     };
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLinkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLinkAnnoObject, string>;
 })[];
 export type DefaultAnnotationTool = (typeof defaultTools)[number];
 export type DefaultAnnotationToolMap = ToolMapFromList<typeof defaultTools>;

package/dist/lib/tools/tools-utils.d.ts

@@ -139,7 +139,7 @@ export declare const isInkTool: (tool: {
         smartLineThreshold?: undefined;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject, string>;
 };
 export declare const isInkHighlighterTool: (tool: {
     id: string;
@@ -172,7 +172,7 @@ export declare const isInkHighlighterTool: (tool: {
         smartLineThreshold: number;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject, string>;
 };
 export declare const isSquareTool: (tool: {
     id: string;
@@ -206,7 +206,7 @@ export declare const isSquareTool: (tool: {
         };
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfSquareAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfSquareAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfSquareAnnoObject, string>;
 };
 export declare const isCircleTool: (tool: {
     id: string;
@@ -240,7 +240,7 @@ export declare const isCircleTool: (tool: {
         };
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfCircleAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfCircleAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfCircleAnnoObject, string>;
 };
 export declare const isLineTool: (tool: {
     id: string;
@@ -274,7 +274,7 @@ export declare const isLineTool: (tool: {
         defaultAngle: number;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfLineAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject, string>;
 };
 export declare const isPolylineTool: (tool: {
     id: string;
@@ -301,7 +301,7 @@ export declare const isPolylineTool: (tool: {
         strokeColor: string;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolylineAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolylineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolylineAnnoObject, string>;
 };
 export declare const isPolygonTool: (tool: {
     id: string;
@@ -328,7 +328,7 @@ export declare const isPolygonTool: (tool: {
         strokeColor: string;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolygonAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolygonAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolygonAnnoObject, string>;
 };
 export declare const isFreeTextTool: (tool: {
     id: string;
@@ -372,7 +372,7 @@ export declare const isFreeTextTool: (tool: {
         selectAfterCreate: true;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfFreeTextAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfFreeTextAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfFreeTextAnnoObject, string>;
 };
 export declare const isStampTool: (tool: {
     id: string;
@@ -398,7 +398,7 @@ export declare const isStampTool: (tool: {
         useAppearanceStream: false;
     };
     transform: import('..').PatchFunction<import('@embedpdf/models').PdfStampAnnoObject>;
-    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfStampAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfStampAnnoObject, string>;
 };
 export declare const isInsertTextTool: (tool: {
     id: string;

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

@@ -179,7 +179,7 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject,
         useAppearanceStream?: boolean;
     } & InsertUprightBehaviorFor<T> & InkBehaviorFor<T>;
     /** Pointer-based creation handler (drag-to-create, click-to-place). */
-    pointerHandler?: HandlerFactory<T>;
+    pointerHandler?: HandlerFactory<T, TId>;
     /** Text-selection-based creation handler. */
     selectionHandler?: SelectionHandlerFactory<T>;
     /** Transform function for move, resize, rotate, and property-update operations. */

package/dist/lib/types.d.ts

@@ -117,6 +117,7 @@ export interface AnnotationDocumentState {
      */
     selectedUid: string | null;
     activeToolId: string | null;
+    activeToolContext?: Record<string, unknown>;
     hasPendingChanges: boolean;
     locked: LockMode;
 }
@@ -245,8 +246,8 @@ export interface AnnotationScope<TTools extends AnnotationToolMap = AnnotationTo
     /** Clear all selection */
     deselectAnnotation(): void;
     getActiveTool(): ToolUnion<TTools> | null;
-    setActiveTool<TId extends ToolId<TTools>>(toolId: TId | null): void;
-    setActiveTool(toolId: string | null): void;
+    setActiveTool<TId extends ToolId<TTools>>(toolId: TId | null, context?: Record<string, unknown>): void;
+    setActiveTool(toolId: string | null, context?: Record<string, unknown>): void;
     findToolForAnnotation(annotation: PdfAnnotationObject): ToolUnion<TTools> | null;
     importAnnotations(items: ImportAnnotationItem<PdfAnnotationObject>[]): void;
     createAnnotation<A extends PdfAnnotationObject>(pageIndex: number, annotation: A, context?: AnnotationCreateContext<A>): void;
@@ -386,8 +387,8 @@ export interface AnnotationCapability<TTools extends AnnotationToolMap = Annotat
     forDocument: (documentId: string) => AnnotationScope<TTools>;
     getActiveTool: () => ToolUnion<TTools> | null;
     setActiveTool: {
-        <TId extends ToolId<TTools>>(toolId: TId | null): void;
-        (toolId: string | null): void;
+        <TId extends ToolId<TTools>>(toolId: TId | null, context?: Record<string, unknown>): void;
+        (toolId: string | null, context?: Record<string, unknown>): void;
     };
     getTools: () => Array<ToolUnion<TTools>>;
     getTool: {