@ingglish/dom 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,155 @@
+import { OutputFormat, TranslatedToken } from '@ingglish/phonemes';
+
+/**
+ * Apply pre-computed translations to DOM.
+ */
+/**
+ * Options for applying pre-computed translations.
+ */
+interface ApplyTranslationsOptions {
+    /** Number of text nodes to process per animation frame */
+    chunkSize?: number;
+    /** Callback for progress updates */
+    onProgress?: (processed: number, total: number) => void;
+    /** Whether to show tooltips with original text on hover */
+    showTooltips?: boolean;
+    /** Pre-collected text nodes (avoids re-traversing DOM) */
+    textNodes?: Text[];
+}
+/**
+ * Applies pre-computed translations to a DOM tree.
+ * This is designed for use cases where translations are fetched externally
+ * (e.g., from a service worker via message passing).
+ *
+ * @param root The root element to translate
+ * @param translations Map of lowercase words to their translations
+ * @param options Configuration options
+ */
+declare function applyTranslationsMap(root: Document | Element, translations: Record<string, string>, options?: ApplyTranslationsOptions): Promise<void>;
+
+/**
+ * DOM restoration utilities.
+ */
+/**
+ * Restores original text content that was translated.
+ * Replaces tooltip spans with their original text to preserve DOM structure.
+ *
+ * @param root The root element to restore
+ */
+declare function restoreDOM(root: Document | Element): void;
+
+/**
+ * Shared types for @ingglish/dom
+ */
+
+/**
+ * Configuration options for DOM translation.
+ */
+interface DOMTranslatorOptions {
+    /**
+     * Enable chunked DOM updates using requestAnimationFrame for smooth rendering.
+     * Prevents UI freezes on large pages.
+     * @default false
+     */
+    chunked?: boolean;
+    /**
+     * Number of text nodes to process per animation frame when chunked is enabled.
+     * @default 100
+     */
+    chunkSize?: number;
+    /**
+     * Callback for progress updates during translation.
+     */
+    onProgress?: (processed: number, total: number) => void;
+    /**
+     * Output format for translations.
+     * @default 'ingglish'
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * Whether to show tooltips with original English words on hover.
+     * When enabled, translated words are wrapped in spans with data-original attributes.
+     * @default false
+     */
+    showTooltips?: boolean;
+    /**
+     * CSS class names to skip during translation.
+     * @default ['no-translate', 'notranslate']
+     */
+    skipClasses?: string[];
+    /**
+     * HTML tag names to skip during translation.
+     * @default ['SCRIPT', 'STYLE', 'CODE', 'PRE', 'KBD', 'SAMP', 'VAR', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SVG', 'MATH', 'CANVAS']
+     */
+    skipTags?: string[];
+    /**
+     * Whether to translate attributes like title, alt, placeholder, aria-label.
+     * @default true
+     */
+    translateAttributes?: boolean;
+    /**
+     * Custom token-mapping translation function. When provided, used instead of
+     * the built-in English→Ingglish translateSyncWithMapping(). Returns structured
+     * tokens with original/translated text and match status. Enables foreign
+     * language translation with full tooltip support.
+     */
+    translateWithMappingFn?: (text: string, format: OutputFormat) => TranslatedToken[];
+}
+
+/**
+ * Core DOM translation functionality.
+ */
+
+/**
+ * Translates all text content within a DOM element (async, auto-loads dictionary).
+ * This is the recommended entry point for DOM translation.
+ */
+declare function translateDOM(root: Document | Element, options?: DOMTranslatorOptions): Promise<void>;
+
+/**
+ * Extracts all unique words from an array of text nodes.
+ * Uses a single Set to collect and deduplicate in one pass.
+ *
+ * @param textNodes - Array of DOM text nodes to extract words from
+ * @returns Array of unique lowercase words across all nodes
+ */
+declare function extractWordsFromNodes(textNodes: Text[]): string[];
+
+/**
+ * Skip rules for DOM translation.
+ * Determines which elements and text nodes should be skipped.
+ */
+/**
+ * Default tags to skip during translation.
+ * These typically contain code, scripts, or non-translatable content.
+ */
+declare const DEFAULT_SKIP_TAGS: string[];
+/**
+ * Default CSS classes to skip during translation.
+ * Common conventions for marking content as non-translatable.
+ */
+declare const DEFAULT_SKIP_CLASSES: string[];
+
+/**
+ * Text node collection utilities.
+ */
+/**
+ * Collects all translatable text nodes from a DOM tree.
+ * Skips elements based on tags, classes, and data attributes.
+ *
+ * Optimized to use FILTER_REJECT on skip elements, which skips entire subtrees
+ * instead of checking each text node's parent chain individually.
+ */
+declare function collectTextNodes(root: Document | Element, skipTags?: string[], skipClasses?: string[]): Text[];
+
+/**
+ * Injects tooltip behavior: creates tooltip divs on hover,
+ * positioned with position:fixed to escape overflow:hidden ancestors.
+ */
+declare function injectTooltipBehavior(targetDoc?: Document): void;
+/**
+ * Injects tooltip styles into the document if not already present.
+ */
+declare function injectTooltipStyles(targetDoc?: Document): void;
+
+export { DEFAULT_SKIP_CLASSES, DEFAULT_SKIP_TAGS, applyTranslationsMap, collectTextNodes, extractWordsFromNodes, injectTooltipBehavior, injectTooltipStyles, restoreDOM, translateDOM };

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import { OutputFormat, TranslatedToken } from '@ingglish/phonemes';
+
+/**
+ * Apply pre-computed translations to DOM.
+ */
+/**
+ * Options for applying pre-computed translations.
+ */
+interface ApplyTranslationsOptions {
+    /** Number of text nodes to process per animation frame */
+    chunkSize?: number;
+    /** Callback for progress updates */
+    onProgress?: (processed: number, total: number) => void;
+    /** Whether to show tooltips with original text on hover */
+    showTooltips?: boolean;
+    /** Pre-collected text nodes (avoids re-traversing DOM) */
+    textNodes?: Text[];
+}
+/**
+ * Applies pre-computed translations to a DOM tree.
+ * This is designed for use cases where translations are fetched externally
+ * (e.g., from a service worker via message passing).
+ *
+ * @param root The root element to translate
+ * @param translations Map of lowercase words to their translations
+ * @param options Configuration options
+ */
+declare function applyTranslationsMap(root: Document | Element, translations: Record<string, string>, options?: ApplyTranslationsOptions): Promise<void>;
+
+/**
+ * DOM restoration utilities.
+ */
+/**
+ * Restores original text content that was translated.
+ * Replaces tooltip spans with their original text to preserve DOM structure.
+ *
+ * @param root The root element to restore
+ */
+declare function restoreDOM(root: Document | Element): void;
+
+/**
+ * Shared types for @ingglish/dom
+ */
+
+/**
+ * Configuration options for DOM translation.
+ */
+interface DOMTranslatorOptions {
+    /**
+     * Enable chunked DOM updates using requestAnimationFrame for smooth rendering.
+     * Prevents UI freezes on large pages.
+     * @default false
+     */
+    chunked?: boolean;
+    /**
+     * Number of text nodes to process per animation frame when chunked is enabled.
+     * @default 100
+     */
+    chunkSize?: number;
+    /**
+     * Callback for progress updates during translation.
+     */
+    onProgress?: (processed: number, total: number) => void;
+    /**
+     * Output format for translations.
+     * @default 'ingglish'
+     */
+    outputFormat?: OutputFormat;
+    /**
+     * Whether to show tooltips with original English words on hover.
+     * When enabled, translated words are wrapped in spans with data-original attributes.
+     * @default false
+     */
+    showTooltips?: boolean;
+    /**
+     * CSS class names to skip during translation.
+     * @default ['no-translate', 'notranslate']
+     */
+    skipClasses?: string[];
+    /**
+     * HTML tag names to skip during translation.
+     * @default ['SCRIPT', 'STYLE', 'CODE', 'PRE', 'KBD', 'SAMP', 'VAR', 'NOSCRIPT', 'TEXTAREA', 'INPUT', 'SVG', 'MATH', 'CANVAS']
+     */
+    skipTags?: string[];
+    /**
+     * Whether to translate attributes like title, alt, placeholder, aria-label.
+     * @default true
+     */
+    translateAttributes?: boolean;
+    /**
+     * Custom token-mapping translation function. When provided, used instead of
+     * the built-in English→Ingglish translateSyncWithMapping(). Returns structured
+     * tokens with original/translated text and match status. Enables foreign
+     * language translation with full tooltip support.
+     */
+    translateWithMappingFn?: (text: string, format: OutputFormat) => TranslatedToken[];
+}
+
+/**
+ * Core DOM translation functionality.
+ */
+
+/**
+ * Translates all text content within a DOM element (async, auto-loads dictionary).
+ * This is the recommended entry point for DOM translation.
+ */
+declare function translateDOM(root: Document | Element, options?: DOMTranslatorOptions): Promise<void>;
+
+/**
+ * Extracts all unique words from an array of text nodes.
+ * Uses a single Set to collect and deduplicate in one pass.
+ *
+ * @param textNodes - Array of DOM text nodes to extract words from
+ * @returns Array of unique lowercase words across all nodes
+ */
+declare function extractWordsFromNodes(textNodes: Text[]): string[];
+
+/**
+ * Skip rules for DOM translation.
+ * Determines which elements and text nodes should be skipped.
+ */
+/**
+ * Default tags to skip during translation.
+ * These typically contain code, scripts, or non-translatable content.
+ */
+declare const DEFAULT_SKIP_TAGS: string[];
+/**
+ * Default CSS classes to skip during translation.
+ * Common conventions for marking content as non-translatable.
+ */
+declare const DEFAULT_SKIP_CLASSES: string[];
+
+/**
+ * Text node collection utilities.
+ */
+/**
+ * Collects all translatable text nodes from a DOM tree.
+ * Skips elements based on tags, classes, and data attributes.
+ *
+ * Optimized to use FILTER_REJECT on skip elements, which skips entire subtrees
+ * instead of checking each text node's parent chain individually.
+ */
+declare function collectTextNodes(root: Document | Element, skipTags?: string[], skipClasses?: string[]): Text[];
+
+/**
+ * Injects tooltip behavior: creates tooltip divs on hover,
+ * positioned with position:fixed to escape overflow:hidden ancestors.
+ */
+declare function injectTooltipBehavior(targetDoc?: Document): void;
+/**
+ * Injects tooltip styles into the document if not already present.
+ */
+declare function injectTooltipStyles(targetDoc?: Document): void;
+
+export { DEFAULT_SKIP_CLASSES, DEFAULT_SKIP_TAGS, applyTranslationsMap, collectTextNodes, extractWordsFromNodes, injectTooltipBehavior, injectTooltipStyles, restoreDOM, translateDOM };