@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -1,11 +1,20 @@
 import type { RichTextValue } from '../../brand-page';
 import type { TextStyleDeclaration } from '../../brand-page/models/styles.model';
-import { renderRteToHtml, getRTEColor } from '../../brand-page-maker/utils';
+import { renderRteToHtml } from '@shared/rte-render.util';
+import {
+  getRTEColor,
+  isRoleVarRef,
+  restoreLinkUnderlines,
+} from '../../brand-page-maker/utils';
 import { getRenderText } from '../../brand-page/utils';
 import { ESCAPED_NEWLINE_CHARACTER } from '../../constants/ui';
 import type { Editor } from '@tiptap/vue-3';
 import { isTiptapDocument } from '../parsers/section-tool-arguments';
 
+// A kept phrase matches whole words only: "Taste" must not keep the start of "Tasteful".
+const isWordChar = (char: string | undefined): boolean =>
+  char !== undefined && /[\p{L}\p{N}_]/u.test(char);
+
 /**
  * Applies a TextStyleDeclaration to RTE HTML by loading it into the given
  * (external/headless) Tiptap editor and rewriting inline marks via command
@@ -16,7 +25,8 @@ export const applyStyleToRTEText = (
   externalEditor: Editor,
   contentText: string,
   newContentStyle: TextStyleDeclaration,
-) => {
+  keepRuns?: readonly string[],
+): string => {
   if (!contentText) {
     return contentText;
   }
@@ -27,58 +37,134 @@ export const applyStyleToRTEText = (
 
   externalEditor.commands.setContent(content);
 
-  let chain = externalEditor.chain().selectAll();
-
-  if (newContentStyle?.fontFamily) {
-    chain = chain.setFontFamily(newContentStyle.fontFamily);
+  const kept = new Set(
+    keepRuns?.map((text) => text.trim().toLowerCase()).filter(Boolean),
+  );
+
+  const apply = (from: number, to: number): void => {
+    let chain =
+      from === 0
+        ? externalEditor.chain().selectAll()
+        : externalEditor.chain().setTextSelection({ from, to });
+
+    if (newContentStyle?.fontFamily) {
+      chain = chain.setFontFamily(newContentStyle.fontFamily);
+    }
+
+    if (newContentStyle?.fontSize) {
+      chain = chain.setFontSize(newContentStyle.fontSize);
+    }
+
+    if (newContentStyle?.letterSpacing) {
+      chain = chain.setLetterSpacing(newContentStyle.letterSpacing);
+    }
+
+    if (newContentStyle?.lineHeight) {
+      chain = chain.setLineHeight(newContentStyle.lineHeight);
+    }
+
+    if (newContentStyle?.color) {
+      chain = chain.setMark('textStyle', {
+        color: getRTEColor(newContentStyle.color, 'text'),
+      });
+    }
+
+    if ('backgroundColor' in (newContentStyle || {})) {
+      chain = newContentStyle.backgroundColor
+        ? chain.setMark('highlight', {
+            color: getRTEColor(newContentStyle.backgroundColor, 'background'),
+          })
+        : chain.unsetHighlight();
+    }
+
+    if (newContentStyle?.textAlign) {
+      chain = chain.setTextAlign(newContentStyle.textAlign);
+    }
+
+    // Emphasis is touched only when the style names it: a colour-only rewrite keeps every
+    // <strong>/<em>/<u>/<s>. A role ref replaces the competing marks, as the JSON relink does.
+    const { fontWeight, fontStyle, textDecoration } = newContentStyle ?? {};
+
+    if (newContentStyle && 'textDecoration' in newContentStyle) {
+      chain = textDecoration?.includes('line-through')
+        ? chain.setStrike()
+        : chain.unsetStrike();
+      chain = textDecoration?.includes('underline')
+        ? chain.setUnderline()
+        : chain.unsetUnderline();
+
+      if (isRoleVarRef(textDecoration))
+        chain = chain.setTextDecoration(textDecoration);
+    }
+
+    if (newContentStyle && 'fontWeight' in newContentStyle) {
+      chain = fontWeight === 'bold' ? chain.setBold() : chain.unsetBold();
+
+      if (isRoleVarRef(fontWeight)) chain = chain.setFontWeight(fontWeight);
+    }
+
+    if (newContentStyle && 'fontStyle' in newContentStyle) {
+      chain = fontStyle === 'italic' ? chain.setItalic() : chain.unsetItalic();
+
+      if (isRoleVarRef(fontStyle)) chain = chain.setFontStyle(fontStyle);
+    }
+
+    chain.command(restoreLinkUnderlines(externalEditor)).run();
+  };
+
+  if (!kept.size) {
+    apply(0, externalEditor.state.doc.content.size);
+
+    return externalEditor.getHTML();
   }
 
-  if (newContentStyle?.fontSize) {
-    chain = chain.setFontSize(newContentStyle.fontSize);
-  }
+  const nodes: {
+    from: number;
+    text: string;
+  }[] = [];
 
-  if (newContentStyle?.letterSpacing) {
-    chain = chain.setLetterSpacing(newContentStyle.letterSpacing);
-  }
+  externalEditor.state.doc.descendants((node, pos) => {
+    if (!node.isText || !node.text) return;
 
-  if (newContentStyle?.lineHeight) {
-    chain = chain.setLineHeight(newContentStyle.lineHeight);
-  }
-
-  if (newContentStyle?.color) {
-    chain = chain.setMark('textStyle', {
-      color: getRTEColor(newContentStyle.color, 'text'),
+    nodes.push({
+      from: pos,
+      text: node.text,
     });
-  }
+  });
 
-  if ('backgroundColor' in (newContentStyle || {})) {
-    chain = newContentStyle.backgroundColor
-      ? chain.setMark('highlight', {
-          color: getRTEColor(newContentStyle.backgroundColor, 'background'),
-        })
-      : chain.unsetHighlight();
-  }
+  for (const node of nodes) {
+    const text = node.text.toLowerCase();
+    const ranges: [number, number][] = [];
 
-  if (newContentStyle?.textAlign) {
-    chain = chain.setTextAlign(newContentStyle.textAlign);
-  }
+    kept.forEach((keptText) => {
+      let start = text.indexOf(keptText);
 
-  const hasStrike = newContentStyle?.textDecoration?.includes('line-through');
-  const hasUnderline = newContentStyle?.textDecoration?.includes('underline');
+      while (start !== -1) {
+        const end = start + keptText.length;
+        const isWholeWords =
+          !isWordChar(text[start - 1]) && !isWordChar(text[end]);
 
-  chain = hasStrike ? chain.setStrike() : chain.unsetStrike();
-  chain = hasUnderline ? chain.setUnderline() : chain.unsetUnderline();
+        if (isWholeWords) ranges.push([start, end]);
+
+        start = text.indexOf(keptText, isWholeWords ? end : start + 1);
+      }
+    });
 
-  chain =
-    newContentStyle?.fontWeight === 'bold'
-      ? chain.setBold()
-      : chain.unsetBold();
-  chain =
-    newContentStyle?.fontStyle === 'italic'
-      ? chain.setItalic()
-      : chain.unsetItalic();
+    ranges.sort(([left], [right]) => left - right);
+    let offset = 0;
 
-  chain.run();
+    for (const [start, end] of ranges) {
+      if (offset < start) {
+        apply(node.from + offset, node.from + start);
+      }
+
+      offset = Math.max(offset, end);
+    }
+
+    if (offset < node.text.length) {
+      apply(node.from + offset, node.from + node.text.length);
+    }
+  }
 
   return externalEditor.getHTML();
 };

package/src/metadata-builder/metadata-executor.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from 'vitest';
+import type { BrandPageModel } from '../brand-page/models';
+import { MetadataExecutor } from './metadata-executor';
+import type { MetadataBuilderRequest } from './models';
+import type { SectionBuilderPayload } from './builders/section-builders/base-section-builder';
+
+type RunMark = { type: string; attrs?: Record<string, unknown> };
+
+type RunNode = { type: 'text'; text: string; marks?: RunMark[] };
+
+const rteDoc = (runs: Omit<RunNode, 'type'>[]) => ({
+  type: 'doc',
+  content: [
+    {
+      type: 'paragraph',
+      content: runs.map((run) => ({ type: 'text' as const, ...run })),
+    },
+  ],
+});
+
+const firstRunMarkAttrs = (
+  doc: unknown,
+  type = 'textStyle',
+): Record<string, unknown> | undefined => {
+  const runs = (doc as { content: { content: RunNode[] }[] }).content[0]
+    .content;
+
+  return runs[0]?.marks?.find((m) => m.type === type)?.attrs;
+};
+
+// N2 — bakeContrastAcrossModel (metadata-executor's birth-time contrast bake, run on every call's
+// touched content right after the section builder) must agree with R18's "style colour cleared":
+// a colour-only patch moves the colour onto the run and clears the now-redundant `titleStyle.color`,
+// and the bake that follows in the SAME call must not read the cleared style as "uncoloured" and
+// re-bake a fresh contrast colour onto it — applyTextContrast has to see the colour the run now
+// carries, the same way textItemColour already does for item-level fields.
+describe('MetadataExecutor — the contrast bake honours R18s cleared style colour', () => {
+  it('a colour-only patch recolours the run and leaves *Style.color unset after the executor-level contrast bake', async () => {
+    const model = {
+      v: 1,
+      styles: {
+        backgroundStyles: { style: {} },
+        colors: [],
+      },
+      pageHeaderMobile: {},
+      pageHeaderDesktop: {},
+      pageFooterMobile: { backgroundStyle: {}, iconStyle: {}, socialLinks: [] },
+      pageFooterDesktop: {
+        backgroundStyle: {},
+        iconStyle: {},
+        socialLinks: [],
+      },
+      nav: { orders: [], routes: [] },
+      pages: [
+        {
+          id: 'page-1',
+          contents: [
+            {
+              id: 'about-1',
+              type: 'about-section',
+              title: rteDoc([
+                {
+                  text: 'Fine',
+                  marks: [{ type: 'textStyle', attrs: { color: '#111111' } }],
+                },
+              ]),
+              titleStyle: { color: '#111111' },
+              paragraph: 'A paragraph',
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+
+    const request: MetadataBuilderRequest<SectionBuilderPayload> = {
+      id: 'test-id',
+      type: 'update-about-section' as MetadataBuilderRequest['type'],
+      payload: {
+        sectionType: 'about-section',
+        contentId: 'about-1',
+        arguments: { title_style: { color: '#f8f2e9' } },
+      } as unknown as SectionBuilderPayload,
+    };
+
+    const { results } = await new MetadataExecutor().executeAsync(model, [
+      request,
+    ]);
+
+    expect(results[0].errors).toBeUndefined();
+
+    const content = results[0].model.pages[0].contents[0] as unknown as {
+      title: unknown;
+      titleStyle: Record<string, unknown>;
+    };
+
+    // R18 ran: the colour is on the run, not the style.
+    expect(firstRunMarkAttrs(content.title)?.color).toBe('#f8f2e9');
+    // N2: the contrast bake that ran right after must leave it that way.
+    expect(content.titleStyle.color).toBeUndefined();
+  });
+
+  // R1 — a doc with only SOME of its runs coloured (an accent word) is not "already coloured":
+  // the bake must still run, or the uncoloured runs fall back to the inherited colour.
+  it('bakes a contrast colour when only an accent run is coloured and the style carries no colour', async () => {
+    const model = {
+      v: 1,
+      styles: {
+        backgroundStyles: { style: {} },
+        colors: [],
+      },
+      pageHeaderMobile: {},
+      pageHeaderDesktop: {},
+      pageFooterMobile: { backgroundStyle: {}, iconStyle: {}, socialLinks: [] },
+      pageFooterDesktop: {
+        backgroundStyle: {},
+        iconStyle: {},
+        socialLinks: [],
+      },
+      nav: { orders: [], routes: [] },
+      pages: [
+        {
+          id: 'page-1',
+          contents: [
+            {
+              id: 'about-1',
+              type: 'about-section',
+              title: rteDoc([
+                {
+                  text: 'Plain ',
+                },
+                {
+                  text: 'accent',
+                  marks: [{ type: 'textStyle', attrs: { color: '#111111' } }],
+                },
+              ]),
+              titleStyle: {},
+              paragraph: 'A paragraph',
+            },
+          ],
+        },
+      ],
+    } as unknown as BrandPageModel;
+
+    const request: MetadataBuilderRequest<SectionBuilderPayload> = {
+      id: 'test-id',
+      type: 'update-about-section' as MetadataBuilderRequest['type'],
+      payload: {
+        sectionType: 'about-section',
+        contentId: 'about-1',
+        arguments: { paragraph: 'An updated paragraph' },
+      } as unknown as SectionBuilderPayload,
+    };
+
+    const { results } = await new MetadataExecutor().executeAsync(model, [
+      request,
+    ]);
+
+    expect(results[0].errors).toBeUndefined();
+
+    const content = results[0].model.pages[0].contents[0] as unknown as {
+      titleStyle: Record<string, unknown>;
+    };
+
+    // The style's own colour was unset and only one run carried colour, so the bake must have run.
+    expect(content.titleStyle.color).toBeDefined();
+  });
+});

package/src/metadata-builder/metadata-executor.ts

@@ -1,6 +1,7 @@
 import cloneDeep from 'lodash.clonedeep';
 import { type BrandPageModel } from '../brand-page/models';
 import { referencifyModelColors } from '../brand-page/utils/color-palette-referencify.util';
+import { applyTextContrast } from '../brand-page/utils/container-text-color.util';
 import {
   type MetadataBuilderRequest,
   type MetadataExecutorResult,
@@ -46,6 +47,31 @@ type BuilderConstructor = new (
   eventTracker?: EventTracker,
 ) => BaseMetadataBuilder;
 
+/**
+ * BP-5969 (ADR-0020): bake a birth-time contrast colour into an uncoloured section's text so
+ * the AI path matches the maker's Add path (which bakes via `applyTextContrast` in
+ * `addItemByType`). Runs AFTER referencify, so section surfaces are palette refs the
+ * contrast resolver can read. Limited to `touchedContentIds` (the sections this call's own
+ * requests created or updated, via each result's `contentId`) — sweeping every section on every
+ * apply follows the prompt for sections it never touched too, recolouring content the call
+ * didn't ask about and re-writing RTE style objects a migration had already stripped. Mutates
+ * `model` in place and returns it.
+ */
+const bakeContrastAcrossModel = (
+  model: BrandPageModel,
+  touchedContentIds: ReadonlySet<string>,
+): BrandPageModel => {
+  model.pages?.forEach((page) => {
+    page.contents?.forEach((content) => {
+      if (content.id && touchedContentIds.has(content.id)) {
+        applyTextContrast(content, model.styles, model.brandPageType);
+      }
+    });
+  });
+
+  return model;
+};
+
 // Lazy initialization to avoid circular dependency issues
 const getBuilderRegistry = (): Record<BuilderType, BuilderConstructor> => ({
   // Section builders (create)
@@ -196,6 +222,10 @@ export class MetadataExecutor {
       model = result.model;
     }
 
+    const touchedContentIds = new Set(
+      results.flatMap((result) => (result.contentId ? [result.contentId] : [])),
+    );
+
     return {
       // The inbound half of the AI colour bridge. The AI answers in literals (it
       // was sent literals — see `minifyBrandPageMetadata`) and migration-21 is
@@ -203,7 +233,10 @@ export class MetadataExecutor {
       // half hex, and editing a palette role silently skips every section the AI
       // touched. Mutates `model` in place — minting into `model.styles.colors` — and
       // returns it; touches no store.
-      model: referencifyModelColors(model),
+      model: bakeContrastAcrossModel(
+        referencifyModelColors(model),
+        touchedContentIds,
+      ),
       results,
     };
   }

package/src/metadata-builder/models.ts

@@ -105,6 +105,8 @@ export interface BuilderResult {
   request: MetadataBuilderRequest;
   model: BrandPageModel;
   errors?: string[];
+  /** Non-failing feedback for an accepted tool call that dropped unsupported input. */
+  warnings?: string[];
   /**
    * Set by the UndoBuilder to signal that the caller should restore the
    * website to the snapshot taken before the most recent change-producing

package/src/metadata-builder/parsers/ai-toolcall-parser.ts

@@ -5,6 +5,7 @@ import type {
   NavigationDisplayType,
 } from '../../brand-page/constants';
 import type { SectionType, TextStyleArguments } from './section-tool-arguments';
+import type { TextStyleType } from '../../brand-page/models';
 
 // Tool names — must match the function names generated by the AI pipeline.
 // Section tools follow the pattern: build_{sectionType}_section
@@ -237,6 +238,11 @@ export interface UpdateFooterArguments {
   mobile?: ViewportFooterOverrides;
 }
 
+/**
+ * A role's typography patch. A sent `fontWeight` / `fontStyle` / `textDecoration` relinks the
+ * role's existing content even when it equals the stored role (the pipeline sends them only when
+ * the user asked); the other properties relink only when they change (`global-role-propagation`).
+ */
 export interface TextStyleOptionStyle {
   fontFamily?: string;
   fontSize?: string;
@@ -263,13 +269,23 @@ export interface UpdateGlobalStylesArguments {
   textStyles?: {
     /** Retired — accepted from the pipeline but ignored. */
     style?: { color?: string };
-    textFontFamily?: string;
-    textStyleOptions?: {
-      titles?: { style?: TextStyleOptionStyle; isModified?: boolean };
-      headings?: { style?: TextStyleOptionStyle; isModified?: boolean };
-      paragraphs?: { style?: TextStyleOptionStyle; isModified?: boolean };
-      buttons?: { style?: TextStyleOptionStyle; isModified?: boolean };
-    };
+    /** Retired — accepted from the pipeline but ignored (`0036-retire-text-font-family.md`). */
+    textFontFamily?: unknown;
+    // BP-5969: keyed by any text role — the 10 canonical roles the page renders, or the 4 legacy
+    // roles still on the model for un-migrated data. The pipeline emits legacy keys today and
+    // canonical keys after the widening ships; accepting both keeps the transition non-breaking.
+    textStyleOptions?: Partial<
+      Record<
+        TextStyleType,
+        { style?: TextStyleOptionStyle; isModified?: boolean }
+      >
+    >;
+    /**
+     * BP-5969 (R16) — the run texts the user explicitly asked to keep during this site-wide
+     * change. The library skips relinking a run or a plain field whose trimmed text matches one
+     * of these, case-insensitively; every other run of the changed role/property still relinks.
+     */
+    keepRuns?: string[];
   };
   buttonStyles?: {
     style?: { color?: string; borderColor?: string; backgroundColor?: string };

package/src/metadata-builder/parsers/section-tool-arguments.ts

@@ -5,7 +5,10 @@
  * Every field defined there has a corresponding TS field here.
  */
 
-import type { ContentType } from '../../brand-page/models';
+import type {
+  ContentType,
+  CanonicalTextStyleType,
+} from '../../brand-page/models';
 
 // ---------------------------------------------------------------------------
 // Section type — the subset of ContentType the AI builder supports
@@ -45,6 +48,10 @@ export interface TiptapMark {
     fontFamily?: string;
     letterSpacing?: string;
     lineHeight?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    textDecoration?: string;
+    textDecorationReset?: boolean;
   };
 }
 
@@ -88,6 +95,15 @@ export const isTiptapDocument = (value: unknown): value is TiptapDocument =>
 // ---------------------------------------------------------------------------
 
 export interface TextStyleArguments {
+  /**
+   * BP-5969 — the canonical text role this element links to. The AI names a role (roles are the
+   * site's predefined styling); typography then follows the role and only a genuinely divergent
+   * property is sent below as a sparse override. Absent, a retired key, or `none` reconnects
+   * instead (`applyAiStyle`, `reconnectTextStyle`): the field's starting role, else the retired
+   * role's successor, else the role nearest its size — keeping the look as overrides, never fully
+   * detached from a role.
+   */
+  textStyleType?: CanonicalTextStyleType | null;
   fontSize?: string | null;
   color?: string | null;
   fontWeight?: string | null;
@@ -115,6 +131,8 @@ export interface TextStyleArguments {
  * (`_button_text_style_field`) for the AI-side mirror.
  */
 export interface ButtonTextStyleArguments {
+  /** BP-5969 — the canonical role a button label links to. See `TextStyleArguments.textStyleType`. */
+  textStyleType?: CanonicalTextStyleType | null;
   color?: string | null;
   fontSize?: string | null;
   fontWeight?: string | null;
@@ -295,8 +313,10 @@ export interface SocialLink {
 }
 
 export interface SocialLinksSectionArguments {
+  title?: RichTextField;
   links?: SocialLink[];
   icon_style?: 'none' | 'square' | 'circle';
+  title_style?: TextStyleArguments;
   /** Style for the social-icon SVG fill (filled from the palette by the slot router). */
   icon_fill_style?: TextStyleArguments;
   /** Style for the icon container background (used when icon_style is 'square' or 'circle'). */