@designcrowd/library.brand-page 6.0.25 → 6.0.26-json-prereq-2

package/src/brand-page/models/index.ts

@@ -30,6 +30,15 @@ import type { LogoImageModel, LogoTemplateImageModel } from './logo.model';
 import cloneDeep from 'lodash.clonedeep';
 import * as uuid from 'uuid';
 import type { BrandPagePaymentConfig } from './payment.model';
+import type { JSONContent } from '@tiptap/vue-3';
+
+/**
+ * BP-5787 — a rich-text field is either a legacy inline-HTML string or a
+ * Tiptap JSON document. Typing RTE content fields as RichTextValue (instead of
+ * `string`) forces every consumer to handle both forms — surfacing at compile
+ * time any code that assumes a plain string (e.g. `.replace`, `.length`).
+ */
+export type RichTextValue = string | JSONContent;
 
 export * from './brand-page-context.model';
 export * from './payment.model';
@@ -280,7 +289,7 @@ export interface TextContent extends Content {
   /**
    * For BrandPage/BrandContact only
    */
-  text: string;
+  text: RichTextValue;
   /**
    * For BrandSite
    */
@@ -304,9 +313,9 @@ export interface TextContent extends Content {
 
 export interface ProfileContent extends Content {
   avatarImageUrl: string;
-  name: string;
-  title: string;
-  description: string;
+  name: RichTextValue;
+  title: RichTextValue;
+  description: RichTextValue;
   backgroundColor: BrandPageCssStyle;
   colorReplacements: ColorReplacement[];
   mediaType?: string;
@@ -327,7 +336,7 @@ export interface MapContent extends Content {
 
 export interface MailingListContent extends Content {
   acceptedFields?: 'emailOnly' | 'nameAndEmail';
-  title: string;
+  title: RichTextValue;
   buttonText: string;
   titleStyle: TextStyleDeclaration;
   buttonTextStyle: TextStyleDeclaration;
@@ -387,10 +396,10 @@ export interface FormField {
 export interface ContactFormContent extends Content {
   type: 'contact-form';
   displayStyle: string;
-  title: string;
-  description: string;
+  title: RichTextValue;
+  description: RichTextValue;
   buttonText: string;
-  successMessage: string;
+  successMessage: RichTextValue;
   fields: FormField[];
   responseEmail: string;
   imageUrl?: string;
@@ -410,8 +419,8 @@ export interface ContactFormContent extends Content {
 export interface BannerSectionContent extends Content {
   type: 'banner-section';
   imageUrl: string;
-  title: string;
-  description: string;
+  title: RichTextValue;
+  description: RichTextValue;
   buttonText: string | false;
   url: string;
   email?: string;
@@ -441,8 +450,8 @@ export const MEDIA_TYPES = {
 export type MediaType = keyof typeof MEDIA_TYPES;
 
 export interface TextMediaItem extends ImageItem {
-  title: string;
-  paragraph: string;
+  title: RichTextValue;
+  paragraph: RichTextValue;
   itemsId: number;
 
   buttonText?: string | false;
@@ -466,8 +475,8 @@ export interface TextShapeItem extends TextMediaItem {
 export interface ShapeItem extends ImageItem {
   colorReplacements: ColorReplacement[];
   mediaType: MediaType;
-  title?: string;
-  paragraph?: string;
+  title?: RichTextValue;
+  paragraph?: RichTextValue;
 
   // overrides for personalisation
   titleOverride?: string;
@@ -478,9 +487,9 @@ export interface TestimonialItems {
   /** Stable per-item identifier. See ImageItem.id. */
   id: string;
   imageUrl: string;
-  name: string;
-  position: string;
-  testimonials: string;
+  name: RichTextValue;
+  position: RichTextValue;
+  testimonials: RichTextValue;
   colorReplacements: ColorReplacement[];
   mediaType: string;
   size?: string;
@@ -496,7 +505,7 @@ export interface TestimonialItems {
 export interface TextItem {
   /** Stable per-item identifier. See ImageItem.id. */
   id: string;
-  text: string;
+  text: RichTextValue;
   textStyle: TextStyleDeclaration;
 
   // overrides for personalisation
@@ -518,8 +527,8 @@ export interface ImagesSectionContent extends Content, MediaSection {
 }
 
 export interface MediaSection extends Content {
-  title: string;
-  description: string;
+  title: RichTextValue;
+  description: RichTextValue;
   displayStyle: ImagesSectionContentDisplayStyle;
   items: TextShapeItem[] | TextMediaItem[];
   titleStyle: TextStyleDeclaration;
@@ -538,7 +547,7 @@ export interface ColorReplacement {
 
 export interface TestimonialSectionContent extends Content {
   type: 'testimonial-section';
-  title: string;
+  title: RichTextValue;
   displayStyle: string;
   items: TestimonialItems[];
   titleStyle: TextStyleDeclaration;
@@ -553,8 +562,8 @@ export interface TestimonialSectionContent extends Content {
 export interface AboutSectionContent extends Content {
   type: 'about-section';
   imageUrl: string;
-  title: string;
-  paragraph: string;
+  title: RichTextValue;
+  paragraph: RichTextValue;
   displayStyle: string;
   titleStyle: TextStyleDeclaration;
   paragraphStyle: TextStyleDeclaration;
@@ -583,7 +592,7 @@ export type SocialLinksIconDisplayStyle =
 
 export interface SocialLinksContent extends Content {
   type: 'social-links';
-  title: string;
+  title: RichTextValue;
   links: LinksItem[];
   iconDisplayStyle: SocialLinksIconDisplayStyle;
   iconFillStyles: BrandPageCssStyle;
@@ -610,8 +619,8 @@ export interface DividerSectionContent extends Content {
 
 export interface BookingSectionContent extends Content {
   type: 'booking-section';
-  title: string;
-  description: string;
+  title: RichTextValue;
+  description: RichTextValue;
   buttonText: string;
   url: string;
   email?: string;

package/src/brand-page/utils/__snapshots__/migration.util.test.ts.snap

@@ -462,7 +462,7 @@ exports[`migration.util > Banner Contents - text Align and Font Family should no
         },
       },
     },
-    "v": 19,
+    "v": 20,
   },
   "useOldLogoRenderSize": true,
 }
@@ -914,7 +914,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
         },
       },
     },
-    "v": 19,
+    "v": 20,
   },
   "useOldLogoRenderSize": true,
 }
@@ -1373,7 +1373,7 @@ exports[`migration.util > migrateBrandPageModel should return brand page model w
         },
       },
     },
-    "v": 19,
+    "v": 20,
   },
   "useOldLogoRenderSize": true,
 }

package/src/brand-page/utils/migration/migration-20.server.test.ts

@@ -0,0 +1,125 @@
+/**
+ * BP-5787 — migration-20 must convert HTML RTE → Tiptap JSON on the SERVER, not
+ * just the browser. The HTML→JSON parse needs a DOM parser, which pure-node SSR
+ * lacks. migration-20 resolves one via `resolveHtmlParser` — a jsdom `DOMParser`
+ * INSTANCE on the server (no global mutation), threaded explicitly into the pass.
+ *
+ * These tests run under the default jsdom environment but DELETE the global
+ * `window`/`document`/`DOMParser` around each case, so `resolveHtmlParser` takes
+ * its real pure-node branch (dynamic jsdom import → parser instance). The sibling
+ * migration-20.test.ts guards the browser path (native global DOMParser).
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'vitest';
+import { migration20 } from './migration-20';
+import type { MigrationData } from '../migration.util';
+import { isTiptapDocument, getRteJsonPlainText } from '@brand-page-maker/utils';
+
+const createMigrationData = (brandPageData: any): MigrationData =>
+  ({ brandPageModel: brandPageData }) as MigrationData;
+
+const model = (contents: any[]) => ({
+  pages: [{ id: 'p1', title: 'Home', slug: 'home', contents }],
+});
+
+const g = globalThis as any;
+let savedWindow: unknown;
+let savedDocument: unknown;
+let savedDOMParser: unknown;
+
+describe('migration20 (server / no DOM) — HTML RTE → Tiptap JSON', () => {
+  beforeEach(() => {
+    // Force the pure-node path: no global window/document AND no global
+    // DOMParser, so resolveHtmlParser must load jsdom itself.
+    savedWindow = g.window;
+    savedDocument = g.document;
+    savedDOMParser = g.DOMParser;
+    delete g.window;
+    delete g.document;
+    delete g.DOMParser;
+
+    expect(typeof window).toBe('undefined');
+    expect(typeof document).toBe('undefined');
+    expect(typeof DOMParser).toBe('undefined');
+  });
+
+  afterEach(() => {
+    g.window = savedWindow;
+    g.document = savedDocument;
+    g.DOMParser = savedDOMParser;
+  });
+
+  test('converts a top-level HTML RTE field with no global DOM', async () => {
+    const data = model([
+      {
+        id: '1',
+        type: 'banner-section',
+        title:
+          '<p><span style="color: var(--logo-text-color)">Hello</span></p>',
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const title = (result.brandPageModel.pages[0].contents[0] as any).title;
+
+    expect(isTiptapDocument(title)).toBe(true);
+    expect(getRteJsonPlainText(title)).toContain('Hello');
+    // theme token ref preserved through the server-side parse
+    expect(JSON.stringify(title)).toContain('var(--logo-text-color)');
+  });
+
+  test('converts RTE inside item arrays server-side (marks preserved)', async () => {
+    const data = model([
+      {
+        id: '2',
+        type: 'text',
+        textItems: [{ id: 'ti1', text: '<p><strong>bold</strong> item</p>' }],
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const item = (result.brandPageModel.pages[0].contents[0] as any)
+      .textItems[0];
+
+    expect(isTiptapDocument(item.text)).toBe(true);
+    expect(getRteJsonPlainText(item.text)).toContain('bold');
+    // the <strong> mark survived the jsdom parse
+    expect(JSON.stringify(item.text)).toContain('bold');
+  });
+
+  test('leaves plain strings and already-JSON content untouched (idempotent)', async () => {
+    const jsonDoc = {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'X' }] }],
+    };
+    const data = model([
+      {
+        id: '3',
+        type: 'banner-section',
+        title: jsonDoc, // already JSON
+        url: 'https://example.com', // plain string, not RTE
+        titleStyle: { color: '#fff', fontSize: '1em' }, // style object, untouched
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const c = result.brandPageModel.pages[0].contents[0] as any;
+
+    expect(c.title).toEqual(jsonDoc);
+    expect(c.url).toBe('https://example.com');
+    expect(c.titleStyle).toEqual({ color: '#fff', fontSize: '1em' });
+  });
+
+  test('does not mutate globalThis (no window/document/DOMParser leak)', async () => {
+    const data = model([
+      { id: '4', type: 'banner-section', title: '<p>Leak check</p>' },
+    ]);
+
+    await migration20(createMigrationData(data));
+
+    // The pass resolves a parser INSTANCE and never assigns to globalThis, so the
+    // deleted globals must stay absent — no transient install, nothing to leak.
+    expect(typeof window).toBe('undefined');
+    expect(typeof document).toBe('undefined');
+    expect(typeof DOMParser).toBe('undefined');
+  });
+});

package/src/brand-page/utils/migration/migration-20.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect } from 'vitest';
+import { migration20 } from './migration-20';
+import type { MigrationData } from '../migration.util';
+import { isTiptapDocument, getRteJsonPlainText } from '@brand-page-maker/utils';
+
+const createMigrationData = (brandPageData: any): MigrationData =>
+  ({ brandPageModel: brandPageData }) as MigrationData;
+
+const model = (contents: any[]) => ({
+  pages: [{ id: 'p1', title: 'Home', slug: 'home', contents }],
+});
+
+describe('migration20 — HTML RTE → Tiptap JSON', () => {
+  test('converts a top-level HTML RTE field to a JSON document', async () => {
+    const data = model([
+      {
+        id: '1',
+        type: 'banner-section',
+        title:
+          '<p><span style="color: var(--logo-text-color)">Hello</span></p>',
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const title = (result.brandPageModel.pages[0].contents[0] as any).title;
+
+    expect(isTiptapDocument(title)).toBe(true);
+    expect(getRteJsonPlainText(title)).toContain('Hello');
+    // theme token ref preserved through migration
+    expect(JSON.stringify(title)).toContain('var(--logo-text-color)');
+  });
+
+  test('converts RTE inside item arrays (text items / testimonials)', async () => {
+    const data = model([
+      {
+        id: '2',
+        type: 'text',
+        textItems: [{ id: 'ti1', text: '<p><strong>bold</strong> item</p>' }],
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const item = (result.brandPageModel.pages[0].contents[0] as any)
+      .textItems[0];
+
+    expect(isTiptapDocument(item.text)).toBe(true);
+    expect(getRteJsonPlainText(item.text)).toContain('bold');
+  });
+
+  test('leaves plain strings and already-JSON content untouched (idempotent)', async () => {
+    const jsonDoc = {
+      type: 'doc',
+      content: [{ type: 'paragraph', content: [{ type: 'text', text: 'X' }] }],
+    };
+    const data = model([
+      {
+        id: '3',
+        type: 'banner-section',
+        title: jsonDoc, // already JSON
+        url: 'https://example.com', // plain string, not RTE
+        titleStyle: { color: '#fff', fontSize: '1em' }, // style object, untouched
+      },
+    ]);
+
+    const result = await migration20(createMigrationData(data));
+    const c = result.brandPageModel.pages[0].contents[0] as any;
+
+    expect(c.title).toEqual(jsonDoc);
+    expect(c.url).toBe('https://example.com');
+    expect(c.titleStyle).toEqual({ color: '#fff', fontSize: '1em' });
+  });
+});

package/src/brand-page/utils/migration/migration-20.ts

@@ -0,0 +1,87 @@
+import type { BrandPageModel } from '../../models';
+import type { MigrationData } from '../migration.util';
+import {
+  hasRTEContent,
+  toRteJson,
+  resolveHtmlParser,
+  type HtmlParser,
+} from '../../../brand-page-maker/utils';
+
+/**
+ * BP-5787 — migrate existing inline-HTML RTE content to Tiptap JSON.
+ *
+ * The editor emits, and the renderer reads, Tiptap JSON. Existing
+ * published/saved sites still hold RTE fields as HTML strings. This converts
+ * them on load, in EVERY environment:
+ *   - maker (browser): the loaded model is JSON, so the next save persists JSON.
+ *   - web-renderer (SSR / server API routes): converted on read, so old sites
+ *     are normalised without a re-save and downstream code can treat RTE as JSON.
+ *
+ * This is a one-time, versioned migration (runAlways is NOT set): legacy sites
+ * are at model version < 20 and convert on first load in any environment; once
+ * `v` is stamped to 20 the conversion is skipped. This is only safe because the
+ * AI section builders now emit Tiptap JSON directly (they no longer write HTML),
+ * so there is no recurring post-load source of HTML to normalise.
+ *
+ * HTML→JSON parsing needs a DOM parser. Rather than mutate a global `window`,
+ * the parser is resolved once (native `DOMParser` in the browser, a jsdom
+ * `DOMParser` instance on the server) and threaded explicitly through the
+ * conversion — see resolveHtmlParser / toRteJson. No global state is touched, so
+ * the pass is safe on any server runtime and under concurrent requests.
+ *
+ * Scope: only HTML-RTE strings (hasRTEContent) are converted. Plain strings,
+ * numbers, and already-JSON docs are left untouched, so the migration is
+ * idempotent (re-running on JSON content is a no-op — non-string values are
+ * skipped). Nested RTE inside item arrays (textItems, testimonials, images…)
+ * is handled by recursing into arrays; style objects are intentionally not
+ * descended into (they never hold RTE content).
+ */
+const convertRteStringsToJson = (value: unknown, parser: HtmlParser): void => {
+  if (Array.isArray(value)) {
+    value.forEach((item) => convertRteStringsToJson(item, parser));
+
+    return;
+  }
+
+  if (!value || typeof value !== 'object') return;
+
+  const record = value as Record<string, unknown>;
+
+  Object.keys(record).forEach((key) => {
+    const field = record[key];
+
+    if (typeof field === 'string' && hasRTEContent(field)) {
+      const json = toRteJson(field, parser);
+
+      if (json) record[key] = json;
+    } else if (Array.isArray(field)) {
+      convertRteStringsToJson(field, parser);
+    }
+  });
+};
+
+const convertModel = (
+  brandPageModel: BrandPageModel,
+  parser: HtmlParser,
+): void => {
+  for (const page of brandPageModel.pages) {
+    for (const content of page.contents) {
+      convertRteStringsToJson(content, parser);
+    }
+  }
+};
+
+export const migration20 = async (
+  migrationResult: MigrationData,
+): Promise<MigrationData> => {
+  const { brandPageModel } = migrationResult;
+
+  // Resolve a DOM parser for this environment (native in the browser, a jsdom
+  // instance on the server — never touching globals), then convert every
+  // HTML-RTE field to Tiptap JSON with it.
+  const parser = await resolveHtmlParser();
+
+  convertModel(brandPageModel, parser);
+
+  return migrationResult;
+};

package/src/brand-page/utils/migration.util.ts

@@ -22,6 +22,7 @@ import { migration16 } from './migration/migration-16';
 import { migration17 } from './migration/migration-17';
 import { migration18 } from './migration/migration-18';
 import { migration19 } from './migration/migration-19';
+import { migration20 } from './migration/migration-20';
 
 export interface MigrationData {
   brandPageModel: BrandPageModel;
@@ -179,6 +180,17 @@ const MIGRATION_TABLE = [
     description:
       'BP-5800: seed the button fill colour as each block’s own container colour so it is independent of the site button (existing sites render unchanged) — backgroundStyle for mailing-list, request-payment and support-me (all types); cardStyle for the BP/BC contact form (skipped on brand-site)',
   },
+  {
+    version: 20,
+    migrateFn: migration20,
+    // One-time versioned migration (NOT runAlways): legacy sites (v < 20)
+    // convert on their first load in any environment — the maker (browser DOM)
+    // and web-renderer SSR (migration-20 installs a jsdom window). It no longer
+    // needs to re-run every load because the AI section builders now emit Tiptap
+    // JSON directly, so there is no recurring post-load source of HTML to catch.
+    description:
+      'BP-5787: convert inline-HTML RTE content to Tiptap JSON on first load (client or server); AI builders emit JSON directly, so this runs once per site',
+  },
 ] as MigrationTableItem[];
 
 export const GetLatestModelVersion = () =>

package/src/brand-page/utils/style.util.test.ts

@@ -87,6 +87,57 @@ describe('style.util', () => {
     );
   });
 
+  test('applyLogoThemeToBrandPageModel preserves var() token refs in JSON RTE content (BP-5787)', () => {
+    // Arrange — title stored as Tiptap JSON with a theme-token colour mark.
+    const logoTheme = logoWithFlatColorsTheme;
+    const titleDoc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'heading',
+          attrs: { level: 2, textAlign: 'center' },
+          content: [
+            {
+              type: 'text',
+              marks: [
+                {
+                  type: 'textStyle',
+                  attrs: { color: `var(--${STYLE_THEME_KEYS.LogoTextColor})` },
+                },
+              ],
+              text: 'Themed',
+            },
+          ],
+        },
+      ],
+    };
+    const brandPageModel = new BrandPageModel({
+      ...BRAND_SITE,
+      pages: [
+        {
+          title: '1',
+          slug: '1',
+          contents: [
+            {
+              ...createInitialBannerSectionContent(),
+              title: titleDoc,
+            } as any,
+          ],
+        },
+      ],
+    });
+
+    // Act
+    const { model } = applyLogoThemeToBrandPageModel(logoTheme, brandPageModel);
+
+    // Assert — JSON RTE content is an object, so the var() token is NOT
+    // flattened to rgb(); it survives so a new theme can still propagate.
+    const title = JSON.stringify((model.pages[0].contents[0] as any).title);
+
+    expect(title).toContain(`var(--${STYLE_THEME_KEYS.LogoTextColor})`);
+    expect(title).not.toContain(logoTheme.logoTextColor.rgb);
+  });
+
   test('applyLogoThemeToBrandPageModel should apply logo theme color to content color when content color has a color matched theme key', () => {
     // Arrange
     const logoTheme = logoWithFlatColorsTheme;

package/src/brand-page/utils/text.util.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { escapeContentText, getRenderText } from './text.util';
+
+/**
+ * BP-5787 — escapeContentText / getRenderText must accept either a legacy
+ * inline-HTML string or a Tiptap JSON document without throwing. Section
+ * components call these on RTE fields (e.g. banner description), which are now
+ * JSON; the previous string-only versions threw `.replace is not a function`
+ * and broke the field's reactivity (strike/format edits stopped rendering).
+ */
+const doc = {
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: [
+        { type: 'text', text: 'WARNING', marks: [{ type: 'strike' }] },
+        { type: 'text', text: ': take flight' },
+      ],
+    },
+  ],
+};
+
+describe('escapeContentText (BP-5787 dual-read)', () => {
+  it('extracts plain text from a Tiptap JSON document', () => {
+    expect(escapeContentText(doc)).toBe('WARNING : take flight');
+  });
+
+  it('still strips tags from a legacy HTML string', () => {
+    expect(escapeContentText('<p><s>WARNING</s></p>')).toBe('WARNING');
+  });
+
+  it('returns falsy input unchanged', () => {
+    expect(escapeContentText('')).toBe('');
+    expect(escapeContentText(undefined)).toBeUndefined();
+  });
+});
+
+describe('getRenderText (BP-5787 JSON-safe)', () => {
+  it('passes a Tiptap JSON document through untouched (no throw)', () => {
+    expect(getRenderText(doc as unknown as string)).toBe(doc);
+  });
+
+  it('still converts newlines to <br/> for plain strings', () => {
+    expect(getRenderText('a\nb')).toBe('a<br/>b');
+  });
+});

package/src/brand-page/utils/text.util.ts

@@ -1,17 +1,56 @@
 import { ESCAPED_NEWLINE_CHARACTER } from '../../constants/ui';
 
+/**
+ * BP-5787 — a Tiptap JSON document is an object with `type: 'doc'`.
+ * Inlined here (rather than importing from brand-page-maker) to avoid a
+ * circular import: rich-text-editor.util imports getRenderText from this file.
+ */
+const isTiptapDoc = (value: unknown): value is { type: 'doc' } =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { type?: string }).type === 'doc';
+
+const jsonDocPlainText = (doc: unknown): string => {
+  const parts: string[] = [];
+
+  const walk = (node: any): void => {
+    if (typeof node?.text === 'string') parts.push(node.text);
+
+    node?.content?.forEach(walk);
+  };
+
+  walk(doc);
+
+  return parts.join(' ').replace(/\s+/g, ' ').trim();
+};
+
 export const getRenderText = (text: string): string => {
+  // BP-5787: RTE fields may now be Tiptap JSON objects. Non-strings pass
+  // through untouched so the renderer (TextWrapper) handles them via its
+  // JSON-aware path, instead of throwing on `.replace`.
+  if (typeof text !== 'string') {
+    return text as unknown as string;
+  }
+
   return text.replace(
     new RegExp(`(${ESCAPED_NEWLINE_CHARACTER}|\\n)`, 'g'),
     '<br/>',
   );
 };
 
-export const escapeContentText = (
-  text: string | undefined,
-): string | undefined => {
+// Accepts a legacy inline-HTML string or a Tiptap JSON document (BP-5787):
+// for JSON it returns the concatenated visible text; for HTML it strips tags.
+export const escapeContentText = (text: unknown): string | undefined => {
   if (!text) {
-    return text;
+    return text as undefined;
+  }
+
+  if (isTiptapDoc(text)) {
+    return jsonDocPlainText(text);
+  }
+
+  if (typeof text !== 'string') {
+    return undefined;
   }
 
   return text