@embedpdf/plugin-annotation 2.7.0 → 2.8.0

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

@@ -17,6 +17,7 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     private importQueue;
     private commitInProgress;
     private handlerFactories;
+    private selectionHandlerFactories;
     private readonly activeTool$;
     private readonly events$;
     private readonly toolsChange$;
@@ -33,6 +34,7 @@ export declare class AnnotationPlugin extends BasePlugin<AnnotationPluginConfig,
     protected onDocumentLoaded(documentId: string): void;
     protected onDocumentClosed(documentId: string): void;
     private registerHandlerFactories;
+    private registerSelectionHandlerFactories;
     private registerBuiltInPatches;
     initialize(): Promise<void>;
     private registerInteractionForTool;

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

@@ -1,4 +1,5 @@
 export * from './ink.handler';
+export * from './text.handler';
 export * from './free-text.handler';
 export * from './line.handler';
 export * from './polyline.handler';
@@ -6,3 +7,6 @@ export * from './polygon.handler';
 export * from './square.handler';
 export * from './stamp.handler';
 export * from './circle.handler';
+export * from './text-markup.handler';
+export * from './insert-text.handler';
+export * from './replace-text.handler';

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

@@ -0,0 +1,8 @@
+import { PdfCaretAnnoObject } from '@embedpdf/models';
+import { SelectionHandlerFactory } from './types';
+/**
+ * Selection handler for the "Insert Text" tool.
+ * Creates a single Caret annotation at the end of the text selection
+ * with intent "Insert".
+ */
+export declare const insertTextSelectionHandler: SelectionHandlerFactory<PdfCaretAnnoObject>;

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

@@ -0,0 +1,9 @@
+import { PdfStrikeOutAnnoObject } from '@embedpdf/models';
+import { SelectionHandlerFactory } from './types';
+/**
+ * Selection handler for the "Replace Text" tool.
+ * Creates a Caret annotation (group leader, intent "Replace") at the end
+ * of the selection, plus a StrikeOut annotation (intent "StrikeOutTextEdit")
+ * over the full selection, linked to the Caret via IRT/RT=Group.
+ */
+export declare const replaceTextSelectionHandler: SelectionHandlerFactory<PdfStrikeOutAnnoObject>;

package/dist/lib/handlers/selection-utils.d.ts

@@ -0,0 +1,7 @@
+import { Rect } from '@embedpdf/models';
+/**
+ * Compute a caret annotation rect at the end of a text selection.
+ * The caret is half the line height, bottom-aligned with the line,
+ * and horizontally centered on the line's end edge.
+ */
+export declare function computeCaretRect(lastSegRect: Rect): Rect;

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

@@ -0,0 +1,7 @@
+import { SelectionHandlerFactory } from './types';
+/**
+ * Default selection handler for text-markup tools (highlight, underline,
+ * strikeout, squiggly). Used as a fallback when no tool-specific
+ * SelectionHandlerFactory is registered.
+ */
+export declare const textMarkupSelectionHandler: SelectionHandlerFactory;

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

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

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

@@ -1,5 +1,6 @@
 import { PointerEventHandlersWithLifecycle } from '@embedpdf/plugin-interaction-manager';
 import { PdfAnnotationObject, PdfAnnotationSubtype, Rect, Rotation, Size, AnnotationCreateContext, PdfAnnotationBorderStyle, Position, LineEndings, PdfInkListObject, PdfStandardFont, PdfTextAlignment, PdfVerticalAlignment } from '@embedpdf/models';
+import { FormattedSelection } from '@embedpdf/plugin-selection';
 import { AnnotationTool } from '../tools/types';
 export interface CirclePreviewData {
     rect: Rect;
@@ -138,4 +139,15 @@ export interface HandlerContext<A extends PdfAnnotationObject> {
     onPreview: (state: AnyPreviewState | null) => void;
     onCommit: (annotation: A, context?: AnnotationCreateContext<A>) => void;
 }
+export interface SelectionHandlerContext<A extends PdfAnnotationObject = PdfAnnotationObject> {
+    toolId: string;
+    documentId: string;
+    getTool: () => AnnotationTool<A> | null;
+    createAnnotation: (pageIndex: number, annotation: PdfAnnotationObject) => void;
+    selectAnnotation: (pageIndex: number, id: string) => void;
+}
+export interface SelectionHandlerFactory<A extends PdfAnnotationObject = PdfAnnotationObject> {
+    toolId: string;
+    handle(context: SelectionHandlerContext<A>, selections: FormattedSelection[], getText: () => Promise<string | undefined>): void;
+}
 export {};

package/dist/lib/helpers.d.ts

@@ -8,7 +8,7 @@ export type AnnoOf<S extends PdfAnnotationSubtype> = Extract<PdfAnnotationObject
     type: S;
 }>;
 export type TextMarkupSubtype = PdfAnnotationSubtype.HIGHLIGHT | PdfAnnotationSubtype.UNDERLINE | PdfAnnotationSubtype.STRIKEOUT | PdfAnnotationSubtype.SQUIGGLY;
-export type SidebarSubtype = TextMarkupSubtype | PdfAnnotationSubtype.INK | PdfAnnotationSubtype.SQUARE | PdfAnnotationSubtype.CIRCLE | PdfAnnotationSubtype.POLYGON | PdfAnnotationSubtype.LINE | PdfAnnotationSubtype.POLYLINE | PdfAnnotationSubtype.FREETEXT | PdfAnnotationSubtype.STAMP | PdfAnnotationSubtype.REDACT;
+export type SidebarSubtype = TextMarkupSubtype | PdfAnnotationSubtype.TEXT | PdfAnnotationSubtype.INK | PdfAnnotationSubtype.SQUARE | PdfAnnotationSubtype.CIRCLE | PdfAnnotationSubtype.POLYGON | PdfAnnotationSubtype.LINE | PdfAnnotationSubtype.POLYLINE | PdfAnnotationSubtype.FREETEXT | PdfAnnotationSubtype.STAMP | PdfAnnotationSubtype.REDACT | PdfAnnotationSubtype.CARET;
 /** True when `a.object.type === INK` – and narrows the generic. */
 export declare function isInk(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.INK>>;
 /** Example for Circle – create similar ones for Square, Line, etc. */
@@ -27,4 +27,5 @@ export declare function isStamp(a: TrackedAnnotation): a is TrackedAnnotation<An
 export declare function isText(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.TEXT>>;
 export declare function isLink(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.LINK>>;
 export declare function isRedact(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.REDACT>>;
+export declare function isCaret(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<PdfAnnotationSubtype.CARET>>;
 export declare function isSidebarAnnotation(a: TrackedAnnotation): a is TrackedAnnotation<AnnoOf<SidebarSubtype>>;

package/dist/lib/selectors.d.ts

@@ -40,9 +40,14 @@ export declare function getToolDefaultsById<K extends keyof ToolMap>(state: Anno
  * Collect every sidebar-eligible annotation and attach its TEXT replies,
  * grouped by page for efficient rendering.
  *
+ * Annotations linked via IRT / RT=Group are collapsed: the group leader
+ * becomes the sidebar entry and its non-LINK group members are attached
+ * as `groupMembers`. This keeps the sidebar compact for tools like
+ * Replace Text (Caret + StrikeOut pair).
+ *
  * Result shape:
  * {
- *   0: [{ page: 0, annotation: <TrackedAnnotation>, replies: [ … ] }, ...],
+ *   0: [{ page: 0, annotation: <TrackedAnnotation>, replies: [ … ], groupMembers: [ … ] }, ...],
  *   1: [{ page: 1, annotation: <TrackedAnnotation>, replies: [ … ] }, ...],
  *   …
  * }

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

@@ -8,8 +8,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -20,8 +22,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode: PdfBlendMode.Multiply;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -43,8 +45,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -55,8 +59,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -78,8 +82,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -90,8 +96,8 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -113,8 +119,10 @@ export declare const defaultTools: ({
         textSelection: true;
         isDraggable: false;
         isResizable: false;
+        isRotatable: false;
         isGroupDraggable: false;
         isGroupResizable: false;
+        showSelectionRects?: undefined;
         cursor?: undefined;
         lockAspectRatio?: undefined;
         lockGroupAspectRatio?: undefined;
@@ -125,8 +133,82 @@ export declare const defaultTools: ({
         color: string;
         opacity: number;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+    behavior?: undefined;
+} | {
+    id: "insertText";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        showSelectionRects: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+        cursor?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.CARET;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+        color?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    clickBehavior?: undefined;
+    behavior?: undefined;
+} | {
+    id: "replaceText";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 0 | 2;
+    interaction: {
+        exclusive: false;
+        textSelection: true;
+        isDraggable: false;
+        isResizable: false;
+        isRotatable: false;
+        isGroupDraggable: false;
+        isGroupResizable: false;
+        showSelectionRects?: undefined;
+        cursor?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.STRIKEOUT;
+        strokeColor: string;
+        opacity: number;
+        intent: string;
+        color?: undefined;
+        blendMode?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -150,8 +232,10 @@ export declare const defaultTools: ({
         isResizable: true;
         lockAspectRatio: false;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
         lockGroupAspectRatio?: undefined;
     };
     defaults: {
@@ -186,8 +270,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.INK;
@@ -221,8 +307,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.CIRCLE;
@@ -265,8 +353,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.SQUARE;
@@ -310,7 +400,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.LINE;
@@ -351,7 +443,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.LINE;
@@ -395,7 +489,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.POLYLINE;
@@ -430,7 +526,9 @@ export declare const defaultTools: ({
         isGroupResizable: true;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.POLYGON;
@@ -452,6 +550,47 @@ export declare const defaultTools: ({
     };
     clickBehavior?: undefined;
     behavior?: undefined;
+} | {
+    id: "textComment";
+    name: string;
+    matchScore: (a: import('@embedpdf/models').PdfAnnotationObject) => 1 | 0;
+    interaction: {
+        exclusive: false;
+        cursor: string;
+        isDraggable: true;
+        isResizable: false;
+        isRotatable: false;
+        textSelection?: undefined;
+        isGroupDraggable?: undefined;
+        isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
+        lockAspectRatio?: undefined;
+        lockGroupAspectRatio?: undefined;
+    };
+    defaults: {
+        type: PdfAnnotationSubtype.TEXT;
+        strokeColor: string;
+        opacity: number;
+        color?: undefined;
+        blendMode?: undefined;
+        intent?: undefined;
+        strokeWidth?: undefined;
+        strokeStyle?: undefined;
+        lineEndings?: undefined;
+        contents?: undefined;
+        fontSize?: undefined;
+        fontColor?: undefined;
+        fontFamily?: undefined;
+        textAlign?: undefined;
+        verticalAlign?: undefined;
+        backgroundColor?: undefined;
+    };
+    behavior: {
+        selectAfterCreate: true;
+        insertUpright?: undefined;
+        useAppearanceStream?: undefined;
+    };
+    clickBehavior?: undefined;
 } | {
     id: "freeText";
     name: string;
@@ -464,8 +603,10 @@ export declare const defaultTools: ({
         lockAspectRatio: false;
         lockGroupAspectRatio: (a: import('@embedpdf/models').PdfAnnotationObject) => boolean;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.FREETEXT;
@@ -480,8 +621,8 @@ export declare const defaultTools: ({
         opacity: number;
         strokeColor?: undefined;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
     };
@@ -497,6 +638,7 @@ export declare const defaultTools: ({
     };
     behavior: {
         insertUpright: true;
+        selectAfterCreate?: undefined;
         useAppearanceStream?: undefined;
     };
 } | {
@@ -511,8 +653,10 @@ export declare const defaultTools: ({
         lockAspectRatio: true;
         lockGroupAspectRatio: true;
         textSelection?: undefined;
+        isRotatable?: undefined;
         isGroupDraggable?: undefined;
         isGroupResizable?: undefined;
+        showSelectionRects?: undefined;
     };
     defaults: {
         type: PdfAnnotationSubtype.STAMP;
@@ -520,8 +664,8 @@ export declare const defaultTools: ({
         color?: undefined;
         opacity?: undefined;
         blendMode?: undefined;
-        strokeWidth?: undefined;
         intent?: undefined;
+        strokeWidth?: undefined;
         strokeStyle?: undefined;
         lineEndings?: undefined;
         contents?: undefined;
@@ -535,6 +679,7 @@ export declare const defaultTools: ({
     behavior: {
         insertUpright: true;
         useAppearanceStream: false;
+        selectAfterCreate?: undefined;
     };
     clickBehavior?: undefined;
 })[];

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

@@ -22,4 +22,6 @@ export declare const isPolylineTool: (tool: AnnotationTool<any> | undefined) =>
 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 {};

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

@@ -109,6 +109,8 @@ export type AnnotationTool<T extends PdfAnnotationObject = PdfAnnotationObject>
         cursor?: string;
         /** If true, this interaction mode is activated by selecting text. */
         textSelection?: boolean;
+        /** Whether to show the native text selection rectangles. Only relevant when textSelection is true. Defaults to false. */
+        showSelectionRects?: boolean;
         /** Whether this annotation can be dragged when selected individually. Can be dynamic based on annotation. */
         isDraggable?: DynamicBooleanProp;
         /** Whether this annotation can be resized when selected individually. Can be dynamic based on annotation. */

package/dist/lib/types.d.ts

@@ -337,6 +337,7 @@ export interface SidebarAnnotationEntry {
     page: number;
     annotation: TrackedAnnotation;
     replies: TrackedAnnotation<PdfTextAnnoObject>[];
+    groupMembers?: TrackedAnnotation[];
 }
 /**
  * Information about an annotation needed for constraint calculation.