@embedpdf/plugin-annotation 1.0.11 → 1.0.13

package/dist/lib/types.d.ts

@@ -0,0 +1,168 @@
+import { BasePluginConfig, EventHook } from '@embedpdf/core';
+import { PdfAnnotationObject, PdfErrorReason, Task, PdfAnnotationSubtype, WebAlphaColor, Rotation, ImageConversionTypes, AppearanceMode, PdfBlendMode, PdfAnnotationBorderStyle, LineEndings } from '@embedpdf/models';
+export type CommitState = 'new' | 'dirty' | 'deleted' | 'synced' | 'ignored';
+export interface TrackedAnnotation<T extends PdfAnnotationObject = PdfAnnotationObject> {
+    /** A stable, client-side unique identifier for history and state management. */
+    localId: number;
+    /**
+     * If the engine has already created the annotation in the PDF
+     * this is the definitive id coming from the engine.
+     * It is **never** cleared once set.
+     */
+    pdfId?: number;
+    /** local commit bookkeeping */
+    commitState: CommitState;
+    /** the actual annotation object */
+    object: T;
+}
+export interface RenderAnnotationOptions {
+    pageIndex: number;
+    annotation: PdfAnnotationObject;
+    scaleFactor?: number;
+    rotation?: Rotation;
+    dpr?: number;
+    mode?: AppearanceMode;
+    imageType?: ImageConversionTypes;
+}
+export interface BaseAnnotationDefaults extends WebAlphaColor {
+    name: string;
+    subtype: PdfAnnotationSubtype;
+    interaction: {
+        mode: string;
+        exclusive: boolean;
+        cursor?: string;
+    };
+    textSelection?: boolean;
+    blendMode?: PdfBlendMode;
+}
+export type TextMarkupSubtype = PdfAnnotationSubtype.HIGHLIGHT | PdfAnnotationSubtype.UNDERLINE | PdfAnnotationSubtype.STRIKEOUT | PdfAnnotationSubtype.SQUIGGLY;
+export interface TextMarkupDefaults extends BaseAnnotationDefaults {
+    subtype: TextMarkupSubtype;
+    blendMode: PdfBlendMode;
+}
+export interface InkDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.INK;
+    strokeWidth: number;
+    intent?: string;
+}
+export interface TextDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.FREETEXT;
+    fontSize: number;
+}
+export interface CircleDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.CIRCLE;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+}
+export interface SquareDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.SQUARE;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+}
+export interface LineDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.LINE;
+    intent?: string;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+    lineEndings?: LineEndings;
+}
+export interface PolylineDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.POLYLINE;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+    lineEndings?: LineEndings;
+}
+export interface PolygonDefaults extends BaseAnnotationDefaults {
+    subtype: PdfAnnotationSubtype.POLYGON;
+    strokeWidth: number;
+    strokeColor: string;
+    strokeStyle: PdfAnnotationBorderStyle;
+    strokeDashArray?: number[];
+}
+export type AnnotationDefaults = TextMarkupDefaults | InkDefaults | TextDefaults | CircleDefaults | SquareDefaults | LineDefaults | PolylineDefaults | PolygonDefaults;
+export type ToolDefaultsByMode = {
+    [K in string]: AnnotationDefaults;
+};
+export type ActiveTool = {
+    variantKey: null;
+    defaults: null;
+} | {
+    [K in string]: {
+        variantKey: K;
+        defaults: ToolDefaultsByMode[K];
+    };
+}[string];
+export interface AnnotationState {
+    pages: Record<number, string[]>;
+    byUid: Record<string, TrackedAnnotation>;
+    selectedUid: string | null;
+    activeVariant: string | null;
+    toolDefaults: Record<string, AnnotationDefaults>;
+    colorPresets: string[];
+    hasPendingChanges: boolean;
+}
+export interface AnnotationPluginConfig extends BasePluginConfig {
+    toolDefaults?: Record<string, AnnotationDefaults>;
+    colorPresets?: string[];
+    /**
+     * When `false` mutations are kept in memory and must be
+     * flushed with `commitPendingChanges()`.
+     */
+    autoCommit?: boolean;
+}
+export interface AnnotationCapability {
+    getPageAnnotations: (options: GetPageAnnotationsOptions) => Task<PdfAnnotationObject[], PdfErrorReason>;
+    getSelectedAnnotation: () => TrackedAnnotation | null;
+    selectAnnotation: (pageIndex: number, annotationId: number) => void;
+    deselectAnnotation: () => void;
+    getActiveVariant: () => string | null;
+    setActiveVariant: (variantKey: string | null) => void;
+    /** strongly typed – only sub-types we have defaults for */
+    getToolDefaults: (variantKey: string) => AnnotationDefaults;
+    getToolDefaultsBySubtypeAndIntent: <Sub extends AnnotationDefaults['subtype']>(subtype: Sub, intent?: string | null) => Extract<AnnotationDefaults, {
+        subtype: Sub;
+    }>;
+    getToolDefaultsBySubtype: <Sub extends AnnotationDefaults['subtype']>(subtype: Sub) => Extract<AnnotationDefaults, {
+        subtype: Sub;
+    }>;
+    /** Return the subtype and intent for a given variant key */
+    getSubtypeAndIntentByVariant: (variantKey: string) => {
+        subtype: PdfAnnotationSubtype;
+        intent?: string;
+    };
+    /** Partially patch a single tool’s defaults */
+    setToolDefaults: (variantKey: string, patch: Partial<AnnotationDefaults>) => void;
+    /** current palette – UI just reads this */
+    getColorPresets: () => string[];
+    /** append a swatch (deduped by RGBA) */
+    addColorPreset: (color: string) => void;
+    createAnnotation: (pageIndex: number, annotation: PdfAnnotationObject) => void;
+    updateAnnotation: (pageIndex: number, annotationId: number, patch: Partial<PdfAnnotationObject>) => void;
+    deleteAnnotation: (pageIndex: number, annotationId: number) => void;
+    renderAnnotation: (options: RenderAnnotationOptions) => Task<Blob, PdfErrorReason>;
+    /** undo / redo */
+    onStateChange: EventHook<AnnotationState>;
+    onActiveVariantChange: EventHook<string | null>;
+    onActiveToolChange: EventHook<ActiveTool>;
+    commit: () => void;
+}
+export interface SelectedAnnotation<T extends PdfAnnotationObject = PdfAnnotationObject> {
+    pageIndex: number;
+    localId: number;
+    annotation: T;
+}
+export interface GetPageAnnotationsOptions {
+    pageIndex: number;
+}
+export interface UpdateAnnotationColorOptions extends WebAlphaColor {
+    pageIndex: number;
+    annotationId: number;
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a stable, document-wide unique ID from a page index and a stable local ID.
+ */
+export declare const makeUid: (pageIndex: number, localId: number) => string;
+/**
+ * Parses a UID string back into its constituent page index and stable local ID.
+ */
+export declare const parseUid: (uid: string) => {
+    pageIndex: number;
+    localId: number;
+};

package/dist/lib/variant-key.d.ts

@@ -0,0 +1,8 @@
+import { PdfAnnotationSubtype, PdfAnnotationObject } from '@embedpdf/models';
+export type VariantKey = string;
+export declare const makeVariantKey: (subtype: PdfAnnotationSubtype, intent?: string | null | undefined) => VariantKey;
+export declare const parseVariantKey: (key: VariantKey) => {
+    subtype: PdfAnnotationSubtype;
+    intent?: string;
+};
+export declare const variantKeyFromAnnotation: (a: PdfAnnotationObject) => VariantKey;

package/dist/preact/adapter.d.ts

@@ -0,0 +1,8 @@
+import { JSX, Fragment } from 'preact';
+export { useEffect, useRef, useState, useCallback, useMemo, useLayoutEffect } from 'preact/hooks';
+export type { ComponentChildren as ReactNode, JSX } from 'preact';
+export { Fragment };
+export type CSSProperties = import('preact').JSX.CSSProperties;
+export type HTMLAttributes<T = any> = import('preact').JSX.HTMLAttributes<T extends EventTarget ? T : never>;
+export type MouseEvent<T = Element> = JSX.TargetedMouseEvent<T extends EventTarget ? T : never>;
+export type PointerEvent<T = Element> = JSX.TargetedPointerEvent<T extends EventTarget ? T : never>;

package/dist/preact/core.d.ts

@@ -0,0 +1 @@
+export * from '@embedpdf/core/preact';