+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result.html).not.toContain('overcome .');
+ });
+});
+
+describe('transformBibleHtml - verse wrapping', () => {
+ it('should wrap verse content in .yv-v[v] elements', () => {
+ const html = `
+ overcomeNote.
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result.html).toMatch(//);
+ expect(result.html).toMatch(//);
+ expect(result.html).not.toContain('');
+ });
+
+ it('should not wrap heading elements inside verse content', () => {
+ const html = `
+
+ 1Verse one text.
+
+
+ 2Verse two text.
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ const doc = new DOMParser().parseFromString(result.html, 'text/html');
+ const heading = doc.querySelector('.s1');
+ expect(heading).not.toBeNull();
+ expect(heading!.closest('.yv-v')).toBeNull();
+ });
+});
+
+describe('transformBibleHtml - addNbspToVerseLabels', () => {
+ it('should add non-breaking space after verse labels', () => {
+ const html = `
+
+ 1Text before heading
+
+ A Heading
+
+ 2Text after heading
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ const doc = new DOMParser().parseFromString(result.html, 'text/html');
+ const label = doc.querySelector('.yv-vlbl');
+ expect(label).not.toBeNull();
+ expect(label!.textContent).toContain('\u00A0');
+ });
+
+ it('should not duplicate non-breaking space if already present', () => {
+ const html = `
+
+ 1Verse text.
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ const doc = new DOMParser().parseFromString(result.html, 'text/html');
+ const label = doc.querySelector('.yv-vlbl');
+ const text = label!.textContent ?? '';
+ const count = (text.match(/\u00A0/g) || []).length;
+ expect(count).toBeLessThanOrEqual(1);
+ });
+});
+
+describe('transformBibleHtml - fixIrregularTables', () => {
+ it('should set colspan on single-cell rows in multi-column tables', () => {
+ const html = `
+
+ 1\u00A0Verse text.
+
+
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ const doc = new DOMParser().parseFromString(result.html, 'text/html');
+ const singleCell = doc.querySelector('tr:nth-child(2) td');
+ expect(singleCell).not.toBeNull();
+ expect(singleCell!.getAttribute('colspan')).toBe('2');
+ });
+});
+
+describe('transformBibleHtml - data attributes', () => {
+ it('should include data-verse-footnote attribute with verse key', () => {
+ const html = `
+ | Header Col 1 | Header Col 2 |
| Single cell spanning full width |
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result.html).toContain('data-verse-footnote="1"');
+ });
+
+ it('should include data-verse-footnote-content attribute with footnote HTML', () => {
+ const html = `
+
+ 1Verse textNote.
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result.html).toContain('data-verse-footnote-content=');
+ expect(result.html).toContain('See Rashi');
+ });
+
+ it('should preserve footnote HTML structure in data-verse-footnote-content', () => {
+ const html = `
+
+ 1Verse textSee Rashi.
+
+
+
+ `;
+
+ const result = transformBibleHtml(html, createAdapters());
+
+ const doc = new DOMParser().parseFromString(result.html, 'text/html');
+ const anchor = doc.querySelector('[data-verse-footnote="1"]');
+ expect(anchor).not.toBeNull();
+ const content = anchor!.getAttribute('data-verse-footnote-content');
+ expect(content).toContain('');
+ expect(content).toContain('Emphasized');
+ });
+});
+
+describe('transformBibleHtmlForBrowser', () => {
+ it('should transform HTML using native DOMParser', () => {
+ const html = `
+
+ 1TextEmphasized note.
+
+
+ `;
+
+ const result = transformBibleHtmlForBrowser(html);
+
+ expect(result.html).toBeDefined();
+ expect(result.html).toContain('data-verse-footnote="1"');
+ });
+
+ it('should return same result as transformBibleHtml with browser adapters', () => {
+ const html = `
+
+ 1Verse textNote.
+
+
+
+ `;
+
+ const result1 = transformBibleHtmlForBrowser(html);
+ const result2 = transformBibleHtml(html, createAdapters());
+
+ expect(result1.html).toBe(result2.html);
+ });
+
+ it('should handle empty HTML', () => {
+ const result = transformBibleHtmlForBrowser('');
+
+ expect(result.html).toBeDefined();
+ });
+});
+
+describe('transformBibleHtml - return type', () => {
+ it('should return html property', () => {
+ const html = '
+ 1Verse text.
+
+ Test
';
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result).toHaveProperty('html');
+ expect(typeof result.html).toBe('string');
+ });
+
+ it('should not have notes or rawHtml properties', () => {
+ const html = 'Test
';
+ const result = transformBibleHtml(html, createAdapters());
+
+ expect(result).not.toHaveProperty('notes');
+ expect(result).not.toHaveProperty('rawHtml');
+ });
+});
diff --git a/packages/core/src/bible-html-transformer.ts b/packages/core/src/bible-html-transformer.ts
new file mode 100644
index 00000000..727ea01b
--- /dev/null
+++ b/packages/core/src/bible-html-transformer.ts
@@ -0,0 +1,317 @@
+const NON_BREAKING_SPACE = '\u00A0';
+
+const FOOTNOTE_KEY_ATTR = 'data-footnote-key';
+
+const NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"»›]/;
+
+/**
+ * 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 currentP: Element | null = startParagraph.nextElementSibling;
+
+ while (currentP && currentP !== endParagraph) {
+ const isHeading =
+ currentP.classList.contains('yv-h') ||
+ currentP.matches('.s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r');
+ if (isHeading) {
+ currentP = currentP.nextElementSibling;
+ continue;
+ }
+
+ if (currentP.querySelector('.yv-v[v]')) break;
+
+ if (currentP.classList.contains('p') || currentP.tagName === 'P') {
+ wrapParagraphContent(doc, currentP, verseNum);
+ }
+
+ currentP = currentP.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);
+
+ 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
+ */
+export function transformBibleHtmlForBrowser(html: string): TransformedBibleHtml {
+ if (typeof globalThis.DOMParser === 'undefined') {
+ return { html };
+ }
+
+ return transformBibleHtml(html, {
+ parseHtml: (h) => new DOMParser().parseFromString(h, 'text/html'),
+ serializeHtml: (doc) => doc.body.innerHTML,
+ });
+}
+
+/**
+ * Transforms Bible HTML for Node.js environments using linkedom.
+ *
+ * linkedom requires HTML to be wrapped in body tags for `doc.body.innerHTML`
+ * to work correctly, so this function handles that wrapping automatically.
+ *
+ * @param html - The raw Bible HTML from the YouVersion API
+ * @returns The transformed HTML
+ */
+export function transformBibleHtmlForNode(html: string): TransformedBibleHtml {
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const { DOMParser } = require('linkedom') as {
+ DOMParser: new () => { parseFromString(html: string, type: string): Document };
+ };
+
+ return transformBibleHtml(html, {
+ parseHtml: (h: string) =>
+ new DOMParser().parseFromString(`${h}`, 'text/html'),
+ serializeHtml: (doc: Document) => doc.body.innerHTML,
+ });
+}
diff --git a/packages/core/src/bible.ts b/packages/core/src/bible.ts
index 62a04b9f..918fdf3a 100644
--- a/packages/core/src/bible.ts
+++ b/packages/core/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(
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 15fb7d91..a5c01f95 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -15,3 +15,10 @@ export * from './YouVersionPlatformConfiguration';
export * from './types';
export * from './utils/constants';
export { getAdjacentChapter } from './getAdjacentChapter';
+export {
+ transformBibleHtml,
+ transformBibleHtmlForBrowser,
+ transformBibleHtmlForNode,
+ type TransformBibleHtmlOptions,
+ type TransformedBibleHtml,
+} from './bible-html-transformer';
diff --git a/packages/ui/package.json b/packages/ui/package.json
index 3f2e1eda..b3ac4eb6 100644
--- a/packages/ui/package.json
+++ b/packages/ui/package.json
@@ -53,7 +53,6 @@
"@youversion/platform-react-hooks": "workspace:*",
"class-variance-authority": "0.7.1",
"clsx": "2.1.1",
- "isomorphic-dompurify": "2.23.0",
"tailwind-merge": "3.3.1",
"tw-animate-css": "1.4.0"
},
diff --git a/packages/ui/src/components/bible-reader.stories.tsx b/packages/ui/src/components/bible-reader.stories.tsx
index 015e7e48..a1bff3ca 100644
--- a/packages/ui/src/components/bible-reader.stories.tsx
+++ b/packages/ui/src/components/bible-reader.stories.tsx
@@ -677,9 +677,8 @@ export const VersionButtonLoadingStates: Story = {
),
play: async () => {
- // The version button should exist in the toolbar (label varies by loading state)
- const versionButton = screen.getByRole('button', { name: /bible version/i });
- await expect(versionButton).toBeInTheDocument();
+ // Wait for the toolbar to mount, then capture the button in loading state
+ const versionButton = await screen.findByRole('button', { name: /bible version/i });
// The delayed MSW handler guarantees the loading state is visible
const spinner = versionButton.querySelector('[role="status"]');
diff --git a/packages/ui/src/components/verse.test.tsx b/packages/ui/src/components/verse.test.tsx
index 3a7c127d..935d18e1 100644
--- a/packages/ui/src/components/verse.test.tsx
+++ b/packages/ui/src/components/verse.test.tsx
@@ -19,52 +19,6 @@ vi.mock('@youversion/platform-react-hooks', async () => {
describe('Verse.Html - XSS Protection', () => {
describe('DOMPurify sanitization', () => {
- it('should remove script tags from HTML', async () => {
- const maliciousHtml = 'Safe text
'; - - const { container } = render(Click me
'; - - const { container } = render(Safe Bible content
'; diff --git a/packages/ui/src/components/verse.tsx b/packages/ui/src/components/verse.tsx index 40ff1afc..21fbb4d0 100644 --- a/packages/ui/src/components/verse.tsx +++ b/packages/ui/src/components/verse.tsx @@ -16,21 +16,29 @@ import { Footnote } from '@/components/icons/footnote'; import { LoaderIcon } from '@/components/icons/loader'; import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover'; import { cn } from '@/lib/utils'; -import { - type FontFamily, - getFootnoteMarker, - transformBibleHtml, - type VerseNotes, -} from '@/lib/verse-html-utils'; +import { type FontFamily } from '@/lib/verse-html-utils'; +import { transformBibleHtmlForBrowser } from '@youversion/platform-core'; -type TransformedBibleHtml = { - html: string; - notes: Record-
- {verseNotes.notes.map((note, index) => {
+ {notes.map((note, index) => {
const marker = getFootnoteMarker(index);
return (
- {marker}. - {/** biome-ignore lint/security/noDangerouslySetInnerHtml: HTML has been run through DOMPurify and is safe */} + {/** biome-ignore lint/security/noDangerouslySetInnerHtml: Bible footnote HTML comes from our YouVersion APIs and is safe */} ); @@ -127,7 +165,6 @@ function VerseUnavailableMessage(): React.ReactElement { function BibleTextHtml({ html, - notes, reference, fontSize, theme, @@ -136,7 +173,6 @@ function BibleTextHtml({ highlightedVerses = {}, }: { html: string; - notes: Record
Some intro textFirst note and more textSecond note.
Text with aA footnote note.
-
- `;
-
- const result = transformBibleHtml(html);
+ const result = transformBibleHtmlForBrowser(html);
- expect(result.html).toContain('data-verse-footnote="intro-0"');
- expect(result.html).toContain('data-verse-footnote="intro-1"');
- expect(result.html).not.toContain('yv-n f');
+ expect(result.html).toContain('See Rashi');
});
it('should not interfere with regular verse footnotes when mixed', () => {
@@ -69,17 +54,12 @@ describe('transformBibleHtml - intro chapter footnotes', () => {
`;
- const result = transformBibleHtml(html);
+ const result = transformBibleHtmlForBrowser(html);
- expect(result.notes['intro-0']).toBeDefined();
- expect(result.notes['intro-0']!.verseHtml).toBe('');
- expect(result.notes['intro-0']!.hasVerseContext).toBe(false);
- expect(result.notes['intro-0']!.notes[0]).toContain('Intro note');
-
- expect(result.notes['1']).toBeDefined();
- expect(result.notes['1']!.verseHtml).not.toBe('');
- expect(result.notes['1']!.hasVerseContext).toBe(true);
- expect(result.notes['1']!.notes[0]).toContain('Verse note');
+ expect(result.html).toContain('data-verse-footnote="intro-0"');
+ expect(result.html).toContain('data-verse-footnote="1"');
+ expect(result.html).toContain('Intro note');
+ expect(result.html).toContain('Verse note');
});
it('should insert space when orphaned footnote is between two words', () => {
@@ -89,7 +69,7 @@ describe('transformBibleHtml - intro chapter footnotes', () => {
`;
- const result = transformBibleHtml(html);
+ const result = transformBibleHtmlForBrowser(html);
expect(result.html).toContain('overcome ');
expect(result.html).not.toMatch(/overcome {
`;
- const result = transformBibleHtml(html);
+ const result = transformBibleHtmlForBrowser(html);
expect(result.html).not.toContain('overcome .');
});
diff --git a/packages/ui/src/lib/verse-html-utils.ts b/packages/ui/src/lib/verse-html-utils.ts
index 08a4a300..51839218 100644
--- a/packages/ui/src/lib/verse-html-utils.ts
+++ b/packages/ui/src/lib/verse-html-utils.ts
@@ -1,413 +1,3 @@
-import DOMPurify from 'isomorphic-dompurify';
-
-const NON_BREAKING_SPACE = '\u00A0';
-
-const LETTERS = 'abcdefghijklmnopqrstuvwxyz';
-
-/**
- * Converts a 0-based footnote index into an alphabetic marker.
- *
- * Examples with LETTERS = "abcdefghijklmnopqrstuvwxyz":
- * 0 -> "a", 25 -> "z", 26 -> "aa", 27 -> "ab"
- *
- * This uses spreadsheet-style indexing and derives its base from
- * LETTERS.length so there are no hardcoded numeric assumptions.
- */
-export function getFootnoteMarker(index: number): string {
- const base = LETTERS.length;
- if (base === 0) return String(index + 1);
-
- let value = index;
- let marker = '';
-
- do {
- marker = LETTERS[value % base] + marker;
- value = Math.floor(value / base) - 1;
- } while (value >= 0);
-
- return marker;
-}
-
-export type VerseNotes = {
- verseHtml: string;
- notes: string[];
- hasVerseContext: boolean;
-};
-
export const INTER_FONT = '"Inter", sans-serif' as const;
export const SOURCE_SERIF_FONT = '"Source Serif 4", serif' as const;
export type FontFamily = typeof INTER_FONT | typeof SOURCE_SERIF_FONT | (string & {});
-
-/**
- * Wraps verse content in `yv-v` elements for easier CSS targeting.
- *
- * Transforms empty verse markers into wrapping containers. When a verse spans
- * multiple paragraphs, creates duplicate wrappers in each paragraph (Bible.com pattern).
- *
- * Before: 1Text...
- * After: 1Text...
- *
- * This enables simple CSS selectors like `.yv-v[v="1"] { background: yellow; }`
- */
-function wrapVerseContent(doc: Document): void {
- /**
- * Wraps all content in a paragraph with a verse span.
- */
- 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);
- });
- }
-
- /**
- * Wraps paragraphs between startParagraph and an optional endParagraph boundary.
- * If no endParagraph is provided, wraps until a verse marker is found or siblings are exhausted.
- */
- function wrapParagraphsUntilBoundary(
- doc: Document,
- verseNum: string,
- startParagraph: Element | null,
- endParagraph?: Element | null,
- ): void {
- if (!startParagraph) return;
-
- let currentP: Element | null = startParagraph.nextElementSibling;
-
- while (currentP && currentP !== endParagraph) {
- // Skip heading elements - these are structural, not verse content
- // See iOS implementation: https://github.com/youversion/platform-sdk-swift/blob/main/Sources/YouVersionPlatformUI/Views/Rendering/BibleVersionRendering.swift
- const isHeading =
- currentP.classList.contains('yv-h') ||
- currentP.matches('.s1, .s2, .s3, .s4, .ms, .ms1, .ms2, .ms3, .ms4, .mr, .sp, .sr, .qa, .r');
- if (isHeading) {
- currentP = currentP.nextElementSibling;
- continue;
- }
-
- if (currentP.querySelector('.yv-v[v]')) break;
-
- if (
- currentP.classList.contains('p') ||
- currentP.tagName === 'P'
- ) {
- wrapParagraphContent(doc, currentP, verseNum);
- }
-
- currentP = currentP.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 instanceof Element && node.contains(endMarker)) return true;
- return false;
- }
-
- function shouldSkipNode(node: Node): boolean {
- return node instanceof Element && node.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);
-}
-
-/**
- * Matches text that needs a space inserted before it (not whitespace or punctuation).
- * Used when replacing footnotes to prevent word concatenation.
- */
-const NEEDS_SPACE_BEFORE = /^[^\s.,;:!?)}\]'"»›]/;
-
-/**
- * Builds the verse text shown inside the footnote popover.
- *
- * Works on clones of the verse wrappers so it never mutates the real DOM.
- * Strips headings and labels, replaces each footnote with a superscript
- * marker (a, b, … z, aa, ab, …).
- */
-function buildVerseHtml(wrappers: Element[]): string {
- const parts: string[] = [];
- let noteIdx = 0;
-
- for (let i = 0; i < wrappers.length; i++) {
- if (i > 0) parts.push(' ');
-
- const clone = wrappers[i]!.cloneNode(true) as Element;
- const ownerDoc = wrappers[i]!.ownerDocument;
-
- // Remove structural elements that shouldn't appear in the popover.
- clone.querySelectorAll('.yv-h, .yv-vlbl').forEach((el) => el.remove());
-
- // Replace each footnote with a superscript marker.
- clone.querySelectorAll('.yv-n.f').forEach((fn) => {
- const marker = ownerDoc.createElement('sup');
- marker.className = 'yv:text-muted-foreground';
- marker.textContent = getFootnoteMarker(noteIdx++);
- fn.replaceWith(marker);
- });
-
- parts.push(clone.innerHTML);
- }
-
- return parts.join('');
-}
-
-/**
- * Assigns a stable key to every footnote element in document order.
- *
- * Verse-bound footnotes get the verse number; orphaned footnotes (intro
- * chapters with no `.yv-v[v]` ancestor) get synthetic keys `"intro-0"`, etc.
- * Called once so both extraction and anchor replacement read the same key.
- */
-const FOOTNOTE_KEY_ATTR = 'data-footnote-key';
-
-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++}`);
- });
-}
-
-/**
- * Replaces each footnote element in the real DOM with a clean anchor span
- * that React portals can target.
- *
- * Also inserts a space when the removal of the footnote would cause two
- * adjacent words to merge (e.g., "overcome" + "it" → "overcomeit").
- */
-function replaceFootnotesWithAnchors(doc: Document, footnotes: Element[]): void {
- for (const fn of footnotes) {
- const key = fn.getAttribute(FOOTNOTE_KEY_ATTR)!;
-
- 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);
- fn.replaceWith(anchor);
- }
-}
-
-/**
- * Extracts footnotes from wrapped verse HTML and prepares data for footnote popovers.
- *
- * Assumes verses are already wrapped in `.yv-v[v]` elements (by wrapVerseContent)
- * and footnote keys assigned (by assignFootnoteKeys).
- *
- * Two-phase approach:
- * 1. Build popover data (verseHtml + note content) using cloned DOM — no side effects.
- * 2. Replace footnotes in the real DOM with clean anchor spans for React portals.
- *
- * @returns Notes data for popovers, keyed by verse number (or synthetic intro key).
- */
-function extractNotesFromWrappedHtml(doc: Document): RecordBeforeNote A afterNote B.
-