@youversion/platform-core 1.20.1 → 1.21.0

package/dist/chunk-2Z2S2WY3.js

@@ -0,0 +1,245 @@
+// src/bible-html-transformer.ts
+var NON_BREAKING_SPACE = "\xA0";
+var FOOTNOTE_KEY_ATTR = "data-footnote-key";
+var NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
+var ALLOWED_TAGS = /* @__PURE__ */ new Set([
+  "DIV",
+  "P",
+  "SPAN",
+  "SUP",
+  "SUB",
+  "EM",
+  "STRONG",
+  "I",
+  "B",
+  "SMALL",
+  "BR",
+  "SECTION",
+  "TABLE",
+  "THEAD",
+  "TBODY",
+  "TR",
+  "TD",
+  "TH"
+]);
+var DROP_ENTIRELY_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "IFRAME",
+  "OBJECT",
+  "EMBED",
+  "SVG",
+  "MATH",
+  "FORM",
+  "INPUT",
+  "BUTTON",
+  "TEXTAREA",
+  "SELECT",
+  "TEMPLATE",
+  "LINK",
+  "META",
+  "BASE",
+  "NOSCRIPT"
+]);
+var ALLOWED_ATTRS = /* @__PURE__ */ new Set(["class", "v", "colspan", "rowspan", "dir", "usfm"]);
+function sanitizeBibleHtmlDocument(doc) {
+  const root = doc.body ?? doc.documentElement;
+  for (const el of Array.from(root.querySelectorAll("*"))) {
+    const tag = el.tagName;
+    if (DROP_ENTIRELY_TAGS.has(tag)) {
+      el.remove();
+      continue;
+    }
+    if (!ALLOWED_TAGS.has(tag)) {
+      el.replaceWith(...Array.from(el.childNodes));
+      continue;
+    }
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on")) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+      if (!ALLOWED_ATTRS.has(name) && !name.startsWith("data-")) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+function wrapVerseContent(doc) {
+  function wrapParagraphContent(doc2, paragraph, verseNum) {
+    const children = Array.from(paragraph.childNodes);
+    if (children.length === 0) return;
+    const wrapper = doc2.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstChild = children[0];
+    if (firstChild) {
+      paragraph.insertBefore(wrapper, firstChild);
+    }
+    children.forEach((child) => {
+      wrapper.appendChild(child);
+    });
+  }
+  function wrapParagraphsUntilBoundary(doc2, verseNum, startParagraph, endParagraph) {
+    if (!startParagraph) return;
+    let currentParagraph = startParagraph.nextElementSibling;
+    while (currentParagraph && currentParagraph !== endParagraph) {
+      const isHeading = currentParagraph.classList.contains("yv-h") || currentParagraph.matches(
+        ".s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r"
+      );
+      if (isHeading) {
+        currentParagraph = currentParagraph.nextElementSibling;
+        continue;
+      }
+      if (currentParagraph.querySelector(".yv-v[v]")) break;
+      if (currentParagraph.classList.contains("p") || currentParagraph.tagName === "P") {
+        wrapParagraphContent(doc2, currentParagraph, verseNum);
+      }
+      currentParagraph = currentParagraph.nextElementSibling;
+    }
+  }
+  function handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum) {
+    if (!currentParagraph) return;
+    if (!nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph);
+      return;
+    }
+    if (currentParagraph !== nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph, nextParagraph);
+    }
+  }
+  function processVerseMarker(marker, index, markers) {
+    const verseNum = marker.getAttribute("v");
+    if (!verseNum) return;
+    const nextMarker = markers[index + 1];
+    const nodesToWrap = collectNodesBetweenMarkers(marker, nextMarker);
+    if (nodesToWrap.length === 0) return;
+    const currentParagraph = marker.closest(".p, p, div.p");
+    const nextParagraph = nextMarker?.closest(".p, p, div.p") || null;
+    const doc2 = marker.ownerDocument;
+    wrapNodesInVerse(marker, verseNum, nodesToWrap);
+    handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum);
+  }
+  function wrapNodesInVerse(marker, verseNum, nodes) {
+    const wrapper = marker.ownerDocument.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstNode = nodes[0];
+    if (firstNode) {
+      marker.parentNode?.insertBefore(wrapper, firstNode);
+    }
+    nodes.forEach((node) => {
+      wrapper.appendChild(node);
+    });
+    marker.remove();
+  }
+  function shouldStopCollecting(node, endMarker) {
+    if (node === endMarker) return true;
+    if (endMarker && node.nodeType === 1 && node.contains(endMarker)) return true;
+    return false;
+  }
+  function shouldSkipNode(node) {
+    return node.nodeType === 1 && node.classList.contains("yv-h");
+  }
+  function collectNodesBetweenMarkers(startMarker, endMarker) {
+    const nodes = [];
+    let current = startMarker.nextSibling;
+    while (current && !shouldStopCollecting(current, endMarker)) {
+      if (shouldSkipNode(current)) {
+        current = current.nextSibling;
+        continue;
+      }
+      nodes.push(current);
+      current = current.nextSibling;
+    }
+    return nodes;
+  }
+  const verseMarkers = Array.from(doc.querySelectorAll(".yv-v[v]"));
+  verseMarkers.forEach(processVerseMarker);
+}
+function assignFootnoteKeys(doc) {
+  let introIdx = 0;
+  doc.querySelectorAll(".yv-n.f").forEach((fn) => {
+    const verseNum = fn.closest(".yv-v[v]")?.getAttribute("v");
+    fn.setAttribute(FOOTNOTE_KEY_ATTR, verseNum ?? `intro-${introIdx++}`);
+  });
+}
+function replaceFootnotesWithAnchors(doc, footnotes) {
+  for (const fn of footnotes) {
+    const key = fn.getAttribute(FOOTNOTE_KEY_ATTR);
+    if (!key) continue;
+    const prev = fn.previousSibling;
+    const next = fn.nextSibling;
+    const prevText = prev?.textContent ?? "";
+    const nextText = next?.textContent ?? "";
+    const prevNeedsSpace = prevText.length > 0 && !/\s$/.test(prevText);
+    const nextNeedsSpace = nextText.length > 0 && NEEDS_SPACE_BEFORE.test(nextText);
+    if (prevNeedsSpace && nextNeedsSpace && fn.parentNode) {
+      fn.parentNode.insertBefore(doc.createTextNode(" "), fn);
+    }
+    const anchor = doc.createElement("span");
+    anchor.setAttribute("data-verse-footnote", key);
+    anchor.setAttribute("data-verse-footnote-content", fn.innerHTML);
+    fn.replaceWith(anchor);
+  }
+}
+function addNbspToVerseLabels(doc) {
+  doc.querySelectorAll(".yv-vlbl").forEach((label) => {
+    const text = label.textContent || "";
+    if (!text.endsWith(NON_BREAKING_SPACE)) {
+      label.textContent = text + NON_BREAKING_SPACE;
+    }
+  });
+}
+function fixIrregularTables(doc) {
+  doc.querySelectorAll("table").forEach((table) => {
+    const rows = table.querySelectorAll("tr");
+    if (rows.length === 0) return;
+    let maxColumns = 0;
+    rows.forEach((row) => {
+      let count = 0;
+      row.querySelectorAll("td, th").forEach((cell) => {
+        count += parseInt(cell.getAttribute("colspan") || "1", 10);
+      });
+      maxColumns = Math.max(maxColumns, count);
+    });
+    if (maxColumns > 1) {
+      rows.forEach((row) => {
+        const cells = row.querySelectorAll("td, th");
+        if (cells.length === 1) {
+          const existing = parseInt(cells[0].getAttribute("colspan") || "1", 10);
+          if (existing < maxColumns) {
+            cells[0].setAttribute("colspan", maxColumns.toString());
+          }
+        }
+      });
+    }
+  });
+}
+function transformBibleHtml(html, options) {
+  const doc = options.parseHtml(html);
+  sanitizeBibleHtmlDocument(doc);
+  wrapVerseContent(doc);
+  assignFootnoteKeys(doc);
+  const footnotes = Array.from(doc.querySelectorAll(".yv-n.f"));
+  replaceFootnotesWithAnchors(doc, footnotes);
+  addNbspToVerseLabels(doc);
+  fixIrregularTables(doc);
+  const transformedHtml = options.serializeHtml(doc);
+  return { html: transformedHtml };
+}
+function transformBibleHtmlForBrowser(html) {
+  if (typeof globalThis.DOMParser === "undefined") {
+    throw new Error("DOMParser is required to transform Bible HTML in browser environments");
+  }
+  return transformBibleHtml(html, {
+    parseHtml: (h) => new DOMParser().parseFromString(h, "text/html"),
+    serializeHtml: (doc) => doc.body.innerHTML
+  });
+}
+
+export {
+  transformBibleHtml,
+  transformBibleHtmlForBrowser
+};

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(index_exports, {
   BOOK_CANON: () => BOOK_CANON,
   BOOK_IDS: () => BOOK_IDS,
   BibleClient: () => BibleClient,
+  CANON_IDS: () => CANON_IDS,
   DEFAULT_LICENSE_FREE_BIBLE_VERSION: () => DEFAULT_LICENSE_FREE_BIBLE_VERSION,
   HighlightsClient: () => HighlightsClient,
   LanguagesClient: () => LanguagesClient,
@@ -35,7 +36,8 @@ __export(index_exports, {
   YouVersionAPIUsers: () => YouVersionAPIUsers,
   YouVersionPlatformConfiguration: () => YouVersionPlatformConfiguration,
   YouVersionUserInfo: () => YouVersionUserInfo,
-  getAdjacentChapter: () => getAdjacentChapter
+  getAdjacentChapter: () => getAdjacentChapter,
+  transformBibleHtml: () => transformBibleHtml
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -203,6 +205,7 @@ var import_zod3 = require("zod");
 
 // src/utils/constants.ts
 var DEFAULT_LICENSE_FREE_BIBLE_VERSION = 3034;
+var CANON_IDS = ["old_testament", "new_testament", "deuterocanon"];
 var BOOK_IDS = [
   "GEN",
   "EXO",
@@ -444,7 +447,7 @@ var BibleChapterSchema = import_zod2.z.object({
 });
 
 // src/schemas/book.ts
-var CanonSchema = import_zod3.z.enum(["old_testament", "new_testament", "deuterocanon"]);
+var CanonSchema = import_zod3.z.enum(CANON_IDS);
 var BibleBookIntroSchema = import_zod3.z.object({
   /** Intro identifier */
   id: import_zod3.z.string(),
@@ -787,12 +790,18 @@ var BibleClient = class _BibleClient {
   /**
    * Fetches a passage (range of verses) from the Bible using the passages endpoint.
    * This is the new API format that returns HTML-formatted content.
+   *
+   * Note: The HTML returned from the API contains inline footnote content that should
+   * be transformed before rendering. Use `transformBibleHtml()` or
+   * `transformBibleHtmlForBrowser()` to clean up the HTML and extract footnotes.
+   *
    * @param versionId The version ID.
    * @param usfm The USFM reference (e.g., "JHN.3.1-2", "GEN.1", "JHN.3.16").
    * @param format The format to return ("html" or "text", default: "html").
    * @param include_headings Whether to include headings in the content.
    * @param include_notes Whether to include notes in the content.
    * @returns The requested BiblePassage object with HTML content.
+   *
    * @example
    * ```ts
    * // Get a single verse
@@ -803,6 +812,10 @@ var BibleClient = class _BibleClient {
    *
    * // Get an entire chapter
    * const chapter = await bibleClient.getPassage(3034, "GEN.1");
+   *
+   * // Transform HTML before rendering
+   * const passage = await bibleClient.getPassage(3034, "JHN.3.16", "html", true, true);
+   * const transformed = transformBibleHtmlForBrowser(passage.content);
    * ```
    */
   async getPassage(versionId, usfm, format = "html", include_headings, include_notes) {
@@ -1730,12 +1743,245 @@ function lastCanonicalOfPreviousBook(books, bookIndex) {
   }
   return null;
 }
+
+// src/bible-html-transformer.ts
+var NON_BREAKING_SPACE = "\xA0";
+var FOOTNOTE_KEY_ATTR = "data-footnote-key";
+var NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
+var ALLOWED_TAGS = /* @__PURE__ */ new Set([
+  "DIV",
+  "P",
+  "SPAN",
+  "SUP",
+  "SUB",
+  "EM",
+  "STRONG",
+  "I",
+  "B",
+  "SMALL",
+  "BR",
+  "SECTION",
+  "TABLE",
+  "THEAD",
+  "TBODY",
+  "TR",
+  "TD",
+  "TH"
+]);
+var DROP_ENTIRELY_TAGS = /* @__PURE__ */ new Set([
+  "SCRIPT",
+  "STYLE",
+  "IFRAME",
+  "OBJECT",
+  "EMBED",
+  "SVG",
+  "MATH",
+  "FORM",
+  "INPUT",
+  "BUTTON",
+  "TEXTAREA",
+  "SELECT",
+  "TEMPLATE",
+  "LINK",
+  "META",
+  "BASE",
+  "NOSCRIPT"
+]);
+var ALLOWED_ATTRS = /* @__PURE__ */ new Set(["class", "v", "colspan", "rowspan", "dir", "usfm"]);
+function sanitizeBibleHtmlDocument(doc) {
+  const root = doc.body ?? doc.documentElement;
+  for (const el of Array.from(root.querySelectorAll("*"))) {
+    const tag = el.tagName;
+    if (DROP_ENTIRELY_TAGS.has(tag)) {
+      el.remove();
+      continue;
+    }
+    if (!ALLOWED_TAGS.has(tag)) {
+      el.replaceWith(...Array.from(el.childNodes));
+      continue;
+    }
+    for (const attr of Array.from(el.attributes)) {
+      const name = attr.name.toLowerCase();
+      if (name.startsWith("on")) {
+        el.removeAttribute(attr.name);
+        continue;
+      }
+      if (!ALLOWED_ATTRS.has(name) && !name.startsWith("data-")) {
+        el.removeAttribute(attr.name);
+      }
+    }
+  }
+}
+function wrapVerseContent(doc) {
+  function wrapParagraphContent(doc2, paragraph, verseNum) {
+    const children = Array.from(paragraph.childNodes);
+    if (children.length === 0) return;
+    const wrapper = doc2.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstChild = children[0];
+    if (firstChild) {
+      paragraph.insertBefore(wrapper, firstChild);
+    }
+    children.forEach((child) => {
+      wrapper.appendChild(child);
+    });
+  }
+  function wrapParagraphsUntilBoundary(doc2, verseNum, startParagraph, endParagraph) {
+    if (!startParagraph) return;
+    let currentParagraph = startParagraph.nextElementSibling;
+    while (currentParagraph && currentParagraph !== endParagraph) {
+      const isHeading = currentParagraph.classList.contains("yv-h") || currentParagraph.matches(
+        ".s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r"
+      );
+      if (isHeading) {
+        currentParagraph = currentParagraph.nextElementSibling;
+        continue;
+      }
+      if (currentParagraph.querySelector(".yv-v[v]")) break;
+      if (currentParagraph.classList.contains("p") || currentParagraph.tagName === "P") {
+        wrapParagraphContent(doc2, currentParagraph, verseNum);
+      }
+      currentParagraph = currentParagraph.nextElementSibling;
+    }
+  }
+  function handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum) {
+    if (!currentParagraph) return;
+    if (!nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph);
+      return;
+    }
+    if (currentParagraph !== nextParagraph) {
+      wrapParagraphsUntilBoundary(doc2, verseNum, currentParagraph, nextParagraph);
+    }
+  }
+  function processVerseMarker(marker, index, markers) {
+    const verseNum = marker.getAttribute("v");
+    if (!verseNum) return;
+    const nextMarker = markers[index + 1];
+    const nodesToWrap = collectNodesBetweenMarkers(marker, nextMarker);
+    if (nodesToWrap.length === 0) return;
+    const currentParagraph = marker.closest(".p, p, div.p");
+    const nextParagraph = nextMarker?.closest(".p, p, div.p") || null;
+    const doc2 = marker.ownerDocument;
+    wrapNodesInVerse(marker, verseNum, nodesToWrap);
+    handleParagraphWrapping(doc2, currentParagraph, nextParagraph, verseNum);
+  }
+  function wrapNodesInVerse(marker, verseNum, nodes) {
+    const wrapper = marker.ownerDocument.createElement("span");
+    wrapper.className = "yv-v";
+    wrapper.setAttribute("v", verseNum);
+    const firstNode = nodes[0];
+    if (firstNode) {
+      marker.parentNode?.insertBefore(wrapper, firstNode);
+    }
+    nodes.forEach((node) => {
+      wrapper.appendChild(node);
+    });
+    marker.remove();
+  }
+  function shouldStopCollecting(node, endMarker) {
+    if (node === endMarker) return true;
+    if (endMarker && node.nodeType === 1 && node.contains(endMarker)) return true;
+    return false;
+  }
+  function shouldSkipNode(node) {
+    return node.nodeType === 1 && node.classList.contains("yv-h");
+  }
+  function collectNodesBetweenMarkers(startMarker, endMarker) {
+    const nodes = [];
+    let current = startMarker.nextSibling;
+    while (current && !shouldStopCollecting(current, endMarker)) {
+      if (shouldSkipNode(current)) {
+        current = current.nextSibling;
+        continue;
+      }
+      nodes.push(current);
+      current = current.nextSibling;
+    }
+    return nodes;
+  }
+  const verseMarkers = Array.from(doc.querySelectorAll(".yv-v[v]"));
+  verseMarkers.forEach(processVerseMarker);
+}
+function assignFootnoteKeys(doc) {
+  let introIdx = 0;
+  doc.querySelectorAll(".yv-n.f").forEach((fn) => {
+    const verseNum = fn.closest(".yv-v[v]")?.getAttribute("v");
+    fn.setAttribute(FOOTNOTE_KEY_ATTR, verseNum ?? `intro-${introIdx++}`);
+  });
+}
+function replaceFootnotesWithAnchors(doc, footnotes) {
+  for (const fn of footnotes) {
+    const key = fn.getAttribute(FOOTNOTE_KEY_ATTR);
+    if (!key) continue;
+    const prev = fn.previousSibling;
+    const next = fn.nextSibling;
+    const prevText = prev?.textContent ?? "";
+    const nextText = next?.textContent ?? "";
+    const prevNeedsSpace = prevText.length > 0 && !/\s$/.test(prevText);
+    const nextNeedsSpace = nextText.length > 0 && NEEDS_SPACE_BEFORE.test(nextText);
+    if (prevNeedsSpace && nextNeedsSpace && fn.parentNode) {
+      fn.parentNode.insertBefore(doc.createTextNode(" "), fn);
+    }
+    const anchor = doc.createElement("span");
+    anchor.setAttribute("data-verse-footnote", key);
+    anchor.setAttribute("data-verse-footnote-content", fn.innerHTML);
+    fn.replaceWith(anchor);
+  }
+}
+function addNbspToVerseLabels(doc) {
+  doc.querySelectorAll(".yv-vlbl").forEach((label) => {
+    const text = label.textContent || "";
+    if (!text.endsWith(NON_BREAKING_SPACE)) {
+      label.textContent = text + NON_BREAKING_SPACE;
+    }
+  });
+}
+function fixIrregularTables(doc) {
+  doc.querySelectorAll("table").forEach((table) => {
+    const rows = table.querySelectorAll("tr");
+    if (rows.length === 0) return;
+    let maxColumns = 0;
+    rows.forEach((row) => {
+      let count = 0;
+      row.querySelectorAll("td, th").forEach((cell) => {
+        count += parseInt(cell.getAttribute("colspan") || "1", 10);
+      });
+      maxColumns = Math.max(maxColumns, count);
+    });
+    if (maxColumns > 1) {
+      rows.forEach((row) => {
+        const cells = row.querySelectorAll("td, th");
+        if (cells.length === 1) {
+          const existing = parseInt(cells[0].getAttribute("colspan") || "1", 10);
+          if (existing < maxColumns) {
+            cells[0].setAttribute("colspan", maxColumns.toString());
+          }
+        }
+      });
+    }
+  });
+}
+function transformBibleHtml(html, options) {
+  const doc = options.parseHtml(html);
+  sanitizeBibleHtmlDocument(doc);
+  wrapVerseContent(doc);
+  assignFootnoteKeys(doc);
+  const footnotes = Array.from(doc.querySelectorAll(".yv-n.f"));
+  replaceFootnotesWithAnchors(doc, footnotes);
+  addNbspToVerseLabels(doc);
+  fixIrregularTables(doc);
+  const transformedHtml = options.serializeHtml(doc);
+  return { html: transformedHtml };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ApiClient,
   BOOK_CANON,
   BOOK_IDS,
   BibleClient,
+  CANON_IDS,
   DEFAULT_LICENSE_FREE_BIBLE_VERSION,
   HighlightsClient,
   LanguagesClient,
@@ -1747,5 +1993,6 @@ function lastCanonicalOfPreviousBook(books, bookIndex) {
   YouVersionAPIUsers,
   YouVersionPlatformConfiguration,
   YouVersionUserInfo,
-  getAdjacentChapter
+  getAdjacentChapter,
+  transformBibleHtml
 });