@embedpdf/plugin-annotation 1.1.1 → 1.2.0

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

@@ -0,0 +1,450 @@
+import { PdfAnnotationBorderStyle, PdfAnnotationLineEnding, PdfAnnotationSubtype, PdfBlendMode, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment } from '@embedpdf/models';
+export declare const defaultTools: ({
+    id: "highlight";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        textSelection: true;
+        cursor?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.HIGHLIGHT;
+        color: string;
+        opacity: number;
+        blendMode: PdfBlendMode.Multiply;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "underline";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        textSelection: true;
+        cursor?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.UNDERLINE;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "strikeout";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        textSelection: true;
+        cursor?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.STRIKEOUT;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "squiggly";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        textSelection: true;
+        cursor?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.SQUIGGLY;
+        color: string;
+        opacity: number;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "ink";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.INK;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "inkHighlighter";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 10;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.INK;
+        intent: string;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        blendMode: PdfBlendMode.Multiply;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "circle";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.CIRCLE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        strokeStyle: PdfAnnotationBorderStyle.SOLID;
+        blendMode?: undefined;
+        intent?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+        defaultLength?: undefined;
+        defaultAngle?: undefined;
+        defaultContent?: undefined;
+    };
+} | {
+    id: "square";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.SQUARE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        strokeStyle: PdfAnnotationBorderStyle.SOLID;
+        blendMode?: undefined;
+        intent?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+        defaultLength?: undefined;
+        defaultAngle?: undefined;
+        defaultContent?: undefined;
+    };
+} | {
+    id: "line";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 5;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.LINE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultLength: number;
+        defaultAngle: number;
+        defaultSize?: undefined;
+        defaultContent?: undefined;
+    };
+} | {
+    id: "lineArrow";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 10;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.LINE;
+        intent: string;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        lineEndings: {
+            start: PdfAnnotationLineEnding.None;
+            end: PdfAnnotationLineEnding.OpenArrow;
+        };
+        blendMode?: undefined;
+        strokeStyle?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultLength: number;
+        defaultAngle: number;
+        defaultSize?: undefined;
+        defaultContent?: undefined;
+    };
+} | {
+    id: "polyline";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.POLYLINE;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "polygon";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.POLYGON;
+        color: string;
+        opacity: number;
+        strokeWidth: number;
+        strokeColor: string;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+} | {
+    id: "freeText";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.FREETEXT;
+        contents: string;
+        fontSize: number;
+        fontColor: string;
+        fontFamily: PdfStandardFont.Helvetica;
+        textAlign: PdfTextAlignment.Left;
+        verticalAlign: PdfVerticalAlignment.Top;
+        backgroundColor: string;
+        opacity: number;
+        color?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+    };
+    clickBehavior: {
+        enabled: true;
+        defaultSize: {
+            width: number;
+            height: number;
+        };
+        defaultContent: string;
+        defaultLength?: undefined;
+        defaultAngle?: undefined;
+    };
+} | {
+    id: "stamp";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        mode: string;
+        exclusive: false;
+        cursor: string;
+        textSelection?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.STAMP;
+        color?: undefined;
+        opacity?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        intent?: undefined;
+        strokeColor?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+})[];

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

@@ -0,0 +1,25 @@
+import { AnnotationTool } from './types';
+import { defaultTools } from './default-tools';
+type DefaultTool = (typeof defaultTools)[number];
+export type ToolMap = {
+    [T in DefaultTool as T['id']]: T;
+};
+/**
+ * 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 {};

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

@@ -0,0 +1,96 @@
+import { PdfAnnotationObject, PdfAnnotationSubtype, Size } from '@embedpdf/models';
+/**
+ * Specific configuration for Stamp tools.
+ */
+export interface StampToolConfig {
+    /** The base64 or URL source for the stamp's image. */
+    imageSrc?: string;
+    imageSize?: Size;
+}
+/**
+ * Click behavior for shape annotations (Circle, Square)
+ */
+export interface ShapeClickBehavior {
+    /** If true, creates annotation on click with default size */
+    enabled: boolean;
+    /** Default size to use when clicking (PDF units) */
+    defaultSize: Size;
+}
+/**
+ * Click behavior for line annotations
+ */
+export interface LineClickBehavior {
+    /** If true, creates annotation on click with default length */
+    enabled: boolean;
+    /** Default length of the line */
+    defaultLength: number;
+    /** Default angle in radians (0 = horizontal right) */
+    defaultAngle?: number;
+}
+/**
+ * Click behavior for free text annotations
+ */
+export interface FreeTextClickBehavior {
+    /** If true, creates annotation on click with default size */
+    enabled: boolean;
+    /** Default size for the text box */
+    defaultSize: Size;
+    /** Optional default content */
+    defaultContent?: string;
+}
+/**
+ * A central, extensible map that associates an annotation subtype
+ * with its unique tool configuration interface.
+ */
+export interface ToolConfigMap {
+    [PdfAnnotationSubtype.STAMP]: StampToolConfig;
+}
+/**
+ * Map of annotation subtypes to their click behavior configuration
+ */
+export interface ClickBehaviorMap {
+    [PdfAnnotationSubtype.CIRCLE]: ShapeClickBehavior;
+    [PdfAnnotationSubtype.SQUARE]: ShapeClickBehavior;
+    [PdfAnnotationSubtype.LINE]: LineClickBehavior;
+    [PdfAnnotationSubtype.FREETEXT]: FreeTextClickBehavior;
+}
+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 ? {} : {
+    clickBehavior?: ClickBehaviorMap[Extract<T['type'], keyof ClickBehaviorMap>];
+};
+/**
+ * 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> = {
+    /** A unique identifier, e.g., 'ink', 'arrow' */
+    id: string;
+    /** A user-facing name for UI elements, e.g., 'Pen' */
+    name: string;
+    /**
+     * Determines how well this tool matches an existing annotation.
+     * Higher numbers indicate a more specific match.
+     */
+    matchScore: (annotation: PdfAnnotationObject) => number;
+    /**
+     * The defaults combine the base annotation properties (Partial<T>)
+     * with any custom tool configuration (C) found in the ToolConfigMap.
+     */
+    defaults: Partial<T> & GetToolConfig<T>;
+    /** Defines how this tool interacts with the viewer. */
+    interaction: {
+        mode: string;
+        exclusive: boolean;
+        cursor?: string;
+        /** If true, this interaction mode is activated by selecting text. */
+        textSelection?: boolean;
+    };
+    /** Tool-specific behavior settings that override plugin defaults */
+    behavior?: {
+        /** When true, deactivate this tool after creating an annotation. Overrides plugin config. */
+        deactivateToolAfterCreate?: boolean;
+        /** When true, select the annotation immediately after creation. Overrides plugin config. */
+        selectAfterCreate?: boolean;
+    };
+} & ClickBehaviorFor<T>;
+export {};