@designcrowd/library.brand-page 6.0.6-json-prereq-1 → 6.0.6-json-prereq-2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@designcrowd/library.brand-page",
   "description": "A collection of Maker/Designer applications",
-  "version": "6.0.6-json-prereq-1",
+  "version": "6.0.6-json-prereq-2",
   "author": "Design.com Eng",
   "license": "UNLICENSED",
   "type": "module",

package/src/brand-page-maker/utils/__snapshots__/rte-render-parity.test.ts.snap

@@ -2,6 +2,8 @@
 
 exports[`BP-5787 RTE render parity (golden master) > T1 — editor renders the complex fixture to the frozen HTML baseline > editor-normalized-html 1`] = `"<h2 style="text-align: center;"><span style="color: var(--logo-text-color);">Themed heading</span></h2><p><strong>bold</strong> <em>italic</em> <u>underline</u> <s>strike</s> <span style="font-family: Montserrat; font-size: 1.5em; letter-spacing: 0.05em; line-height: 1.4;">styled span</span> <mark data-color="#ffe08a" style="background-color: rgb(255, 224, 138); color: inherit;">highlight</mark> <span style="color: rgb(255, 0, 0);">literal hex</span> <a href="/about" target="_self">internal link</a> <a href="https://example.com" target="_blank" rel="noopener noreferrer nofollow">external link</a></p><p style="text-align: right;">second paragraph, right-aligned</p>"`;
 
+exports[`BP-5787 RTE render parity (golden master) > T1 — render-from-JSON (DOM-less serialiser) produces equivalent HTML > serializer-html 1`] = `"<h2 style="text-align: center"><span style="color: var(--logo-text-color)">Themed heading</span></h2><p><strong>bold</strong> <em>italic</em> <u>underline</u> <s>strike</s> <span style="font-family: Montserrat; font-size: 1.5em; letter-spacing: 0.05em; line-height: 1.4">styled span</span> <mark data-color="#ffe08a" style="background-color: #ffe08a; color: inherit;">highlight</mark> <span style="color: rgb(255, 0, 0)">literal hex</span> <a href="/about" target="_self">internal link</a> <a href="https://example.com" target="_blank" rel="noopener noreferrer nofollow">external link</a></p><p style="text-align: right">second paragraph, right-aligned</p>"`;
+
 exports[`BP-5787 RTE render parity (golden master) > T6 — freezes the JSON shape that becomes the stored form > editor-json 1`] = `
 {
   "content": [

package/src/brand-page-maker/utils/rte-render-parity.test.ts

@@ -82,17 +82,29 @@ describe('BP-5787 RTE render parity (golden master)', () => {
     expect(JSON.stringify(ed.getJSON())).toContain(THEME_TOKEN_REF);
   });
 
-  it('T1 — render-from-JSON reproduces the editor-normalised HTML', () => {
-    // The migration's core guarantee: store JSON, render to the SAME HTML
-    // the editor produces directly (which the baseline snapshot freezes).
-    const ed = makeEditor();
-
-    ed.commands.setContent(COMPLEX_RTE_HTML);
-    const reference = ed.getHTML();
-
+  it('T1 — render-from-JSON (DOM-less serialiser) produces equivalent HTML', () => {
+    // renderRteToHtml now serialises JSON → HTML with a pure function (no
+    // editor/DOM, so it works on the server). Output is semantically identical
+    // to the editor's — the Playwright visual golden-master is the authority on
+    // pixel parity; here we freeze the serialiser output and assert structure.
     const viaJson = renderRteToHtml(toRteJson(COMPLEX_RTE_HTML));
 
-    expect(viaJson).toEqual(reference);
+    expect(viaJson).toMatchSnapshot('serializer-html');
+
+    // marks/nodes preserved
+    expect(viaJson).toContain('<strong>bold</strong>');
+    expect(viaJson).toContain('<em>italic</em>');
+    expect(viaJson).toContain('<u>underline</u>');
+    expect(viaJson).toContain('<s>strike</s>');
+    expect(viaJson).toContain('font-family: Montserrat');
+    expect(viaJson).toContain('font-size: 1.5em');
+    // theme token ref preserved (the crux of BP-5787)
+    expect(viaJson).toContain('color: var(--logo-text-color)');
+    // links + alignment
+    expect(viaJson).toContain('href="/about"');
+    expect(viaJson).toContain('href="https://example.com"');
+    expect(viaJson).toContain('text-align: center');
+    expect(viaJson).toContain('text-align: right');
   });
 
   it('T4 — legacy HTML strings render unchanged (back-compat passthrough)', () => {

package/src/brand-page-maker/utils/rte-render.util.ts

@@ -1,6 +1,7 @@
 import { Editor, type JSONContent } from '@tiptap/vue-3';
 import { getRteExtensions } from '../composables/rich-text-editor/getRteExtensions';
 import { isTiptapDocument, getRteJsonPlainText } from './rich-text-editor.util';
+import { serializeRteJsonToHtml } from './rte-serializer';
 
 export { isTiptapDocument, getRteJsonPlainText };
 
@@ -15,20 +16,17 @@ export { isTiptapDocument, getRteJsonPlainText };
  *   - renderRteToHtml  — render either form to final HTML for display.
  *   - toRteJson        — normalise either form to JSON for storage.
  *
- * Rendering uses the SAME extension set as the headless serialiser
- * (getRteExtensions, includeLinkRel) so JSON-rendered output is byte-identical
- * to today's stored HTML — proven by the render-parity golden master.
+ *   - renderRteToHtml uses a DOM-less serialiser (works on the server).
+ *   - toRteJson uses a headless editor to PARSE HTML → JSON, so it only runs
+ *     where a DOM exists (browser, or jsdom in tests); the server never parses
+ *     HTML (migration-18 is DOM-guarded, translation/fraud walk JSON directly).
  */
 export type RichTextValue = string | JSONContent;
 
 /**
  * Run a function with a short-lived headless editor (created then destroyed).
- *
- * We deliberately do NOT keep a long-lived editor instance: a lingering Tiptap
- * editor throws "document is not defined" when a test DOM (jsdom) is torn down.
- * The expensive repeat-render case (re-rendering unchanged content on a
- * display-style/layout change) is handled by the render cache below, so this
- * only runs on a cache miss — i.e. genuinely new/changed content.
+ * Used only by toRteJson (HTML → JSON parsing), which needs a real DOM. Not
+ * used by the render path, which is DOM-less.
  */
 const withHeadlessEditor = <T>(fn: (editor: Editor) => T): T => {
   const editor = new Editor({
@@ -44,20 +42,10 @@ const withHeadlessEditor = <T>(fn: (editor: Editor) => T): T => {
 };
 
 /**
- * JSON→HTML is pure: the same document always renders to the same HTML. A
- * display-style/layout change re-renders every TextWrapper but does NOT change
- * the text content, so without a cache we would re-run the (expensive)
- * setContent+getHTML for unchanged content on every re-render. A small LRU
- * keyed by the document makes those repeat renders a near-free map lookup.
- */
-const RENDER_CACHE_LIMIT = 200;
-const renderCache = new Map<string, string>();
-
-/**
- * Render an RTE value to final HTML. Legacy HTML strings pass through
- * untouched (they are already HTML); Tiptap JSON is rendered via the
- * headless editor's renderHTML, matching the stored-HTML output exactly,
- * and memoised so repeat renders of unchanged content don't re-convert.
+ * Render an RTE value to final HTML. Legacy HTML strings pass through untouched
+ * (they are already HTML); Tiptap JSON is serialised by a DOM-less pure
+ * function (rte-serializer) — no editor, no DOM — so it works on the server
+ * (SSR/publish), not just the browser, and is cheap enough to run per render.
  */
 export const renderRteToHtml = (
   value: RichTextValue | null | undefined,
@@ -66,30 +54,7 @@ export const renderRteToHtml = (
 
   if (typeof value === 'string') return value;
 
-  const key = JSON.stringify(value);
-  const cached = renderCache.get(key);
-
-  if (cached !== undefined) {
-    // LRU bump: re-insert so the most-recently-used key is evicted last.
-    renderCache.delete(key);
-    renderCache.set(key, cached);
-
-    return cached;
-  }
-
-  const html = withHeadlessEditor((editor) => {
-    editor.commands.setContent(value);
-
-    return editor.getHTML();
-  });
-
-  renderCache.set(key, html);
-
-  if (renderCache.size > RENDER_CACHE_LIMIT) {
-    renderCache.delete(renderCache.keys().next().value as string);
-  }
-
-  return html;
+  return serializeRteJsonToHtml(value);
 };
 
 /**

package/src/brand-page-maker/utils/rte-serializer.ts

@@ -0,0 +1,172 @@
+import type { JSONContent } from '@tiptap/vue-3';
+
+/**
+ * BP-5787 — DOM-less Tiptap-JSON → HTML serialiser.
+ *
+ * The editor-based render (`new Editor().getHTML()`) needs a browser DOM and
+ * throws "document is not defined" on the server (web-renderer SSR / publish),
+ * which is where published pages are rendered. This pure-function serialiser
+ * walks the JSON and emits the equivalent HTML with no editor and no DOM, so it
+ * runs anywhere (SSR, node, browser) and is far cheaper than instantiating an
+ * editor per field.
+ *
+ * The output is semantically identical to the editor's (same tags, same inline
+ * styles); the Playwright visual golden-master is the authority on pixel parity.
+ */
+
+type Mark = { type?: string; attrs?: Record<string, unknown> };
+
+type Node = {
+  type?: string;
+  text?: string;
+  marks?: Mark[];
+  attrs?: Record<string, unknown>;
+  content?: Node[];
+};
+
+const escapeHtml = (value: string): string =>
+  value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+const escapeAttr = (value: string): string =>
+  escapeHtml(value).replace(/"/g, '&quot;');
+
+// textStyle attr → CSS property, in a stable order.
+const TEXT_STYLE_PROPS: [string, string][] = [
+  ['fontFamily', 'font-family'],
+  ['fontSize', 'font-size'],
+  ['letterSpacing', 'letter-spacing'],
+  ['lineHeight', 'line-height'],
+  ['color', 'color'],
+];
+
+const textStyleCss = (attrs: Record<string, unknown>): string =>
+  TEXT_STYLE_PROPS.filter(
+    ([key]) => typeof attrs[key] === 'string' && attrs[key],
+  )
+    .map(([key, css]) => `${css}: ${attrs[key] as string}`)
+    .join('; ');
+
+// Outermost → innermost. Reversed at wrap time so links wrap outside spans,
+// which wrap outside the plain formatting marks.
+const MARK_ORDER = [
+  'link',
+  'textStyle',
+  'highlight',
+  'strike',
+  'underline',
+  'italic',
+  'bold',
+  'code',
+];
+
+const wrapMark = (
+  type: string,
+  attrs: Record<string, unknown>,
+  inner: string,
+): string => {
+  switch (type) {
+    case 'bold':
+      return `<strong>${inner}</strong>`;
+    case 'italic':
+      return `<em>${inner}</em>`;
+    case 'underline':
+      return `<u>${inner}</u>`;
+    case 'strike':
+      return `<s>${inner}</s>`;
+    case 'code':
+      return `<code>${inner}</code>`;
+
+    case 'textStyle': {
+      const css = textStyleCss(attrs);
+
+      return css ? `<span style="${escapeAttr(css)}">${inner}</span>` : inner;
+    }
+
+    case 'highlight': {
+      const color = typeof attrs.color === 'string' ? attrs.color : '';
+
+      return color
+        ? `<mark data-color="${escapeAttr(color)}" style="background-color: ${escapeAttr(color)}; color: inherit;">${inner}</mark>`
+        : `<mark>${inner}</mark>`;
+    }
+
+    case 'link': {
+      const href = typeof attrs.href === 'string' ? attrs.href : '';
+      let open = `<a href="${escapeAttr(href)}"`;
+
+      if (attrs.target) open += ` target="${escapeAttr(String(attrs.target))}"`;
+
+      if (attrs.rel) open += ` rel="${escapeAttr(String(attrs.rel))}"`;
+
+      return `${open}>${inner}</a>`;
+    }
+
+    default:
+      return inner;
+  }
+};
+
+const renderText = (node: Node): string => {
+  let html = escapeHtml(node.text ?? '');
+  const marks = Array.isArray(node.marks) ? node.marks : [];
+
+  for (const type of [...MARK_ORDER].reverse()) {
+    const mark = marks.find((m) => m?.type === type);
+
+    if (mark) html = wrapMark(type, mark.attrs ?? {}, html);
+  }
+
+  return html;
+};
+
+const alignAttr = (node: Node): string => {
+  const align = node.attrs?.textAlign;
+
+  return typeof align === 'string' && align
+    ? ` style="text-align: ${escapeAttr(align)}"`
+    : '';
+};
+
+const renderChildren = (node: Node): string =>
+  (node.content ?? []).map(renderNode).join('');
+
+const renderNode = (node: Node): string => {
+  if (!node || typeof node !== 'object') return '';
+
+  switch (node.type) {
+    case 'text':
+      return renderText(node);
+    case 'hardBreak':
+      return '<br>';
+    case 'horizontalRule':
+      return '<hr>';
+    case 'paragraph':
+      return `<p${alignAttr(node)}>${renderChildren(node)}</p>`;
+
+    case 'heading': {
+      const level = Math.min(6, Math.max(1, Number(node.attrs?.level) || 1));
+
+      return `<h${level}${alignAttr(node)}>${renderChildren(node)}</h${level}>`;
+    }
+
+    case 'bulletList':
+      return `<ul>${renderChildren(node)}</ul>`;
+    case 'orderedList':
+      return `<ol>${renderChildren(node)}</ol>`;
+    case 'listItem':
+      return `<li>${renderChildren(node)}</li>`;
+    case 'blockquote':
+      return `<blockquote>${renderChildren(node)}</blockquote>`;
+    case 'codeBlock':
+      return `<pre><code>${renderChildren(node)}</code></pre>`;
+    // doc and any unknown container: render children.
+    default:
+      return renderChildren(node);
+  }
+};
+
+/**
+ * Serialise a Tiptap JSON document to HTML without an editor/DOM.
+ */
+export const serializeRteJsonToHtml = (doc: JSONContent): string =>
+  renderChildren(doc as Node);