@embedpdf/plugin-annotation 2.9.1 → 2.10.0

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

@@ -1,27 +1,453 @@
-import { AnnotationTool } from './types';
+import { ToolMapFromList } from './types';
 import { defaultTools } from './default-tools';
-type DefaultTool = (typeof defaultTools)[number];
-export type ToolMap = {
-    [T in DefaultTool as T['id']]: T;
-};
+export type ToolMap = ToolMapFromList<typeof defaultTools>;
 /**
  * A factory that creates a type-safe predicate function for a specific tool ID.
  * This is more reliable for TypeScript's type inference than a single generic function.
  */
-export declare function createToolPredicate<K extends keyof ToolMap>(id: K): (tool: AnnotationTool<any> | undefined) => tool is ToolMap[K];
-export declare const isHighlightTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["highlight"];
-export declare const isSquigglyTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["squiggly"];
-export declare const isUnderlineTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["underline"];
-export declare const isStrikeoutTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["strikeout"];
-export declare const isInkTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["ink"];
-export declare const isInkHighlighterTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["inkHighlighter"];
-export declare const isSquareTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["square"];
-export declare const isCircleTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["circle"];
-export declare const isLineTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["line"];
-export declare const isPolylineTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["polyline"];
-export declare const isPolygonTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["polygon"];
-export declare const isFreeTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["freeText"];
-export declare const isStampTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["stamp"];
-export declare const isInsertTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["insertText"];
-export declare const isReplaceTextTool: (tool: AnnotationTool<any> | undefined) => tool is ToolMap["replaceText"];
-export {};
+export declare function createToolPredicate<K extends keyof ToolMap>(id: K): (tool: {
+    id: string;
+} | undefined) => tool is ToolMap[K];
+export declare const isHighlightTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "highlight";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.HIGHLIGHT;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        blendMode: import("@embedpdf/models").PdfBlendMode.Multiply;
+    };
+};
+export declare const isSquigglyTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "squiggly";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.SQUIGGLY;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+    };
+};
+export declare const isUnderlineTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "underline";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.UNDERLINE;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+    };
+};
+export declare const isStrikeoutTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "strikeout";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.STRIKEOUT;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+    };
+};
+export declare const isInkTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "ink";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: false;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.INK;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        intent?: undefined;
+        blendMode?: undefined;
+    };
+    behavior: {
+        commitDelay: number;
+        smartLineRecognition?: undefined;
+        smartLineThreshold?: undefined;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+};
+export declare const isInkHighlighterTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "inkHighlighter";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 10;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.INK;
+        intent: string;
+        strokeColor: string;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        blendMode: import("@embedpdf/models").PdfBlendMode.Multiply;
+    };
+    behavior: {
+        commitDelay: number;
+        smartLineRecognition: true;
+        smartLineThreshold: number;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfInkAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfInkAnnoObject>;
+};
+export declare const isSquareTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "square";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.SQUARE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        strokeStyle: import("@embedpdf/models").PdfAnnotationBorderStyle.SOLID;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfSquareAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfSquareAnnoObject>;
+};
+export declare const isCircleTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "circle";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.CIRCLE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        strokeStyle: import("@embedpdf/models").PdfAnnotationBorderStyle.SOLID;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfCircleAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfCircleAnnoObject>;
+};
+export declare const isLineTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "line";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: false;
+        lockAspectRatio: false;
+        isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.LINE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        intent?: undefined;
+        lineEndings?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultLength: number;
+        defaultAngle: number;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfLineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfLineAnnoObject>;
+};
+export declare const isPolylineTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "polyline";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: false;
+        lockAspectRatio: false;
+        isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.POLYLINE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolylineAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolylineAnnoObject>;
+};
+export declare const isPolygonTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "polygon";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: false;
+        lockAspectRatio: false;
+        isGroupResizable: true;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.POLYGON;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfPolygonAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfPolygonAnnoObject>;
+};
+export declare const isFreeTextTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "freeText";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: false;
+        lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.FREETEXT;
+        contents: string;
+        fontSize: number;
+        fontColor: string;
+        fontFamily: import("@embedpdf/models").PdfStandardFont.Helvetica;
+        textAlign: import("@embedpdf/models").PdfTextAlignment.Left;
+        verticalAlign: import("@embedpdf/models").PdfVerticalAlignment.Top;
+        color: string;
+        backgroundColor: string;
+        opacity: number;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+        defaultContent: string;
+    };
+    behavior: {
+        insertUpright: true;
+        editAfterCreate: true;
+        selectAfterCreate: true;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfFreeTextAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfFreeTextAnnoObject>;
+};
+export declare const isStampTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "stamp";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: true;
+        lockAspectRatio: true;
+        lockGroupAspectRatio: true;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.STAMP;
+    };
+    behavior: {
+        insertUpright: true;
+        useAppearanceStream: false;
+    };
+    transform: import('..').PatchFunction<import('@embedpdf/models').PdfStampAnnoObject>;
+    pointerHandler: import('..').HandlerFactory<import('@embedpdf/models').PdfStampAnnoObject>;
+};
+export declare const isInsertTextTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "insertText";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 1 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        showSelectionRects: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.CARET;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+    };
+    selectionHandler: import('..').SelectionHandlerFactory<import('@embedpdf/models').PdfCaretAnnoObject>;
+};
+export declare const isReplaceTextTool: (tool: {
+    id: string;
+} | undefined) => tool is {
+    id: "replaceText";
+    name: string;
+    labelKey: string;
+    categories: string[];
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+    };
+    defaults: {
+        type: import("@embedpdf/models").PdfAnnotationSubtype.STRIKEOUT;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+    };
+    selectionHandler: import('..').SelectionHandlerFactory<import('@embedpdf/models').PdfStrikeOutAnnoObject>;
+};

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

@@ -1,4 +1,6 @@
 import { PdfAnnotationObject, PdfAnnotationSubtype, Size } from '@embedpdf/models';
+import { HandlerFactory, SelectionHandlerFactory } from '../handlers/types';
+import { PatchFunction } from '../patching/patch-registry';
 /**
  * A dynamic boolean property that can be either a static boolean
  * or a function that receives the annotation and returns a boolean.
@@ -65,6 +67,8 @@ export interface ClickBehaviorMap {
     [PdfAnnotationSubtype.SQUARE]: ShapeClickBehavior;
     [PdfAnnotationSubtype.LINE]: LineClickBehavior;
     [PdfAnnotationSubtype.FREETEXT]: FreeTextClickBehavior;
+    [PdfAnnotationSubtype.WIDGET]: ShapeClickBehavior;
+    [PdfAnnotationSubtype.LINK]: ShapeClickBehavior;
 }
 type GetToolConfig<T extends PdfAnnotationObject> = T['type'] extends keyof ToolConfigMap ? ToolConfigMap[T['type']] : {};
 type ClickBehaviorFor<T extends PdfAnnotationObject> = Extract<T['type'], keyof ClickBehaviorMap> extends never ? {} : {
@@ -118,11 +122,15 @@ type InkBehaviorFor<T extends PdfAnnotationObject> = [T] extends [
  * The primary interface for defining an annotation tool.
  * Uses a type alias to properly combine the base interface with conditional properties.
  */
-export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject> = {
+export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject, TId extends string = string> = {
     /** A unique identifier, e.g., 'ink', 'arrow' */
-    id: string;
+    id: TId;
     /** A user-facing name for UI elements, e.g., 'Pen' */
     name: string;
+    /** Translation key for the tool label, e.g., 'annotation.ink'. Used by the UI for i18n. */
+    labelKey?: string;
+    /** Category tags for authoring mode control, e.g., `['annotation', 'form']`. */
+    categories?: string[];
     /**
      * Determines how well this tool matches an existing annotation.
      * Higher numbers indicate a more specific match.
@@ -170,5 +178,30 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         /** Override whether this annotation type uses AP rendering before editing (default: true) */
         useAppearanceStream?: boolean;
     } & InsertUprightBehaviorFor<T> & InkBehaviorFor<T>;
+    /** Pointer-based creation handler (drag-to-create, click-to-place). */
+    pointerHandler?: HandlerFactory<T>;
+    /** Text-selection-based creation handler. */
+    selectionHandler?: SelectionHandlerFactory<T>;
+    /** Transform function for move, resize, rotate, and property-update operations. */
+    transform?: PatchFunction<T>;
 } & ClickBehaviorFor<T>;
+export interface AnnotationToolRecord {
+    id: string;
+    defaults: Record<string, unknown>;
+}
+export type AnnotationToolMap = Record<string, AnnotationToolRecord>;
+export type ToolId<TMap extends AnnotationToolMap> = Extract<keyof TMap, string>;
+export type ToolById<TMap extends AnnotationToolMap, TId extends ToolId<TMap>> = TMap[TId];
+export type ToolMapFromList<TTools extends readonly {
+    id: string;
+}[]> = {
+    [T in TTools[number] as T['id']]: T;
+};
+export type UpsertToolMap<TMap extends AnnotationToolMap, TTool extends AnnotationTool> = Omit<TMap, TTool['id']> & {
+    [K in TTool['id']]: TTool;
+};
+/**
+ * Helper to preserve literal IDs and concrete tool typing.
+ */
+export declare const defineAnnotationTool: <const TTool extends AnnotationTool<any>>(tool: TTool) => TTool;
 export {};