@ingglish/dom 0.1.0

package/dist/index.mjs

@@ -0,0 +1,572 @@
+// src/translate/apply-map.ts
+import { applyCasePattern as applyCasePattern2, detectCasePattern as detectCasePattern2, normalizeApostrophes as normalizeApostrophes3 } from "@ingglish/normalize";
+
+// src/constants.ts
+var WORD_SPAN_CLASS = "ingglish-word";
+var TOOLTIP_STYLES_ID = "ingglish-tooltip-styles";
+var ATTR_ORIGINAL_WORD = "data-ingglish-orig";
+var ATTR_ORIGINAL_CONTENT = "data-ingglish-original";
+var ATTR_SKIP = "data-ingglish-skip";
+var ATTR_ORIGINAL_PREFIX = "data-ingglish-original-";
+var FORMAT_DIFF_CLASS = "ingglish-format-diff";
+var NOT_FOUND_CLASS = "ingglish-not-found";
+
+// src/traversal/browser.ts
+function isBrowser() {
+  return typeof document !== "undefined" && globalThis.window !== void 0;
+}
+function requireBrowser() {
+  if (!isBrowser()) {
+    throw new Error("DOM translation requires a browser environment");
+  }
+}
+
+// src/traversal/extract.ts
+import { normalizeApostrophes, WORD_SPLIT_REGEX, WORD_TEST_REGEX } from "@ingglish/normalize";
+function extractWordsFromNodes(textNodes) {
+  const uniqueWords = /* @__PURE__ */ new Set();
+  for (const node of textNodes) {
+    const text = node.textContent ?? "";
+    const normalized = normalizeApostrophes(text);
+    const tokens = normalized.split(WORD_SPLIT_REGEX);
+    for (const token of tokens) {
+      if (token !== "" && WORD_TEST_REGEX.test(token)) {
+        uniqueWords.add(token.toLowerCase());
+      }
+    }
+  }
+  return [...uniqueWords];
+}
+
+// src/traversal/skip-rules.ts
+var DEFAULT_SKIP_TAGS = [
+  "SCRIPT",
+  "STYLE",
+  "CODE",
+  "PRE",
+  "KBD",
+  "SAMP",
+  "VAR",
+  "NOSCRIPT",
+  "TEXTAREA",
+  "INPUT",
+  "SVG",
+  "MATH",
+  "CANVAS"
+];
+var DEFAULT_SKIP_TAGS_SET = new Set(DEFAULT_SKIP_TAGS);
+var DEFAULT_SKIP_CLASSES = ["no-translate", "notranslate"];
+var DEFAULT_SKIP_CLASSES_SET = new Set(DEFAULT_SKIP_CLASSES);
+var TRANSLATABLE_ATTRIBUTES = [
+  "title",
+  "alt",
+  "placeholder",
+  "aria-label",
+  "aria-description"
+];
+function shouldSkipElement(element, skipTags, skipClasses) {
+  const tagsSet = skipTags === DEFAULT_SKIP_TAGS ? DEFAULT_SKIP_TAGS_SET : new Set(skipTags);
+  const classesSet = skipClasses === DEFAULT_SKIP_CLASSES ? DEFAULT_SKIP_CLASSES_SET : new Set(skipClasses);
+  return checkElementSkip(element, tagsSet, classesSet);
+}
+function checkElementSkip(element, skipTagsSet, skipClassesSet) {
+  if (skipTagsSet.has(element.tagName)) {
+    return true;
+  }
+  const classList = element.classList;
+  const classCount = classList.length;
+  for (let i = 0; i < classCount; i++) {
+    if (skipClassesSet.has(classList[i])) {
+      return true;
+    }
+  }
+  if (element.getAttribute("contenteditable") === "true") {
+    return true;
+  }
+  if (element.hasAttribute(ATTR_SKIP)) {
+    return true;
+  }
+  if (element.hasAttribute(ATTR_ORIGINAL_WORD)) {
+    return true;
+  }
+  return false;
+}
+
+// src/traversal/text-nodes.ts
+function collectTextNodes(root, skipTags = DEFAULT_SKIP_TAGS, skipClasses = DEFAULT_SKIP_CLASSES) {
+  requireBrowser();
+  const textNodes = [];
+  const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, {
+    acceptNode(node) {
+      if (node.nodeType === Node.ELEMENT_NODE) {
+        return shouldSkipElement(node, skipTags, skipClasses) ? NodeFilter.FILTER_REJECT : NodeFilter.FILTER_SKIP;
+      }
+      const text = node.textContent?.trim() ?? "";
+      return text.length > 0 ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+    }
+  });
+  while (walker.nextNode()) {
+    if (walker.currentNode.nodeType === Node.TEXT_NODE) {
+      textNodes.push(walker.currentNode);
+    }
+  }
+  return textNodes;
+}
+
+// src/traversal/tooltip.ts
+var TOOLTIP_BEHAVIOR_ID = "ingglish-tooltip-behavior";
+var TOOLTIP_STYLES = `
+.${WORD_SPAN_CLASS} {
+  cursor: help;
+}
+
+.ingglish-tooltip {
+  position: fixed !important;
+  background: #333 !important;
+  color: #fff !important;
+  padding: 4px 8px !important;
+  border-radius: 4px !important;
+  font-size: 12px !important;
+  font-family: system-ui, -apple-system, sans-serif !important;
+  line-height: 1.4 !important;
+  white-space: nowrap !important;
+  z-index: 2147483647 !important;
+  pointer-events: none !important;
+  opacity: 0;
+  animation: ingglish-tooltip-fade-in 0.15s ease-out forwards;
+}
+
+.ingglish-tooltip::after {
+  content: '' !important;
+  position: absolute !important;
+  left: var(--arrow-left, 50%) !important;
+  transform: translateX(-50%) !important;
+  border: 5px solid transparent !important;
+}
+
+.ingglish-tooltip--above::after {
+  top: 100% !important;
+  border-top-color: #333 !important;
+}
+
+.ingglish-tooltip--below::after {
+  bottom: 100% !important;
+  border-bottom-color: #333 !important;
+}
+
+@keyframes ingglish-tooltip-fade-in {
+  to { opacity: 1; }
+}
+
+.${FORMAT_DIFF_CLASS} {
+  border-bottom: 1.5px dotted currentColor;
+}
+
+.${NOT_FOUND_CLASS} {
+  opacity: 0.55;
+  text-decoration: underline dotted currentColor;
+  text-decoration-thickness: 1.5px;
+  text-underline-offset: 0.2em;
+}
+`;
+function injectTooltipBehavior(targetDoc = document) {
+  if (targetDoc.documentElement.hasAttribute(`data-${TOOLTIP_BEHAVIOR_ID}`)) {
+    return;
+  }
+  targetDoc.documentElement.setAttribute(`data-${TOOLTIP_BEHAVIOR_ID}`, "true");
+  let activeTooltip = null;
+  let activeWord = null;
+  function removeTooltip() {
+    if (activeTooltip) {
+      activeTooltip.remove();
+      activeTooltip = null;
+      activeWord = null;
+    }
+  }
+  targetDoc.addEventListener(
+    "mouseover",
+    (e) => {
+      const word = e.target.closest?.(`.${WORD_SPAN_CLASS}`);
+      if (word === activeWord) {
+        return;
+      }
+      removeTooltip();
+      if (!word) {
+        return;
+      }
+      const orig = word.getAttribute(ATTR_ORIGINAL_WORD);
+      if (orig === null || orig === "") {
+        return;
+      }
+      const tooltip = targetDoc.createElement("div");
+      tooltip.className = "ingglish-tooltip";
+      tooltip.textContent = orig;
+      targetDoc.body.append(tooltip);
+      activeTooltip = tooltip;
+      activeWord = word;
+      const wordRect = word.getBoundingClientRect();
+      const tipRect = tooltip.getBoundingClientRect();
+      const viewportWidth = targetDoc.defaultView?.innerWidth ?? 0;
+      const showAbove = wordRect.top > tipRect.height + 10;
+      tooltip.classList.add(showAbove ? "ingglish-tooltip--above" : "ingglish-tooltip--below");
+      const top = showAbove ? wordRect.top - tipRect.height - 5 : wordRect.bottom + 5;
+      tooltip.style.top = `${top}px`;
+      let left = wordRect.left + wordRect.width / 2 - tipRect.width / 2;
+      left = Math.max(4, Math.min(left, viewportWidth - tipRect.width - 4));
+      tooltip.style.left = `${left}px`;
+      const arrowLeft = wordRect.left + wordRect.width / 2 - left;
+      tooltip.style.setProperty("--arrow-left", `${arrowLeft}px`);
+    },
+    true
+  );
+  targetDoc.addEventListener("scroll", removeTooltip, true);
+}
+function injectTooltipStyles(targetDoc = document) {
+  if (targetDoc.querySelector(`#${TOOLTIP_STYLES_ID}`)) {
+    return;
+  }
+  const style = targetDoc.createElement("style");
+  style.id = TOOLTIP_STYLES_ID;
+  style.textContent = TOOLTIP_STYLES;
+  targetDoc.head?.append(style);
+}
+
+// src/translate/chunked.ts
+function processChunked(items, processFn, chunkSize, onProgress, syncThreshold = 0) {
+  const total = items.length;
+  if (total === 0) {
+    return Promise.resolve();
+  }
+  if (total <= syncThreshold) {
+    for (let i = 0; i < total; i++) {
+      processFn(items[i]);
+      if (onProgress) {
+        onProgress(i + 1, total);
+      }
+    }
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => {
+    let index = 0;
+    function processChunk() {
+      const endIndex = Math.min(index + chunkSize, total);
+      while (index < endIndex) {
+        processFn(items[index]);
+        index++;
+        if (onProgress) {
+          onProgress(index, total);
+        }
+      }
+      if (index < total) {
+        requestAnimationFrame(processChunk);
+      } else {
+        resolve();
+      }
+    }
+    requestAnimationFrame(processChunk);
+  });
+}
+
+// src/translate/tooltip-fragment.ts
+import { translateSyncWithMapping } from "ingglish";
+import {
+  applyCasePattern,
+  detectCasePattern,
+  normalizeApostrophes as normalizeApostrophes2,
+  WORD_SPLIT_REGEX as WORD_SPLIT_REGEX2,
+  WORD_TEST_REGEX as WORD_TEST_REGEX2
+} from "@ingglish/normalize";
+var templateSpan = null;
+function createTooltipFragment(text, format = "ingglish") {
+  const tokens = translateSyncWithMapping(text, { format });
+  const stdTokens = format === "ingglish" ? null : translateSyncWithMapping(text, { format: "ingglish" });
+  return buildTooltipFragment(
+    tokens.map((token, i) => {
+      if (token.isWord && token.original !== token.translated) {
+        const stdSpelling = stdTokens?.[i]?.translated;
+        const isDiff = stdSpelling !== void 0 && stdSpelling.toLowerCase() !== token.translated.toLowerCase();
+        const notFound = !token.matched;
+        const tooltip = isDiff ? `${token.original} (Ingglish: ${stdSpelling})` : token.original;
+        return { isDiff, notFound, text: token.translated, tooltip };
+      }
+      return { text: token.translated };
+    })
+  );
+}
+function createTooltipFragmentFromMap(text, translations) {
+  const normalized = normalizeApostrophes2(text);
+  const tokens = normalized.split(WORD_SPLIT_REGEX2);
+  return buildTooltipFragment(
+    tokens.filter(Boolean).map((token) => {
+      if (WORD_TEST_REGEX2.test(token)) {
+        const lowerToken = token.toLowerCase();
+        const translated = translations[lowerToken];
+        if (translated !== void 0 && translated !== lowerToken) {
+          const pattern = detectCasePattern(token);
+          return { text: applyCasePattern(translated, pattern, token), tooltip: token };
+        }
+      }
+      return { text: token };
+    })
+  );
+}
+function createTooltipFragmentFromTokens(tokens) {
+  return buildTooltipFragment(
+    tokens.map((token) => {
+      if (token.isWord && token.original !== token.translated) {
+        return { notFound: !token.matched, text: token.translated, tooltip: token.original };
+      }
+      if (token.isWord && !token.matched) {
+        return { notFound: true, text: token.translated, tooltip: token.original };
+      }
+      return { text: token.translated };
+    })
+  );
+}
+function buildTooltipFragment(items) {
+  const fragment = document.createDocumentFragment();
+  let pendingText = "";
+  for (const item of items) {
+    if (item.tooltip === void 0) {
+      pendingText += item.text;
+    } else {
+      if (pendingText) {
+        fragment.append(document.createTextNode(pendingText));
+        pendingText = "";
+      }
+      const span = getTemplateSpan().cloneNode(false);
+      span.setAttribute(ATTR_ORIGINAL_WORD, item.tooltip);
+      if (item.isDiff === true) {
+        span.classList.add(FORMAT_DIFF_CLASS);
+      }
+      if (item.notFound === true) {
+        span.classList.add(NOT_FOUND_CLASS);
+      }
+      span.textContent = item.text;
+      fragment.append(span);
+    }
+  }
+  if (pendingText) {
+    fragment.append(document.createTextNode(pendingText));
+  }
+  return fragment;
+}
+function getTemplateSpan() {
+  if (templateSpan === null) {
+    templateSpan = document.createElement("span");
+    templateSpan.className = WORD_SPAN_CLASS;
+  }
+  return templateSpan;
+}
+
+// src/translate/apply-map.ts
+var DEFAULT_CHUNK_SIZE = 100;
+var SYNC_THRESHOLD = 500;
+var WORD_REGEX = /(?<!\d)[a-zA-Z\u00C0-\u024F']+(?!\d)/g;
+function applyTranslationsMap(root, translations, options = {}) {
+  requireBrowser();
+  const {
+    chunkSize = DEFAULT_CHUNK_SIZE,
+    onProgress,
+    showTooltips = false,
+    textNodes: preCollectedNodes
+  } = options;
+  const targetDoc = root instanceof Document ? root : root.ownerDocument;
+  if (showTooltips && targetDoc !== null) {
+    injectTooltipStyles(targetDoc);
+    injectTooltipBehavior(targetDoc);
+  }
+  const textNodes = preCollectedNodes ?? collectTextNodes(root);
+  return processChunked(
+    textNodes,
+    (node) => {
+      processTextNode(node, translations, showTooltips);
+    },
+    chunkSize,
+    onProgress,
+    SYNC_THRESHOLD
+  );
+}
+function processTextNode(textNode, translations, showTooltips) {
+  const parent = textNode.parentElement;
+  if (parent && !parent.hasAttribute(ATTR_ORIGINAL_CONTENT)) {
+    parent.setAttribute(ATTR_ORIGINAL_CONTENT, textNode.textContent ?? "");
+  }
+  if (showTooltips) {
+    const fragment = createTooltipFragmentFromMap(textNode.textContent ?? "", translations);
+    textNode.replaceWith(fragment);
+  } else {
+    const text = textNode.textContent ?? "";
+    const normalized = normalizeApostrophes3(text);
+    let result = "";
+    let lastIndex = 0;
+    let match;
+    WORD_REGEX.lastIndex = 0;
+    while ((match = WORD_REGEX.exec(normalized)) !== null) {
+      result += normalized.slice(lastIndex, match.index);
+      lastIndex = match.index + match[0].length;
+      const word = match[0];
+      const translated = translations[word.toLowerCase()];
+      if (translated === void 0) {
+        result += word;
+      } else {
+        const pattern = detectCasePattern2(word);
+        result += applyCasePattern2(translated, pattern, word);
+      }
+    }
+    result += normalized.slice(lastIndex);
+    textNode.textContent = result;
+  }
+}
+
+// src/translate/restore.ts
+function restoreDOM(root) {
+  requireBrowser();
+  const wordSpans = Array.from(
+    root.querySelectorAll(`.${WORD_SPAN_CLASS}[${ATTR_ORIGINAL_WORD}]`)
+  );
+  for (const span of wordSpans) {
+    const originalWord = span.getAttribute(ATTR_ORIGINAL_WORD);
+    if (originalWord !== null) {
+      const textNode = document.createTextNode(originalWord);
+      span.replaceWith(textNode);
+    }
+  }
+  const elementsWithOriginal = Array.from(
+    root.querySelectorAll(`[${ATTR_ORIGINAL_CONTENT}]`)
+  );
+  for (const element of elementsWithOriginal) {
+    element.removeAttribute(ATTR_ORIGINAL_CONTENT);
+  }
+  const attrSelector = TRANSLATABLE_ATTRIBUTES.map(
+    (attr) => `[${ATTR_ORIGINAL_PREFIX}${attr}]`
+  ).join(",");
+  const elementsWithTranslatedAttrs = Array.from(root.querySelectorAll(attrSelector));
+  for (const element of elementsWithTranslatedAttrs) {
+    for (const attrName of TRANSLATABLE_ATTRIBUTES) {
+      const originalAttrName = `${ATTR_ORIGINAL_PREFIX}${attrName}`;
+      const originalValue = element.getAttribute(originalAttrName);
+      if (originalValue !== null) {
+        element.setAttribute(attrName, originalValue);
+        element.removeAttribute(originalAttrName);
+      }
+    }
+  }
+}
+
+// src/translate/translator.ts
+import { translate, translateSync } from "ingglish";
+var DEFAULT_CHUNK_SIZE2 = 100;
+async function translateDOM(root, options = {}) {
+  if (!options.translateWithMappingFn) {
+    await translate("");
+  }
+  const result = translateDOMSync(root, options);
+  if (result instanceof Promise) {
+    await result;
+  }
+}
+function translateDOMSync(root, options = {}) {
+  requireBrowser();
+  const {
+    chunked = false,
+    chunkSize = DEFAULT_CHUNK_SIZE2,
+    onProgress,
+    outputFormat = "ingglish",
+    showTooltips = false,
+    skipClasses = DEFAULT_SKIP_CLASSES,
+    skipTags = DEFAULT_SKIP_TAGS,
+    translateAttributes = true,
+    translateWithMappingFn
+  } = options;
+  const targetDoc = root instanceof Document ? root : root.ownerDocument;
+  if (showTooltips && targetDoc !== null) {
+    injectTooltipStyles(targetDoc);
+    injectTooltipBehavior(targetDoc);
+  }
+  const textNodes = collectTextNodes(root, skipTags, skipClasses);
+  const totalNodes = textNodes.length;
+  const customTranslateFn = translateWithMappingFn ? (text, format) => translateWithMappingFn(text, format).map((t) => t.translated).join("") : void 0;
+  if (translateAttributes) {
+    translateElementAttributes(root, skipTags, skipClasses, outputFormat, customTranslateFn);
+  }
+  if (chunked) {
+    return processChunked(
+      textNodes,
+      (node) => {
+        translateTextNode(
+          node,
+          showTooltips,
+          outputFormat,
+          customTranslateFn,
+          translateWithMappingFn
+        );
+      },
+      chunkSize,
+      onProgress
+    );
+  }
+  for (let i = 0; i < totalNodes; i++) {
+    translateTextNode(
+      textNodes[i],
+      showTooltips,
+      outputFormat,
+      customTranslateFn,
+      translateWithMappingFn
+    );
+    if (onProgress) {
+      onProgress(i + 1, totalNodes);
+    }
+  }
+}
+function translateElementAttributes(root, skipTags, skipClasses, format = "ingglish", customTranslateFn) {
+  const doTranslate = customTranslateFn ?? ((text, fmt) => translateSync(text, { format: fmt }));
+  const attrSelector = TRANSLATABLE_ATTRIBUTES.map((attr) => `[${attr}]`).join(",");
+  const elements = Array.from(root.querySelectorAll(attrSelector));
+  for (const element of elements) {
+    if (shouldSkipElement(element, skipTags, skipClasses)) {
+      continue;
+    }
+    for (const attrName of TRANSLATABLE_ATTRIBUTES) {
+      const attrValue = element.getAttribute(attrName);
+      if (attrValue !== null && attrValue.length > 0) {
+        const originalAttrName = `${ATTR_ORIGINAL_PREFIX}${attrName}`;
+        if (!element.hasAttribute(originalAttrName)) {
+          element.setAttribute(originalAttrName, attrValue);
+        }
+        element.setAttribute(attrName, doTranslate(attrValue, format));
+      }
+    }
+  }
+}
+function translateTextNode(textNode, showTooltips, outputFormat, customTranslateFn, customMappingFn) {
+  const originalText = textNode.textContent;
+  if (!originalText) {
+    return;
+  }
+  const parent = textNode.parentElement;
+  if (showTooltips) {
+    const fragment = customMappingFn ? createTooltipFragmentFromTokens(customMappingFn(originalText, outputFormat)) : createTooltipFragment(originalText, outputFormat);
+    if (parent && !parent.hasAttribute(ATTR_ORIGINAL_CONTENT)) {
+      parent.setAttribute(ATTR_ORIGINAL_CONTENT, originalText);
+    }
+    textNode.replaceWith(fragment);
+  } else {
+    if (parent && !parent.hasAttribute(ATTR_ORIGINAL_CONTENT)) {
+      parent.setAttribute(ATTR_ORIGINAL_CONTENT, originalText);
+    }
+    const doTranslate = customTranslateFn ?? ((text, fmt) => translateSync(text, { format: fmt }));
+    textNode.textContent = doTranslate(originalText, outputFormat);
+  }
+}
+export {
+  DEFAULT_SKIP_CLASSES,
+  DEFAULT_SKIP_TAGS,
+  applyTranslationsMap,
+  collectTextNodes,
+  extractWordsFromNodes,
+  injectTooltipBehavior,
+  injectTooltipStyles,
+  restoreDOM,
+  translateDOM
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@ingglish/dom",
+  "version": "0.1.0",
+  "description": "DOM translation utilities for Ingglish",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:fast": "tsup src/index.ts --format esm",
+    "lint": "eslint --cache src",
+    "test": "vitest run --no-color",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@ingglish/ipa": "^0.1.0",
+    "@ingglish/normalize": "^0.1.0",
+    "@ingglish/phonemes": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ingglish": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "jsdom": "^28.1.0",
+    "vite": "^7.3.1"
+  },
+  "keywords": [
+    "dom",
+    "translation",
+    "phonetic",
+    "english",
+    "browser"
+  ],
+  "author": "Paul Tarjan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ptarjan/ingglish.git",
+    "directory": "packages/dom"
+  },
+  "homepage": "https://github.com/ptarjan/ingglish#readme",
+  "bugs": {
+    "url": "https://github.com/ptarjan/ingglish/issues"
+  }
+}