@designcrowd/library.brand-page 6.2.11-builder-v2-1 → 6.2.12

package/src/metadata-builder/builders/section-field-utils.ts

@@ -1,16 +1,31 @@
+import type { JSONContent } from '@tiptap/vue-3';
 import type { Content } from '../../brand-page/models';
 import { BUTTON_LINK_TYPE } from '../../brand-page/models';
 import type { ButtonLinkType } from '../../brand-page/models';
-import type {
-  TextStyleOptions,
-  TextStyleType,
-} from '../../brand-page/models/styles.model';
+import type { TextStyleOptions } from '../../brand-page/models/styles.model';
+import type { CanonicalTextStyleType } from '../../brand-page/models/styles.model';
+import {
+  normalizeTextStyleAgainstRole,
+  omitTypography,
+} from '../../brand-page/utils/text-style.util';
+import {
+  computeLegacyTargets,
+  contentFieldReconnectSpec,
+  isCanonicalTextStyleType,
+  reconnectTextStyle,
+  type ReconnectSpec,
+} from '../../brand-page/utils/text-role-reconnect.util';
 import {
   isTiptapDocument,
   type SectionToolArguments,
 } from '../parsers/section-tool-arguments';
 import { hasRTEContent } from '../../brand-page-maker/utils';
 import { useExternalRichTextEditor } from '../../brand-page-maker/composables/rich-text-editor/useRichTextEditor';
+import { relinkDocToRole } from '../../brand-page-maker/utils/rich-text-editor.util';
+import {
+  docHasColourableRun,
+  setRteTextColor,
+} from '../../shared/color-strategies/rte-color';
 import { applyStyleToRTEText } from '../helpers/rte.helpers';
 import type { TextStyleDeclaration } from '../../brand-page/models';
 import { getSectionFieldMap, getStyleFieldMap } from './section-field-maps';
@@ -110,6 +125,13 @@ export const applyScalarFields = (
 /**
  * Convert AI-sent style value to the format expected by the model.
  * - letterSpacing: unitless 0-100 → em string (e.g., 50 → '0.5em')
+ * - lineHeight: coerced to a plain numeric string, UNSNAPPED — snapping here would shift a
+ *   value that's actually equal to its role (e.g. 1.25) off that equality before
+ *   `applyAiStyle` gets a chance to drop it as a role-equal non-override (R2). Only a value
+ *   that survives the role-equal check is snapped (`snapLineHeight`, in `applyAiStyle`), and the
+ *   drop runs AGAIN after snapping: a role can itself hold a non-grid value (e.g. heading3's
+ *   native 1.25), so comparing before snapping catches an exact match at full precision, and
+ *   re-comparing after catches a snap that LANDS the override exactly on the role's value.
  * - null → '' (explicitly clear/reset the property)
  * - everything else passes through as-is
  */
@@ -123,72 +145,168 @@ export const normalizeStyleValue = (key: string, value: unknown): unknown => {
   }
 
   if (key === 'lineHeight') {
-    // Snap to 0.1 increments to match the UI slider step
     const num = typeof value === 'number' ? value : parseFloat(String(value));
 
-    if (!isNaN(num)) return String(Math.floor(num * 10) / 10);
+    if (!isNaN(num)) return String(num);
   }
 
   return value;
 };
 
-/**
- * When an executor is about to mark a content-level text style "custom" by
- * clearing `textStyleType`, the resolved preset values (font, size, spacing,
- * etc.) must first be copied onto the style — otherwise the renderer falls
- * back to browser defaults because `textStyleType` no longer points at a
- * preset.
- *
- * The category is read from the existing `style.textStyleType`, which is the
- * authoritative per-section + per-field reference set by the content factory.
- * Existing style values win over preset defaults (the content may already
- * carry user overrides on top of the preset).
- */
-export const resolveGlobalPresetIntoStyle = (
-  style: object | undefined,
-  textStyleOptions: TextStyleOptions | undefined,
+/** Snap a line-height value to the UI slider's 0.1 step. Pure — returns a new object. */
+const snapLineHeight = (
+  style: Record<string, unknown>,
 ): Record<string, unknown> => {
-  const base = { ...((style as Record<string, unknown>) ?? {}) };
-  const currentTextStyleType = base.textStyleType as TextStyleType | undefined;
+  const { lineHeight } = style;
 
-  if (!currentTextStyleType || !textStyleOptions?.[currentTextStyleType]) {
-    base.textStyleType = undefined;
+  if (typeof lineHeight !== 'string') return style;
 
-    return base;
-  }
+  const num = parseFloat(lineHeight);
 
-  const presetStyle = textStyleOptions[currentTextStyleType].style;
-  const presetDefaults: Record<string, unknown> = {};
+  if (isNaN(num)) return style;
 
-  for (const [k, v] of Object.entries(presetStyle)) {
-    if (k === 'textStyleType' || v === undefined) continue;
+  return { ...style, lineHeight: String(Math.floor(num * 10) / 10) };
+};
+
+/**
+ * Whether this call is a REAL canonical switch (R19): both the stored and the INCOMING role (the
+ * raw value the call sent, before any reconnect fallback) are canonical, and differ. Decided once
+ * from `incoming.textStyleType` and shared by `applyAiStyle` (which resets the style object) and
+ * the caller of `applyStoredDocStyleConsequences` (which resets the stored doc), so both agree: a
+ * retired-key call reconnects in `applyAiStyle` (not a switch — it keeps the look as overrides) but
+ * can still land on a canonical role that differs from the stored one, which deriving it from the
+ * RESULT instead would misread as a switch and relink a doc whose overrides were meant to survive.
+ */
+export const isRealCanonicalSwitch = (
+  existingRole: unknown,
+  incomingRole: unknown,
+): boolean =>
+  isCanonicalTextStyleType(existingRole) &&
+  isCanonicalTextStyleType(incomingRole) &&
+  incomingRole !== existingRole;
+
+/**
+ * Apply an AI-sent style to a field, honouring the role model under partial-update semantics
+ * (a property present = update; absent = no change).
+ *
+ * The role is the EFFECTIVE one — `incoming.textStyleType ?? existing.textStyleType` — so a sparse
+ * update that omits the role KEEPS the element's current role. When that role is canonical, keep
+ * the link and store a sparse override: incoming props layer on and `normalizeTextStyleAgainstRole`
+ * drops any prop equal to the role, so the page-scoped role CSS drives it and a later global edit
+ * repaints the block.
+ *
+ * A REAL canonical switch (both the old and the new role are canonical, and differ — R19) is a
+ * reset, not a patch: it starts from `omitTypography(existing)` before layering this call's own
+ * style on top, so a stale override from the old role doesn't survive as a bogus override of the
+ * new one. Colour, background, alignment and `applyAutoScale` aren't typography, so they carry
+ * over untouched; the call's own text and overrides win (they're applied after the reset).
+ *
+ * Any other role — a retired key the pipeline still emits, `none`, or no role at all — reconnects
+ * the way the upgrade does (`reconnectTextStyle`, with the field's `spec`): its starting role, else
+ * the retired role's successor, else the role nearest its size, keeping its look as overrides.
+ */
+export const applyAiStyle = <T extends object>(
+  existing: T | undefined,
+  incoming: Record<string, unknown>,
+  textStyleOptions: TextStyleOptions | undefined,
+  spec: ReconnectSpec = {},
+): T => {
+  const existingRole = (existing as Record<string, unknown> | undefined)
+    ?.textStyleType;
+  const role = incoming.textStyleType ?? existingRole;
+  const base = isRealCanonicalSwitch(existingRole, incoming.textStyleType)
+    ? omitTypography(existing ?? ({} as T))
+    : (existing ?? {});
+  const merged = { ...base, ...incoming, textStyleType: role } as T;
+
+  if (isCanonicalTextStyleType(role)) {
+    const normalized = normalizeTextStyleAgainstRole(
+      merged,
+      textStyleOptions,
+    ) as Record<string, unknown>;
+
+    // Snap and re-check only a lineHeight that is BOTH this call's own (not one inherited
+    // untouched from the stored style — an unrelated patch must not silently rewrite it) AND
+    // survived the first role-equal pass as a genuine override.
+    if ('lineHeight' in incoming && 'lineHeight' in normalized) {
+      return normalizeTextStyleAgainstRole(
+        snapLineHeight(normalized),
+        textStyleOptions,
+      ) as T;
+    }
 
-    presetDefaults[k] = v;
+    return normalized as T;
   }
 
-  return { ...presetDefaults, ...base, textStyleType: undefined };
+  return reconnectTextStyle(
+    merged,
+    computeLegacyTargets(textStyleOptions),
+    textStyleOptions,
+    spec,
+  );
 };
 
 /**
- * Applies per-element style overrides while detaching the element from any
- * global text-style preset. When a style is bound to a `textStyleType` preset,
- * the renderer (`getCopyrightTextStyle` / `getTextStyleByContentTextStyle`)
- * replaces the whole style with that preset and discards per-element values such
- * as `fontFamily`. Resolving the preset in and clearing `textStyleType` makes the
- * override stick — the same disconnect rule section content follows.
+ * BP-5969 (R18, R19) — what a style-only patch (no new text in the same call) does to an already-
+ * stored RTE doc. A real role switch relinks every run to the new role (the document-level half of
+ * the reset `applyAiStyle` already gave the style object above), keeping any typography the call's
+ * own `nextStyle` still overrides via `relinkDocToRole`'s `styleOverrides` arg. A colour-only patch,
+ * OR a colour riding along with a switch in the same call (James Joung, 2026-10-01: a role switch
+ * and a recolour with no text both apply), recolours every run and clears the now-redundant style
+ * colour (kept only when the doc has no run to hold it — an empty field's colour waits for the
+ * maker's first keystroke, `buildInitialMarks`). Both consequences can apply to one call: the
+ * switch's relink runs first, then the colour branch recolours the relinked doc.
  *
- * Idempotent: once `textStyleType` is cleared, subsequent calls just merge the
- * updates without re-resolving a preset.
+ * No-op for anything but a stored Tiptap document — a legacy HTML string is handled by the caller's
+ * own `ApplyColorToRTE` rewrite instead.
  */
-export const applyDetachedStyleOverride = <T extends object>(
-  current: T | undefined,
-  updates: Partial<T>,
+export const applyStoredDocStyleConsequences = (
+  existingText: unknown,
+  existingRole: unknown,
+  nextStyle: Record<string, unknown>,
+  incomingStyle: Record<string, unknown>,
   textStyleOptions: TextStyleOptions | undefined,
-): T =>
-  ({
-    ...resolveGlobalPresetIntoStyle(current, textStyleOptions),
-    ...updates,
-  }) as T;
+): unknown => {
+  if (!isTiptapDocument(existingText)) return existingText;
+
+  // Decided from the call's own RAW textStyleType (via isRealCanonicalSwitch), the same test
+  // applyAiStyle already made for the style object, not re-derived from nextStyle.textStyleType:
+  // a retired-key call reconnects (not a switch) in applyAiStyle but can still land on a canonical
+  // role that differs from the stored one, which re-deriving from the RESULT would misread as a
+  // switch. When it IS a real switch, nextStyle.textStyleType equals incomingStyle.textStyleType.
+  const isRealSwitch = isRealCanonicalSwitch(
+    existingRole,
+    incomingStyle.textStyleType,
+  );
+  const nextRole = nextStyle.textStyleType;
+
+  let text: unknown = existingText;
+
+  if (isRealSwitch) {
+    const roleStyle = textStyleOptions?.[nextRole as CanonicalTextStyleType]
+      ?.style as Record<string, unknown> | undefined;
+
+    text = relinkDocToRole(text as JSONContent, roleStyle, nextStyle);
+  }
+
+  const newColor = incomingStyle.color;
+
+  if (
+    typeof newColor === 'string' &&
+    newColor &&
+    docHasColourableRun(text as JSONContent)
+  ) {
+    const recoloured = setRteTextColor(text, newColor);
+
+    if (recoloured) {
+      delete nextStyle.color;
+
+      return recoloured;
+    }
+  }
+
+  return text;
+};
 
 /**
  * Rewrites the stored RTE HTML's inline colour marks. Injectable for tests;
@@ -235,35 +353,50 @@ export const applyStyleFields = (
         if (normalized !== undefined) filtered[k] = normalized;
       }
 
-      const resolved = resolveGlobalPresetIntoStyle(
-        content[modelKey] as object,
+      const existingStyle = content[modelKey] as
+        | Record<string, unknown>
+        | undefined;
+      const existingRole = existingStyle?.textStyleType;
+
+      record[modelKey] = applyAiStyle(
+        existingStyle as object,
+        filtered,
         textStyleOptions,
+        contentFieldReconnectSpec(sectionType, modelKey),
       );
 
-      record[modelKey] = { ...resolved, ...filtered, textStyleType: undefined };
-
-      // A colour patch without new text leaves the field's EXISTING inline
-      // textStyle marks in place — and inline marks override every style layer
-      // at render, so the old colour survives on a recoloured band (invisible
-      // text, AI QA 2026-07-05 rerun). Propagate the new colour into the
-      // stored HTML, mirroring global-font-propagation for font families.
+      // A style-only patch (no new text in this call) leaves the field's EXISTING inline
+      // textStyle marks in place — and inline marks override every style layer at render, so the
+      // old look survives a recoloured band (invisible text, AI QA 2026-07-05 rerun) or a role
+      // switch (the overrides reset above, but the stored doc's runs don't follow on their own).
+      // Propagate the consequence into the stored text, mirroring global-role-propagation.
       const textKey = modelKey.endsWith('Style')
         ? modelKey.slice(0, -'Style'.length)
         : undefined;
       const textAiKey = aiKey.endsWith('_style')
         ? aiKey.slice(0, -'_style'.length)
         : undefined;
-      const newColor = filtered.color;
-
-      if (
-        textKey &&
-        typeof newColor === 'string' &&
-        newColor &&
-        !(textAiKey && textAiKey in args) &&
-        typeof record[textKey] === 'string' &&
-        hasRTEContent(record[textKey] as string)
-      ) {
-        record[textKey] = applyColorToHtml(record[textKey] as string, newColor);
+      const textSentThisCall = !!(textAiKey && textAiKey in args);
+
+      if (textKey && !textSentThisCall) {
+        const existingText = record[textKey];
+
+        if (isTiptapDocument(existingText)) {
+          record[textKey] = applyStoredDocStyleConsequences(
+            existingText,
+            existingRole,
+            record[modelKey] as Record<string, unknown>,
+            filtered,
+            textStyleOptions,
+          );
+        } else if (
+          typeof filtered.color === 'string' &&
+          filtered.color &&
+          typeof existingText === 'string' &&
+          hasRTEContent(existingText)
+        ) {
+          record[textKey] = applyColorToHtml(existingText, filtered.color);
+        }
       }
     }
   } finally {

package/src/metadata-builder/builders/section-rules/global-styles.rules.ts

@@ -2,32 +2,57 @@ import type {
   UpdateGlobalStylesArguments,
   TextStyleOptionStyle,
 } from '../../parsers/ai-toolcall-parser';
-import type { TextStyleType } from '../../../brand-page/models/styles.model';
-import { STYLE_RULES } from '../../sanitizers/sanitizer-rules';
+import {
+  CANONICAL_TEXT_STYLE_TYPES,
+  LEGACY_TEXT_STYLE_TYPES,
+  type TextStyleType,
+} from '../../../brand-page/models/styles.model';
 import { validateStringStyleAttrs } from '../../sanitizers/section-args-validator';
 
 export const TEXT_STYLE_OPTION_KEYS: TextStyleType[] = [
-  'titles',
-  'headings',
-  'paragraphs',
-  'buttons',
+  ...CANONICAL_TEXT_STYLE_TYPES,
+  ...LEGACY_TEXT_STYLE_TYPES,
 ];
 
+/** Role definitions accept numeric wire values but store their canonical string representation. */
+export const normalizeGlobalTextStyleOption = (
+  style: TextStyleOptionStyle,
+): TextStyleOptionStyle => {
+  const normalized = { ...style } as TextStyleOptionStyle;
+  const lineHeight: unknown = style.lineHeight;
+  const fontWeight: unknown = style.fontWeight;
+
+  if (typeof lineHeight === 'number' && !isNaN(lineHeight)) {
+    normalized.lineHeight = String(lineHeight);
+  } else if (lineHeight != null) {
+    const value = parseFloat(String(lineHeight).trim());
+
+    if (!isNaN(value) && String(lineHeight).trim() !== String(value)) {
+      normalized.lineHeight = String(value);
+    }
+  }
+
+  if (typeof fontWeight === 'number' && !isNaN(fontWeight)) {
+    normalized.fontWeight = String(fontWeight);
+  }
+
+  return normalized;
+};
+
 type GlobalStyleCheck = (args: UpdateGlobalStylesArguments) => string | null;
 
 export const GLOBAL_STYLE_CHECKS: GlobalStyleCheck[] = [
-  // textFontFamily: must be a recognized camelCase font key (e.g. 'playfairDisplay')
   (args) => {
-    const font = args.textStyles?.textFontFamily;
+    const keepRuns = args.textStyles?.keepRuns;
 
-    if (font == null) return null;
+    if (keepRuns == null) return null;
 
-    return !STYLE_RULES.fontFamilyKeys.has(font)
-      ? `"textFontFamily" "${font}" is not a recognized font family key`
+    return !Array.isArray(keepRuns) ||
+      keepRuns.some((run) => typeof run !== 'string')
+      ? `"textStyles.keepRuns" must be an array of strings`
       : null;
   },
 
-  // textStyleOptions[category].style — fontSize, fontFamily, lineHeight, letterSpacing
   ...TEXT_STYLE_OPTION_KEYS.map(
     (category): GlobalStyleCheck =>
       (args) => {
@@ -37,7 +62,7 @@ export const GLOBAL_STYLE_CHECKS: GlobalStyleCheck[] = [
 
         return validateStringStyleAttrs(
           `textStyleOptions.${category}.style`,
-          style as TextStyleOptionStyle,
+          normalizeGlobalTextStyleOption(style as TextStyleOptionStyle),
         );
       },
   ),

package/src/metadata-builder/builders/section-rules/social-links.rules.ts

@@ -1,18 +1,23 @@
 import { SOCIAL_LINKS_ICON_DISPLAY_STYLES } from '../../../brand-page/models';
+import { MAX_TITLE_LENGTH } from '../../../brand-page/constants/font.constants';
 import {
   enumCheck,
   itemCapCheck,
   runChecks,
+  styleCheck,
   type SectionCheck,
   type ValidationContext,
 } from '../../sanitizers/section-args-validator';
+import { textAndRteChecks } from '../../sanitizers/rte-schema-check';
 
 const CHECKS: SectionCheck[] = [
+  ...textAndRteChecks('title', MAX_TITLE_LENGTH),
   enumCheck(
     'icon_style',
     Object.keys(SOCIAL_LINKS_ICON_DISPLAY_STYLES),
     'social-links',
   ),
+  styleCheck('title_style'),
   itemCapCheck(
     { brandSite: 4, brandPage: 4, arrayField: 'links' },
     'social-links',

package/src/metadata-builder/helpers/rte.helpers.test.ts

@@ -0,0 +1,101 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import type { Editor } from '@tiptap/vue-3';
+import { useExternalRichTextEditor } from '../../brand-page-maker/composables/rich-text-editor/useRichTextEditor';
+import { applyStyleToRTEText } from './rte.helpers';
+
+describe('applyStyleToRTEText', () => {
+  let editor: Editor | undefined;
+
+  afterEach(() => editor?.destroy());
+
+  it('keeps a named word in legacy HTML while relinking the surrounding text', () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><span style="font-family: Georgia">Taste</span> <span style="font-family: Georgia">the rest</span></p>',
+      { fontFamily: 'Oswald' },
+      ['Taste'],
+    );
+
+    expect(html).toContain('font-family: Georgia;">Taste</span>');
+    expect(html).toContain('font-family: Oswald;">the rest</span>');
+  });
+
+  it('does not keep text that only exists across separate text nodes', () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><span style="font-family: Georgia">Ta</span><span style="font-family: Georgia">ste</span></p>',
+      { fontFamily: 'Oswald' },
+      ['Taste'],
+    );
+
+    expect(html).not.toContain('font-family: Georgia;">Ta</span>');
+    expect(html).not.toContain('font-family: Georgia;">ste</span>');
+  });
+
+  it('keeps a named word only where it stands as a whole word', () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><span style="font-family: Georgia">Tasteful Taste</span></p>',
+      { fontFamily: 'Oswald' },
+      ['Taste'],
+    );
+
+    expect(html).toContain('font-family: Oswald;">Tasteful </span>');
+    expect(html).toContain('font-family: Georgia;">Taste</span>');
+  });
+
+  it("keeps a link's underline when a decoration ref clears the others", () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><u>Plain</u> <a href="https://example.com"><u>link</u></a></p>',
+      { textDecoration: 'var(--role-text-decoration)' },
+    );
+
+    expect(html).toContain(
+      '<span style="text-decoration: var(--role-text-decoration);">Plain </span>',
+    );
+    expect(html).toContain(
+      '<u><span style="text-decoration: var(--role-text-decoration);">link</span></u>',
+    );
+  });
+
+  it('a weight ref drops <strong> on every run except a kept word', () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><strong>Fresh</strong> <strong>Taste</strong></p>',
+      { fontWeight: 'var(--role-font-weight)' },
+      ['Taste'],
+    );
+
+    expect(html).toContain(
+      '<span style="font-weight: var(--role-font-weight);">Fresh </span>',
+    );
+    expect(html).toContain('<strong>Taste</strong>');
+    expect(html).not.toContain('<strong>Fresh');
+  });
+
+  it('a style that names no emphasis leaves <strong>, <em>, <u> and <s> alone', () => {
+    editor = useExternalRichTextEditor().externalEditor;
+
+    const html = applyStyleToRTEText(
+      editor,
+      '<p><strong>Bold</strong> <em>Italic</em> <u>Under</u> <s>Struck</s></p>',
+      { color: '#ff0000', fontFamily: 'Oswald' },
+    );
+
+    expect(html).toContain('<strong>');
+    expect(html).toContain('<em>');
+    expect(html).toContain('<u>');
+    expect(html).toContain('<s>');
+  });
+});