@lexmata/micropdf 0.4.0

package/dist/annot.js

@@ -0,0 +1,697 @@
+/**
+ * Annot - PDF annotation handling
+ *
+ * This module provides comprehensive PDF annotation support with 100% API compatibility
+ * with MuPDF's annotation operations. It supports creating, modifying, and managing
+ * various types of PDF annotations including text notes, highlights, stamps, shapes,
+ * ink annotations, and more.
+ *
+ * **Key Features:**
+ * - 28 annotation types (text, highlight, stamp, ink, shapes, etc.)
+ * - Complete annotation properties (color, opacity, borders, etc.)
+ * - Annotation lifecycle management (creation, modification, deletion)
+ * - Dirty tracking for efficient updates
+ * - Reference counting for memory management
+ *
+ * **Supported Annotation Types:**
+ * - **Text Markup**: Highlight, Underline, Squiggly, StrikeOut
+ * - **Note Annotations**: Text, FreeText
+ * - **Shape Annotations**: Square, Circle, Line, Polygon, PolyLine
+ * - **Stamp Annotations**: Stamp (Approved, Draft, etc.)
+ * - **Drawing Annotations**: Ink (freehand drawing)
+ * - **Special Types**: Link, FileAttachment, Sound, Movie, Widget, etc.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * import { Annotation, AnnotationType, AnnotationFlags } from 'micropdf';
+ *
+ * // Create a text annotation
+ * const textAnnot = Annotation.createText(
+ *   { x0: 100, y0: 100, x1: 150, y1: 120 },
+ *   'This is a note'
+ * );
+ *
+ * // Create a highlight annotation
+ * const highlightAnnot = Annotation.createHighlight(
+ *   { x0: 50, y0: 200, x1: 300, y1: 220 },
+ *   [1, 1, 0] // Yellow
+ * );
+ *
+ * // Modify annotation properties
+ * highlightAnnot.opacity = 0.5;
+ * highlightAnnot.author = 'John Doe';
+ * highlightAnnot.setFlag(AnnotationFlags.Print, true);
+ *
+ * // Check if annotation was modified
+ * if (highlightAnnot.isDirty) {
+ *   // Update appearance
+ *   highlightAnnot.update();
+ * }
+ * ```
+ *
+ * @module annot
+ */
+import { Rect, Point } from './geometry.js';
+/**
+ * PDF annotation types.
+ *
+ * These correspond to the standard PDF annotation types as defined in the PDF specification.
+ * Each type has specific rendering behavior and properties.
+ *
+ * @enum {number}
+ */
+export var AnnotationType;
+(function (AnnotationType) {
+    /** Text note annotation - sticky note icon */
+    AnnotationType[AnnotationType["Text"] = 0] = "Text";
+    /** Link annotation - hyperlink to URL or document location */
+    AnnotationType[AnnotationType["Link"] = 1] = "Link";
+    /** Free text annotation - text directly on page */
+    AnnotationType[AnnotationType["FreeText"] = 2] = "FreeText";
+    /** Line annotation - straight line with optional endpoints */
+    AnnotationType[AnnotationType["Line"] = 3] = "Line";
+    /** Square annotation - rectangle shape */
+    AnnotationType[AnnotationType["Square"] = 4] = "Square";
+    /** Circle annotation - circle/ellipse shape */
+    AnnotationType[AnnotationType["Circle"] = 5] = "Circle";
+    /** Polygon annotation - closed polygon shape */
+    AnnotationType[AnnotationType["Polygon"] = 6] = "Polygon";
+    /** PolyLine annotation - open polyline shape */
+    AnnotationType[AnnotationType["PolyLine"] = 7] = "PolyLine";
+    /** Highlight annotation - text markup highlighting */
+    AnnotationType[AnnotationType["Highlight"] = 8] = "Highlight";
+    /** Underline annotation - text markup underlining */
+    AnnotationType[AnnotationType["Underline"] = 9] = "Underline";
+    /** Squiggly annotation - text markup squiggly underline */
+    AnnotationType[AnnotationType["Squiggly"] = 10] = "Squiggly";
+    /** StrikeOut annotation - text markup strikethrough */
+    AnnotationType[AnnotationType["StrikeOut"] = 11] = "StrikeOut";
+    /** Stamp annotation - rubber stamp (Approved, Draft, etc.) */
+    AnnotationType[AnnotationType["Stamp"] = 12] = "Stamp";
+    /** Caret annotation - text insertion point */
+    AnnotationType[AnnotationType["Caret"] = 13] = "Caret";
+    /** Ink annotation - freehand drawing paths */
+    AnnotationType[AnnotationType["Ink"] = 14] = "Ink";
+    /** Popup annotation - popup window for another annotation */
+    AnnotationType[AnnotationType["Popup"] = 15] = "Popup";
+    /** File attachment annotation - embedded file */
+    AnnotationType[AnnotationType["FileAttachment"] = 16] = "FileAttachment";
+    /** Sound annotation - embedded sound */
+    AnnotationType[AnnotationType["Sound"] = 17] = "Sound";
+    /** Movie annotation - embedded video */
+    AnnotationType[AnnotationType["Movie"] = 18] = "Movie";
+    /** Widget annotation - interactive form field */
+    AnnotationType[AnnotationType["Widget"] = 19] = "Widget";
+    /** Screen annotation - multimedia screen */
+    AnnotationType[AnnotationType["Screen"] = 20] = "Screen";
+    /** Printer mark annotation - printing marks */
+    AnnotationType[AnnotationType["PrinterMark"] = 21] = "PrinterMark";
+    /** Trap net annotation - color separation trapping */
+    AnnotationType[AnnotationType["TrapNet"] = 22] = "TrapNet";
+    /** Watermark annotation - page watermark */
+    AnnotationType[AnnotationType["Watermark"] = 23] = "Watermark";
+    /** 3D annotation - 3D artwork */
+    AnnotationType[AnnotationType["ThreeD"] = 24] = "ThreeD";
+    /** Redact annotation - content to be redacted */
+    AnnotationType[AnnotationType["Redact"] = 25] = "Redact";
+})(AnnotationType || (AnnotationType = {}));
+/**
+ * Annotation flags (bit flags).
+ *
+ * These flags control the visibility, behavior, and interaction of annotations.
+ * Multiple flags can be combined using bitwise OR operations.
+ *
+ * @example Using annotation flags:
+ * ```typescript
+ * import { Annotation, AnnotationFlags } from 'micropdf';
+ *
+ * const annot = Annotation.createText(rect, 'Note');
+ *
+ * // Set multiple flags
+ * annot.setFlags(AnnotationFlags.Print | AnnotationFlags.ReadOnly);
+ *
+ * // Check if a flag is set
+ * if (annot.hasFlag(AnnotationFlags.Print)) {
+ *   console.log('Annotation will be printed');
+ * }
+ *
+ * // Toggle a flag
+ * annot.setFlag(AnnotationFlags.Hidden, true);
+ * ```
+ *
+ * @enum {number}
+ */
+export var AnnotationFlags;
+(function (AnnotationFlags) {
+    /** Annotation is invisible (not displayed or printed) */
+    AnnotationFlags[AnnotationFlags["Invisible"] = 1] = "Invisible";
+    /** Annotation is hidden (not displayed, but may be printed) */
+    AnnotationFlags[AnnotationFlags["Hidden"] = 2] = "Hidden";
+    /** Annotation should be printed */
+    AnnotationFlags[AnnotationFlags["Print"] = 4] = "Print";
+    /** Annotation should not scale with zoom */
+    AnnotationFlags[AnnotationFlags["NoZoom"] = 8] = "NoZoom";
+    /** Annotation should not rotate with page */
+    AnnotationFlags[AnnotationFlags["NoRotate"] = 16] = "NoRotate";
+    /** Annotation should not be viewed (but may be printed) */
+    AnnotationFlags[AnnotationFlags["NoView"] = 32] = "NoView";
+    /** Annotation is read-only (cannot be modified or deleted) */
+    AnnotationFlags[AnnotationFlags["ReadOnly"] = 64] = "ReadOnly";
+    /** Annotation is locked (cannot be moved or resized) */
+    AnnotationFlags[AnnotationFlags["Locked"] = 128] = "Locked";
+    /** Toggle NoView flag based on user actions */
+    AnnotationFlags[AnnotationFlags["ToggleNoView"] = 256] = "ToggleNoView";
+    /** Annotation contents are locked (cannot be edited) */
+    AnnotationFlags[AnnotationFlags["LockedContents"] = 512] = "LockedContents";
+})(AnnotationFlags || (AnnotationFlags = {}));
+/**
+ * Line ending styles for line annotations.
+ *
+ * These styles define the appearance of line endings for Line, PolyLine,
+ * and Polygon annotations.
+ *
+ * @example Using line ending styles:
+ * ```typescript
+ * import { Annotation, LineEndingStyle } from 'micropdf';
+ *
+ * const lineAnnot = Annotation.createLine(rect, start, end);
+ * lineAnnot.lineStartStyle = LineEndingStyle.OpenArrow;
+ * lineAnnot.lineEndStyle = LineEndingStyle.ClosedArrow;
+ * ```
+ *
+ * @enum {number}
+ */
+export var LineEndingStyle;
+(function (LineEndingStyle) {
+    /** No line ending */
+    LineEndingStyle[LineEndingStyle["None"] = 0] = "None";
+    /** Square line ending */
+    LineEndingStyle[LineEndingStyle["Square"] = 1] = "Square";
+    /** Circle line ending */
+    LineEndingStyle[LineEndingStyle["Circle"] = 2] = "Circle";
+    /** Diamond line ending */
+    LineEndingStyle[LineEndingStyle["Diamond"] = 3] = "Diamond";
+    /** Open arrow line ending */
+    LineEndingStyle[LineEndingStyle["OpenArrow"] = 4] = "OpenArrow";
+    /** Closed arrow line ending (filled) */
+    LineEndingStyle[LineEndingStyle["ClosedArrow"] = 5] = "ClosedArrow";
+    /** Butt line ending (perpendicular cap) */
+    LineEndingStyle[LineEndingStyle["Butt"] = 6] = "Butt";
+    /** Reverse open arrow */
+    LineEndingStyle[LineEndingStyle["ROpenArrow"] = 7] = "ROpenArrow";
+    /** Reverse closed arrow (filled) */
+    LineEndingStyle[LineEndingStyle["RClosedArrow"] = 8] = "RClosedArrow";
+    /** Slash line ending (diagonal cap) */
+    LineEndingStyle[LineEndingStyle["Slash"] = 9] = "Slash";
+})(LineEndingStyle || (LineEndingStyle = {}));
+/**
+ * A PDF annotation.
+ *
+ * Represents a single PDF annotation with all its properties and methods.
+ * Annotations can be text notes, highlights, shapes, stamps, ink drawings, and more.
+ *
+ * **Lifecycle:**
+ * 1. Create annotation using static factory methods or constructor
+ * 2. Modify properties (color, opacity, contents, etc.)
+ * 3. Check `isDirty` to see if annotation needs updating
+ * 4. Call `update()` to update appearance
+ * 5. Increment/decrement reference count for memory management
+ * 6. Drop annotation when done (`drop()`)
+ *
+ * **Properties:**
+ * - Type, rectangle, flags
+ * - Contents, author, subject
+ * - Color, opacity, borders
+ * - Line endpoints and styles (for line annotations)
+ * - Modification date
+ * - Popup association
+ *
+ * **Methods:**
+ * - Getters/setters for all properties
+ * - Type checking (`isHighlight()`, `isStamp()`, etc.)
+ * - Dirty tracking (`isDirty`, `markDirty()`, `clearDirty()`)
+ * - Reference counting (`keep()`, `drop()`)
+ * - Appearance updates (`update()`)
+ * - Cloning (`clone()`)
+ *
+ * @example Creating and modifying annotations:
+ * ```typescript
+ * // Create a highlight annotation
+ * const highlight = Annotation.createHighlight(
+ *   { x0: 100, y0: 200, x1: 400, y1: 220 },
+ *   [1, 1, 0] // Yellow
+ * );
+ *
+ * // Modify properties
+ * highlight.opacity = 0.3;
+ * highlight.author = 'John Doe';
+ * highlight.contents = 'Important section';
+ *
+ * // Check if modified
+ * if (highlight.isDirty) {
+ *   highlight.update(); // Update appearance
+ * }
+ *
+ * // Clone annotation
+ * const copy = highlight.clone();
+ *
+ * // Clean up
+ * highlight.drop();
+ * copy.drop();
+ * ```
+ *
+ * @example Working with different annotation types:
+ * ```typescript
+ * // Text note
+ * const note = Annotation.createText(rect, 'Important!');
+ * note.setFlag(AnnotationFlags.ReadOnly, true);
+ *
+ * // Stamp
+ * const stamp = Annotation.createStamp(rect, 'Approved');
+ * stamp.color = [0, 1, 0]; // Green
+ *
+ * // Line with arrows
+ * const line = Annotation.createLine(rect, start, end);
+ * line.lineStartStyle = LineEndingStyle.OpenArrow;
+ * line.lineEndStyle = LineEndingStyle.ClosedArrow;
+ *
+ * // Free text
+ * const freeText = Annotation.createFreeText(rect, 'This is text');
+ * freeText.borderWidth = 2;
+ * ```
+ *
+ * @class
+ */
+export class Annotation {
+    _type;
+    _rect;
+    _flags = AnnotationFlags.Print;
+    _contents = '';
+    _author = '';
+    _color = [1, 1, 0]; // Yellow default
+    _interiorColor = [];
+    _borderWidth = 1;
+    _opacity = 1.0;
+    _lineStart = Point.ORIGIN;
+    _lineEnd = Point.ORIGIN;
+    _refCount = 1;
+    _dirty = false;
+    _hasPopup = false;
+    /**
+     * Creates a new PDF annotation.
+     *
+     * **Note**: Prefer using static factory methods (e.g., `createHighlight()`, `createStamp()`)
+     * instead of the constructor for better type safety and convenience.
+     *
+     * @param type - The annotation type
+     * @param rect - The annotation rectangle on the page
+     *
+     * @example Using the constructor:
+     * ```typescript
+     * const annot = new Annotation(AnnotationType.Square, {
+     *   x0: 100, y0: 100, x1: 200, y1: 200
+     * });
+     * ```
+     */
+    constructor(type, rect) {
+        this._type = type;
+        this._rect = Rect.from(rect);
+    }
+    /**
+     * Create a new annotation (alias for constructor).
+     *
+     * @param type - The annotation type
+     * @param rect - The annotation rectangle
+     * @returns A new annotation instance
+     *
+     * @deprecated Use static factory methods instead (e.g., `createHighlight()`)
+     */
+    static create(type, rect) {
+        return new Annotation(type, rect);
+    }
+    // ============================================================================
+    // Reference Counting
+    // ============================================================================
+    keep() {
+        this._refCount++;
+        return this;
+    }
+    drop() {
+        if (this._refCount > 0) {
+            this._refCount--;
+        }
+    }
+    /**
+     * Clone this annotation
+     */
+    clone() {
+        const cloned = new Annotation(this._type, this._rect);
+        cloned._flags = this._flags;
+        cloned._contents = this._contents;
+        cloned._author = this._author;
+        cloned._color = [...this._color];
+        cloned._interiorColor = [...this._interiorColor];
+        cloned._borderWidth = this._borderWidth;
+        cloned._opacity = this._opacity;
+        cloned._lineStart = this._lineStart;
+        cloned._lineEnd = this._lineEnd;
+        cloned._hasPopup = this._hasPopup;
+        return cloned;
+    }
+    // ============================================================================
+    // Basic Properties
+    // ============================================================================
+    get type() {
+        return this._type;
+    }
+    get rect() {
+        return this._rect;
+    }
+    set rect(r) {
+        this._rect = Rect.from(r);
+        this._dirty = true;
+    }
+    // ============================================================================
+    // Flags
+    // ============================================================================
+    get flags() {
+        return this._flags;
+    }
+    set flags(f) {
+        this._flags = f;
+        this._dirty = true;
+    }
+    hasFlag(flag) {
+        return (this._flags & flag) !== 0;
+    }
+    setFlag(flag, value) {
+        if (value) {
+            this._flags |= flag;
+        }
+        else {
+            this._flags &= ~flag;
+        }
+        this._dirty = true;
+    }
+    get isHidden() {
+        return this.hasFlag(AnnotationFlags.Hidden);
+    }
+    set isHidden(value) {
+        this.setFlag(AnnotationFlags.Hidden, value);
+    }
+    get isPrintable() {
+        return this.hasFlag(AnnotationFlags.Print);
+    }
+    set isPrintable(value) {
+        this.setFlag(AnnotationFlags.Print, value);
+    }
+    get isReadOnly() {
+        return this.hasFlag(AnnotationFlags.ReadOnly);
+    }
+    set isReadOnly(value) {
+        this.setFlag(AnnotationFlags.ReadOnly, value);
+    }
+    get isLocked() {
+        return this.hasFlag(AnnotationFlags.Locked);
+    }
+    set isLocked(value) {
+        this.setFlag(AnnotationFlags.Locked, value);
+    }
+    // ============================================================================
+    // Content Properties
+    // ============================================================================
+    get contents() {
+        return this._contents;
+    }
+    set contents(text) {
+        this._contents = text;
+        this._dirty = true;
+    }
+    get author() {
+        return this._author;
+    }
+    set author(name) {
+        this._author = name;
+        this._dirty = true;
+    }
+    // ============================================================================
+    // Appearance Properties
+    // ============================================================================
+    get color() {
+        return [...this._color];
+    }
+    set color(rgb) {
+        if (rgb.length === 3) {
+            this._color = [...rgb];
+            this._dirty = true;
+        }
+    }
+    get interiorColor() {
+        return [...this._interiorColor];
+    }
+    set interiorColor(rgb) {
+        if (rgb.length === 3 || rgb.length === 0) {
+            this._interiorColor = [...rgb];
+            this._dirty = true;
+        }
+    }
+    get borderWidth() {
+        return this._borderWidth;
+    }
+    set borderWidth(width) {
+        this._borderWidth = Math.max(0, width);
+        this._dirty = true;
+    }
+    get opacity() {
+        return this._opacity;
+    }
+    set opacity(alpha) {
+        this._opacity = Math.max(0, Math.min(1, alpha));
+        this._dirty = true;
+    }
+    // ============================================================================
+    // Line Annotation Properties
+    // ============================================================================
+    get lineStart() {
+        return this._lineStart;
+    }
+    get lineEnd() {
+        return this._lineEnd;
+    }
+    setLine(start, end) {
+        this._lineStart = Point.from(start);
+        this._lineEnd = Point.from(end);
+        this._dirty = true;
+    }
+    getLine() {
+        return [this._lineStart, this._lineEnd];
+    }
+    // ============================================================================
+    // Popup
+    // ============================================================================
+    get hasPopup() {
+        return this._hasPopup;
+    }
+    set hasPopup(value) {
+        this._hasPopup = value;
+        this._dirty = true;
+    }
+    // ============================================================================
+    // Dirty Tracking
+    // ============================================================================
+    get isDirty() {
+        return this._dirty;
+    }
+    clearDirty() {
+        this._dirty = false;
+    }
+    /**
+     * Update the annotation (mark for re-rendering)
+     */
+    update() {
+        this._dirty = true;
+    }
+    // ============================================================================
+    // Validation
+    // ============================================================================
+    isValid() {
+        // Check if annotation has valid properties
+        if (!this._rect || this._rect.isEmpty) {
+            return false;
+        }
+        if (this._opacity < 0 || this._opacity > 1) {
+            return false;
+        }
+        if (this._borderWidth < 0) {
+            return false;
+        }
+        return true;
+    }
+    // ============================================================================
+    // Type-specific factory methods
+    // ============================================================================
+    /**
+     * Create a text note annotation
+     */
+    static createText(rect, contents = '', author = '') {
+        const annot = new Annotation(AnnotationType.Text, rect);
+        annot.contents = contents;
+        annot.author = author;
+        return annot;
+    }
+    /**
+     * Create a highlight annotation
+     */
+    static createHighlight(rect, color = [1, 1, 0]) {
+        const annot = new Annotation(AnnotationType.Highlight, rect);
+        annot.color = color;
+        annot.opacity = 0.5;
+        return annot;
+    }
+    /**
+     * Create an underline annotation
+     */
+    static createUnderline(rect, color = [1, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Underline, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a strikeout annotation
+     */
+    static createStrikeOut(rect, color = [1, 0, 0]) {
+        const annot = new Annotation(AnnotationType.StrikeOut, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a squiggly underline annotation
+     */
+    static createSquiggly(rect, color = [1, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Squiggly, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a line annotation
+     */
+    static createLine(rect, start, end, color = [0, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Line, rect);
+        annot.setLine(start, end);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a square annotation
+     */
+    static createSquare(rect, color = [0, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Square, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a circle annotation
+     */
+    static createCircle(rect, color = [0, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Circle, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create an ink annotation (freehand drawing)
+     */
+    static createInk(rect, color = [0, 0, 0]) {
+        const annot = new Annotation(AnnotationType.Ink, rect);
+        annot.color = color;
+        return annot;
+    }
+    /**
+     * Create a stamp annotation
+     */
+    static createStamp(rect, stampText = 'Approved') {
+        const annot = new Annotation(AnnotationType.Stamp, rect);
+        annot.contents = stampText;
+        return annot;
+    }
+    /**
+     * Create a free text annotation
+     */
+    static createFreeText(rect, text = '') {
+        const annot = new Annotation(AnnotationType.FreeText, rect);
+        annot.contents = text;
+        return annot;
+    }
+}
+/**
+ * Annotation list manager for a page
+ */
+export class AnnotationList {
+    _annotations = [];
+    constructor() { }
+    /**
+     * Add an annotation
+     */
+    add(annot) {
+        this._annotations.push(annot);
+    }
+    /**
+     * Delete an annotation
+     */
+    delete(annot) {
+        const index = this._annotations.indexOf(annot);
+        if (index >= 0) {
+            this._annotations.splice(index, 1);
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Get annotation count
+     */
+    get count() {
+        return this._annotations.length;
+    }
+    /**
+     * Get annotation by index
+     */
+    get(index) {
+        return this._annotations[index];
+    }
+    /**
+     * Get first annotation
+     */
+    first() {
+        return this._annotations[0];
+    }
+    /**
+     * Get next annotation after the given one
+     */
+    next(current) {
+        const index = this._annotations.indexOf(current);
+        if (index >= 0 && index < this._annotations.length - 1) {
+            return this._annotations[index + 1];
+        }
+        return undefined;
+    }
+    /**
+     * Get all annotations
+     */
+    getAll() {
+        return [...this._annotations];
+    }
+    /**
+     * Clear all annotations
+     */
+    clear() {
+        this._annotations = [];
+    }
+    /**
+     * Iterate over annotations
+     */
+    *[Symbol.iterator]() {
+        for (const annot of this._annotations) {
+            yield annot;
+        }
+    }
+}
+//# sourceMappingURL=annot.js.map