@youversion/platform-core 1.20.2 → 1.21.0

package/src/bible-html-transformer.ts

@@ -0,0 +1,378 @@
+const NON_BREAKING_SPACE = '\u00A0';
+
+const FOOTNOTE_KEY_ATTR = 'data-footnote-key';
+
+const NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"'»›]/;
+
+const ALLOWED_TAGS = new Set([
+  'DIV',
+  'P',
+  'SPAN',
+  'SUP',
+  'SUB',
+  'EM',
+  'STRONG',
+  'I',
+  'B',
+  'SMALL',
+  'BR',
+  'SECTION',
+  'TABLE',
+  'THEAD',
+  'TBODY',
+  'TR',
+  'TD',
+  'TH',
+]);
+
+const DROP_ENTIRELY_TAGS = new Set([
+  'SCRIPT',
+  'STYLE',
+  'IFRAME',
+  'OBJECT',
+  'EMBED',
+  'SVG',
+  'MATH',
+  'FORM',
+  'INPUT',
+  'BUTTON',
+  'TEXTAREA',
+  'SELECT',
+  'TEMPLATE',
+  'LINK',
+  'META',
+  'BASE',
+  'NOSCRIPT',
+]);
+
+const ALLOWED_ATTRS = new Set(['class', 'v', 'colspan', 'rowspan', 'dir', 'usfm']);
+
+function sanitizeBibleHtmlDocument(doc: Document): void {
+  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);
+      }
+    }
+  }
+}
+
+/**
+ * Options for transforming Bible HTML. Requires DOM adapter functions
+ * to parse and serialize HTML, making the transformer runtime-agnostic.
+ */
+export type TransformBibleHtmlOptions = {
+  /** Parses an HTML string into a DOM Document */
+  parseHtml: (html: string) => Document;
+  /** Serializes a Document back to an HTML string */
+  serializeHtml: (doc: Document) => string;
+};
+
+/**
+ * The result of transforming Bible HTML.
+ *
+ * The returned HTML is self-contained — footnote data is embedded as attributes:
+ * - `data-verse-footnote="KEY"` marks the footnote position
+ * - `data-verse-footnote-content="HTML"` contains the footnote's inner HTML
+ *
+ * Consumers can access verse context by walking up from a footnote anchor
+ * to `.closest('.yv-v[v]')`.
+ */
+export type TransformedBibleHtml = {
+  /** The transformed HTML with footnotes replaced by marker elements */
+  html: string;
+};
+
+function wrapVerseContent(doc: Document): void {
+  function wrapParagraphContent(doc: Document, paragraph: Element, verseNum: string): void {
+    const children = Array.from(paragraph.childNodes);
+    if (children.length === 0) return;
+
+    const wrapper = doc.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(
+    doc: Document,
+    verseNum: string,
+    startParagraph: Element | null,
+    endParagraph?: Element | null,
+  ): void {
+    if (!startParagraph) return;
+
+    let currentParagraph: Element | null = 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(doc, currentParagraph, verseNum);
+      }
+
+      currentParagraph = currentParagraph.nextElementSibling;
+    }
+  }
+
+  function handleParagraphWrapping(
+    doc: Document,
+    currentParagraph: Element | null,
+    nextParagraph: Element | null,
+    verseNum: string,
+  ): void {
+    if (!currentParagraph) return;
+
+    if (!nextParagraph) {
+      wrapParagraphsUntilBoundary(doc, verseNum, currentParagraph);
+      return;
+    }
+
+    if (currentParagraph !== nextParagraph) {
+      wrapParagraphsUntilBoundary(doc, verseNum, currentParagraph, nextParagraph);
+    }
+  }
+
+  function processVerseMarker(marker: Element, index: number, markers: Element[]): void {
+    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 doc = marker.ownerDocument;
+
+    wrapNodesInVerse(marker, verseNum, nodesToWrap);
+    handleParagraphWrapping(doc, currentParagraph, nextParagraph, verseNum);
+  }
+
+  function wrapNodesInVerse(marker: Element, verseNum: string, nodes: Node[]): void {
+    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: Node, endMarker: Element | undefined): boolean {
+    if (node === endMarker) return true;
+    if (endMarker && node.nodeType === 1 && (node as Element).contains(endMarker)) return true;
+    return false;
+  }
+
+  function shouldSkipNode(node: Node): boolean {
+    return node.nodeType === 1 && (node as Element).classList.contains('yv-h');
+  }
+
+  function collectNodesBetweenMarkers(
+    startMarker: Element,
+    endMarker: Element | undefined,
+  ): Node[] {
+    const nodes: Node[] = [];
+    let current: Node | null = 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: Document): void {
+  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: Document, footnotes: Element[]): void {
+  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: Document): void {
+  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: Document): void {
+  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());
+          }
+        }
+      });
+    }
+  });
+}
+
+/**
+ * Transforms Bible HTML by cleaning up verse structure, extracting footnotes,
+ * and replacing them with self-contained anchor elements.
+ *
+ * Footnote data is embedded directly in the HTML via attributes:
+ * - `data-verse-footnote="KEY"` — the footnote key (verse number or `intro-N`)
+ * - `data-verse-footnote-content="HTML"` — the footnote's inner HTML content
+ *
+ * Verse context is available by walking up from a footnote anchor:
+ * `anchor.closest('.yv-v[v]')` returns the verse wrapper (null for intro footnotes).
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @param options - DOM adapter options for parsing and serializing HTML
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtml } from '@youversion/platform-core';
+ *
+ * const result = transformBibleHtml(rawHtml, {
+ *   parseHtml: (html) => new DOMParser().parseFromString(html, 'text/html'),
+ *   serializeHtml: (doc) => doc.body.innerHTML,
+ * });
+ *
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+export function transformBibleHtml(
+  html: string,
+  options: TransformBibleHtmlOptions,
+): TransformedBibleHtml {
+  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 };
+}
+
+/**
+ * Transforms Bible HTML for browser environments using the native DOMParser API.
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @returns The transformed HTML
+ *
+ * @example
+ * ```ts
+ * import { transformBibleHtmlForBrowser } from '@youversion/platform-core/browser';
+ *
+ * const result = transformBibleHtmlForBrowser(rawHtml);
+ * console.log(result.html); // Clean HTML with self-contained footnote anchors
+ * ```
+ */
+export function transformBibleHtmlForBrowser(html: string): TransformedBibleHtml {
+  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,
+  });
+}

package/src/bible.ts

@@ -235,12 +235,18 @@ export 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
@@ -251,6 +257,10 @@ export 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(

package/src/browser.ts

@@ -0,0 +1,4 @@
+export {
+  transformBibleHtmlForBrowser as transformBibleHtml,
+  type TransformedBibleHtml,
+} from './bible-html-transformer';

package/src/index.ts

@@ -15,3 +15,8 @@ export * from './YouVersionPlatformConfiguration';
 export * from './types';
 export * from './utils/constants';
 export { getAdjacentChapter } from './getAdjacentChapter';
+export {
+  transformBibleHtml,
+  type TransformBibleHtmlOptions,
+  type TransformedBibleHtml,
+} from './bible-html-transformer';

package/src/server.ts

@@ -0,0 +1,2 @@
+export { transformBibleHtml } from './bible-html-transformer-server';
+export { type TransformedBibleHtml } from './bible-html-transformer';