@lexmata/micropdf 0.4.0

package/dist/text.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Text - PDF text object handling and layout
+ *
+ * This module provides comprehensive support for working with text in PDF documents,
+ * including text layout, glyph positioning, font management, and structured text extraction.
+ *
+ * This module provides 100% API compatibility with MuPDF's text operations.
+ *
+ * @module text
+ * @example
+ * ```typescript
+ * import { Text, Language, Matrix } from 'micropdf';
+ *
+ * // Create a text object
+ * const text = Text.create();
+ *
+ * // Set language for text processing
+ * text.setLanguage(Language.en);
+ *
+ * // Add glyphs (from font)
+ * text.showGlyph('Arial', 12, Matrix.identity(), 65, 0x0041, 0); // 'A'
+ *
+ * // Get bounding box
+ * const bounds = text.getBounds();
+ * console.log(`Text spans ${bounds.width} x ${bounds.height}`);
+ *
+ * // Walk through text structure
+ * text.walk({
+ *   beginSpan(font, size, wmode, trm) {
+ *     console.log(`Span: ${font} @ ${size}pt`);
+ *   },
+ *   showGlyph(x, y, glyph, unicode) {
+ *     console.log(`Glyph ${glyph} at (${x}, ${y})`);
+ *   }
+ * });
+ *
+ * // Clean up
+ * text.drop();
+ * ```
+ */
+import { Rect, Matrix, type MatrixLike } from './geometry.js';
+/**
+ * Language codes for text handling.
+ *
+ * These language codes are used to assist with text extraction, hyphenation,
+ * and language-specific text processing in PDF documents.
+ *
+ * @enum {number}
+ * @example
+ * ```typescript
+ * const text = Text.create();
+ *
+ * // Set English
+ * text.setLanguage(Language.en);
+ *
+ * // Set Spanish
+ * text.setLanguage(Language.es);
+ *
+ * // Set Chinese
+ * text.setLanguage(Language.zh);
+ *
+ * // Check current language
+ * if (text.getLanguage() === Language.ja) {
+ *   console.log('Japanese text');
+ * }
+ * ```
+ */
+export declare enum Language {
+    /** No language set or unknown language */
+    UNSET = 0,
+    /** English (en) */
+    en = 1,
+    /** Spanish (es) */
+    es = 2,
+    /** Chinese (zh) */
+    zh = 3,
+    /** French (fr) */
+    fr = 4,
+    /** German (de) */
+    de = 5,
+    /** Japanese (ja) */
+    ja = 6,
+    /** Korean (ko) */
+    ko = 7,
+    /** Russian (ru) */
+    ru = 8,
+    /** Arabic (ar) */
+    ar = 9,
+    /** Portuguese (pt) */
+    pt = 10,
+    /** Italian (it) */
+    it = 11,
+    /** Dutch (nl) */
+    nl = 12,
+    /** Swedish (sv) */
+    sv = 13,
+    /** Polish (pl) */
+    pl = 14,
+    /** Turkish (tr) */
+    tr = 15
+}
+/**
+ * A text span representing a run of text with consistent formatting.
+ *
+ * Text spans group glyphs that share the same font, size, and rendering properties.
+ * They are the basic unit of text layout in PDF documents.
+ *
+ * @interface TextSpan
+ * @example
+ * ```typescript
+ * const span: TextSpan = {
+ *   font: 'Arial',
+ *   size: 12,
+ *   wmode: 0, // Horizontal
+ *   trm: Matrix.identity(),
+ *   items: [
+ *     { x: 10, y: 20, glyph: 65, unicode: 0x0041 }, // 'A'
+ *     { x: 20, y: 20, glyph: 66, unicode: 0x0042 }  // 'B'
+ *   ]
+ * };
+ * ```
+ */
+export interface TextSpan {
+    /** The font name (e.g., "Arial", "Times-Roman") */
+    font: string;
+    /** The font size in points */
+    size: number;
+    /** Writing mode: 0 = horizontal, 1 = vertical */
+    wmode: number;
+    /** Text rendering matrix for transformations */
+    trm: Matrix;
+    /** Individual glyphs/characters in this span */
+    items: TextItem[];
+}
+/**
+ * A text item representing a single glyph or character.
+ *
+ * Text items contain the glyph identifier, Unicode codepoint, and position
+ * information for individual characters.
+ *
+ * @interface TextItem
+ * @example
+ * ```typescript
+ * const item: TextItem = {
+ *   x: 100.5,
+ *   y: 200.3,
+ *   glyph: 65,      // Glyph ID in the font
+ *   unicode: 0x0041 // Unicode codepoint for 'A'
+ * };
+ * ```
+ */
+export interface TextItem {
+    /** X-coordinate of the glyph position */
+    x: number;
+    /** Y-coordinate of the glyph position */
+    y: number;
+    /** Glyph identifier in the font */
+    glyph: number;
+    /** Unicode codepoint of the character */
+    unicode: number;
+}
+/**
+ * Text walker interface for iterating through text structure.
+ *
+ * Text walkers provide a callback-based API for traversing the hierarchical
+ * structure of text objects. This is useful for custom text processing,
+ * analysis, and rendering.
+ *
+ * @interface TextWalker
+ * @example
+ * ```typescript
+ * const walker: TextWalker = {
+ *   beginSpan(font, size, wmode, trm) {
+ *     console.log(`Begin span: ${font} @ ${size}pt`);
+ *   },
+ *   endSpan() {
+ *     console.log('End span');
+ *   },
+ *   showGlyph(x, y, glyph, unicode) {
+ *     const char = String.fromCodePoint(unicode);
+ *     console.log(`Glyph '${char}' at (${x}, ${y})`);
+ *   }
+ * };
+ *
+ * text.walk(walker);
+ * ```
+ */
+export interface TextWalker {
+    /**
+     * Called when entering a new text span.
+     * @param font - The font name
+     * @param size - The font size in points
+     * @param wmode - Writing mode (0=horizontal, 1=vertical)
+     * @param trm - Text rendering matrix
+     */
+    beginSpan?(font: string, size: number, wmode: number, trm: Matrix): void;
+    /**
+     * Called when leaving a text span.
+     */
+    endSpan?(): void;
+    /**
+     * Called for each glyph in the text.
+     * @param x - X-coordinate
+     * @param y - Y-coordinate
+     * @param glyph - Glyph ID
+     * @param unicode - Unicode codepoint
+     */
+    showGlyph(x: number, y: number, glyph: number, unicode: number): void;
+}
+/**
+ * A PDF text object for structured text layout and rendering.
+ *
+ * Text objects provide low-level control over text positioning, font selection,
+ * and glyph rendering. They maintain a structured representation of text with
+ * spans and items for precise layout control.
+ *
+ * **Reference Counting**: Text objects use manual reference counting. Call `keep()`
+ * to increment the reference count and `drop()` to decrement it.
+ *
+ * @class Text
+ * @example
+ * ```typescript
+ * // Create and configure text object
+ * const text = Text.create();
+ * text.setLanguage(Language.en);
+ *
+ * // Add text with font and positioning
+ * const font = 'Arial';
+ * const size = 12;
+ * const matrix = Matrix.translate(100, 200);
+ *
+ * // Show individual glyphs
+ * 'Hello'.split('').forEach((char, i) => {
+ *   const glyph = char.charCodeAt(0);
+ *   const unicode = char.codePointAt(0)!;
+ *   text.showGlyph(font, size, matrix, glyph, unicode);
+ * });
+ *
+ * // Get bounding box
+ * const bounds = text.getBounds();
+ * console.log(`Text size: ${bounds.width} x ${bounds.height}`);
+ *
+ * // Walk through structure
+ * text.walk({
+ *   showGlyph(x, y, glyph, unicode) {
+ *     console.log(`Character: ${String.fromCodePoint(unicode)}`);
+ *   }
+ * });
+ *
+ * // Clean up
+ * text.drop();
+ * ```
+ */
+export declare class Text {
+    private _spans;
+    private _language;
+    private _refCount;
+    private _currentSpan;
+    constructor(_handle?: any);
+    /**
+     * Create a new text object
+     */
+    static create(): Text;
+    keep(): this;
+    drop(): void;
+    /**
+     * Clone this text object
+     */
+    clone(): Text;
+    get language(): number;
+    set language(lang: number);
+    /**
+     * Get the language code
+     */
+    getLanguage(): number;
+    /**
+     * Set the language code
+     */
+    setLanguage(lang: number): void;
+    /**
+     * Begin a new text span
+     */
+    private beginSpan;
+    /**
+     * End the current text span
+     */
+    private endSpan;
+    /**
+     * Show a single glyph
+     */
+    showGlyph(font: string, size: number, trm: MatrixLike, glyph: number, unicode: number, wmode?: number): void;
+    /**
+     * Show a string of text
+     */
+    showString(font: string, size: number, trm: MatrixLike, text: string, wmode?: number): void;
+    /**
+     * Calculate the bounding box of all text
+     */
+    getBounds(ctm?: MatrixLike): Rect;
+    /**
+     * Count number of text spans
+     */
+    countSpans(): number;
+    /**
+     * Count total number of items (glyphs/characters)
+     */
+    countItems(): number;
+    /**
+     * Clear all text
+     */
+    clear(): void;
+    /**
+     * Check if text object is valid
+     */
+    isValid(): boolean;
+    /**
+     * Check if text is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Walk through all text spans and items
+     */
+    walk(walker: TextWalker): void;
+    /**
+     * Extract text content as plain string
+     */
+    extractText(): string;
+    /**
+     * Get all spans
+     */
+    getSpans(): TextSpan[];
+    /**
+     * Get span by index
+     */
+    getSpan(index: number): TextSpan | undefined;
+}
+//# sourceMappingURL=text.d.ts.map

package/dist/text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.d.ts","sourceRoot":"","sources":["../src/text.ts"],"names":[],"mappings":"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"}