@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -1,6 +1,260 @@
 import { describe, expect, it } from 'vitest';
-import type { Content } from '../../brand-page/models';
-import { applyStyleFields } from './section-field-utils';
+import type { Content, TextStyleDeclaration } from '../../brand-page/models';
+import { TextStyles } from '../../brand-page/models';
+import type { TextStyleOptions } from '../../brand-page/models/styles.model';
+import { DETACHED_UNSET_EFFECTIVE } from '../../brand-page/utils/text-role-reconnect.util';
+import {
+  resolveTextStyle,
+  TEXT_STYLE_CASCADE_PROPS,
+} from '../../brand-page/utils/text-style.util';
+import { DEFAULT_LINK_COLOR } from '../../constants/rich-text-editor.constants';
+import { fillRteRunTypography } from '../../brand-page/utils/text-role-css.util';
+import {
+  applyAiStyle,
+  applyStyleFields,
+  normalizeStyleValue,
+} from './section-field-utils';
+
+const OPTIONS = {
+  heading1: { style: { fontSize: '2.5em', fontFamily: 'Lato' } },
+} as unknown as TextStyleOptions;
+
+// The seven typography properties a field renders with. An unset one renders its inherited
+// default; family and size left unset inherit from the page, so they stay undefined here.
+const lookOf = (
+  style: TextStyleDeclaration,
+  role: object | undefined,
+): Record<string, string | undefined> => {
+  const resolved = resolveTextStyle(style, role) as Record<
+    string,
+    string | undefined
+  >;
+
+  return Object.fromEntries(
+    TEXT_STYLE_CASCADE_PROPS.map((prop) => [
+      prop,
+      resolved[prop] || DETACHED_UNSET_EFFECTIVE[prop],
+    ]),
+  );
+};
+
+/** BP-5969 — role-aware style apply for the AI builder (Phase 1b). */
+describe('applyAiStyle', () => {
+  it('keeps the role link and stores a sparse override when the AI names a canonical role', () => {
+    const out = applyAiStyle(
+      { textStyleType: 'heading1', fontFamily: 'Lato' },
+      // AI: size equals the role (should drop), family differs (should keep)
+      { textStyleType: 'heading1', fontSize: '2.5em', fontFamily: 'Georgia' },
+      OPTIONS,
+    );
+
+    expect(out).toEqual({ textStyleType: 'heading1', fontFamily: 'Georgia' });
+  });
+
+  it('keeps the existing role on a sparse update that omits textStyleType (partial update)', () => {
+    const out = applyAiStyle(
+      { textStyleType: 'heading1' },
+      { fontFamily: 'Georgia' }, // update omits the role → role must be preserved
+      OPTIONS,
+    ) as Record<string, unknown>;
+
+    expect(out.textStyleType).toBe('heading1'); // role preserved, not detached
+    expect(out.fontFamily).toBe('Georgia'); // sparse override kept
+    expect(out.fontSize).toBeUndefined(); // NOT baked in — the role drives it
+  });
+
+  it.each([
+    ['2.5em', undefined, 'heading4'],
+    [undefined, undefined, 'paragraph1'],
+    ['2.5em', 'paragraph2', 'paragraph2'],
+  ] as const)(
+    'reconnects a field on no role (size %s, starting role %s) to the nearest role %s, look kept',
+    (fontSize, startingRole, expectedRole) => {
+      const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+      const existing: TextStyleDeclaration = {
+        fontFamily: 'Lato',
+        ...(fontSize && { fontSize }),
+      };
+      const incoming = { fontFamily: 'Georgia' };
+
+      const out = applyAiStyle(existing, incoming, options, { startingRole });
+
+      const kept = lookOf({ ...existing, ...incoming }, undefined);
+      const look = lookOf(out, options[expectedRole].style);
+
+      expect(out.textStyleType).toBe(expectedRole);
+      expect(out.fontFamily).toBe('Georgia');
+
+      for (const [prop, value] of Object.entries(kept)) {
+        if (value !== undefined) expect(look[prop]).toBe(value);
+      }
+    },
+  );
+
+  it('reconnects a retired role the AI names to its successor, keeping its look (buttons → button)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.buttons.style.fontFamily = 'Oswald';
+
+    const out = applyAiStyle(
+      { textStyleType: 'heading1' },
+      { textStyleType: 'buttons', fontSize: '1.25em' },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(out.textStyleType).toBe('button');
+    expect(out.fontSize).toBe('1.25em'); // the AI's own value wins
+    expect(out.fontFamily).toBe('Oswald'); // the buttons look, kept as an override
+    expect(out.lineHeight).toBe(options.buttons.style.lineHeight); // 1.5, not Button text's 1.2
+  });
+});
+
+describe('applyStyleFields — a field on no role reconnects within its kind', () => {
+  it.each([
+    ['description_style', 'paragraph1', 'descriptionStyle'],
+    ['title_style', 'heading4', 'titleStyle'],
+  ] as const)(
+    'a %s on no role at 2.25em lands on %s',
+    (aiKey, expected, modelKey) => {
+      const content = {
+        type: 'banner-section',
+        [modelKey]: {},
+      } as unknown as Content;
+
+      applyStyleFields(
+        content,
+        { [aiKey]: { fontSize: '2.25em' } },
+        'banner-section',
+        TextStyles.GetDefaultTextStyle().textStyleOptions,
+      );
+
+      const style = (content as unknown as Record<string, unknown>)[
+        modelKey
+      ] as Record<string, unknown>;
+
+      expect(style.textStyleType).toBe(expected);
+      expect(style.fontSize).toBe('2.25em');
+    },
+  );
+});
+
+/** BP-5969 (R19) — a real canonical switch is a reset, not a patch: stale typography goes. */
+describe('applyAiStyle — role switch drops overrides (R19)', () => {
+  it('role switch drops overrides: typography goes, colour/alignment/auto-scale stay', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    const out = applyAiStyle(
+      {
+        textStyleType: 'paragraph1',
+        fontSize: '1.875em',
+        fontFamily: 'Oswald',
+        color: '#ff0000',
+        textAlign: 'center',
+        applyAutoScale: true,
+      },
+      { textStyleType: 'heading2' },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(out).toEqual({
+      textStyleType: 'heading2',
+      color: '#ff0000',
+      textAlign: 'center',
+      applyAutoScale: true,
+    });
+  });
+
+  it('role switch keeps this call: the same role resent keeps its override; a genuine switch keeps only this call’s own', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    // Same role resent with a new explicit override → the existing override survives alongside it.
+    const resent = applyAiStyle(
+      { textStyleType: 'heading2', fontFamily: 'Oswald' },
+      { textStyleType: 'heading2', fontSize: '3em' },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(resent.fontFamily).toBe('Oswald');
+    expect(resent.fontSize).toBe('3em');
+
+    // A genuine switch sending its own fontFamily → that value wins; the OLD size override is gone.
+    const switched = applyAiStyle(
+      {
+        textStyleType: 'paragraph1',
+        fontFamily: 'Oswald',
+        fontSize: '1.875em',
+      },
+      { textStyleType: 'heading2', fontFamily: 'Playfair Display' },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(switched.fontFamily).toBe('Playfair Display');
+    expect(switched.fontSize).toBeUndefined();
+  });
+});
+
+/** BP-5969 (R2) — a raw value equal to its role is not stored as an override; only a true override snaps. */
+describe('applyAiStyle — role-equal line height (R2)', () => {
+  it('role-equal line height: equal to the role is omitted; a differing value snaps to the 0.1 step', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.heading3.style.lineHeight = '1.25';
+
+    const normalizedEqual = normalizeStyleValue('lineHeight', 1.25);
+    const equalOut = applyAiStyle(
+      { textStyleType: 'heading3' },
+      { textStyleType: 'heading3', lineHeight: normalizedEqual },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(equalOut.lineHeight).toBeUndefined();
+
+    const normalizedOverride = normalizeStyleValue('lineHeight', 1.33);
+    const overrideOut = applyAiStyle(
+      { textStyleType: 'heading3' },
+      { textStyleType: 'heading3', lineHeight: normalizedOverride },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(overrideOut.lineHeight).toBe('1.3');
+  });
+
+  it('a value that only matches the role AFTER snapping is still dropped, not stored as a bogus override (S2)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.heading2.style.lineHeight = '1.2';
+
+    // 1.25 differs from the role's 1.2 at full precision, so the first role-equal pass keeps it
+    // — but it snaps to exactly 1.2 (the role's own value), which must be re-recognised and
+    // dropped, not stored as an override indistinguishable from the role.
+    const out = applyAiStyle(
+      { textStyleType: 'heading2' },
+      {
+        textStyleType: 'heading2',
+        lineHeight: normalizeStyleValue('lineHeight', 1.25),
+      },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(out.lineHeight).toBeUndefined();
+  });
+
+  it('a call that never touches lineHeight does not snap the stored override (S2)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.heading4.style.lineHeight = '1.2';
+
+    // A migrated/legacy override that isn't on the UI slider's 0.1 grid — an unrelated patch
+    // (here, just a colour) must leave it exactly as stored, not silently snap it to '1.3'.
+    const out = applyAiStyle(
+      { textStyleType: 'heading4', lineHeight: '1.35' },
+      { color: '#111111' },
+      options,
+    ) as Record<string, unknown>;
+
+    expect(out.lineHeight).toBe('1.35');
+  });
+});
 
 /**
  * Regression tests for the AI QA 2026-07-05 rerun P0: a colour-only *_style
@@ -81,3 +335,292 @@ describe('applyStyleFields inline-colour propagation', () => {
     expect(style.fontSize).toBe('2.188em');
   });
 });
+
+/**
+ * BP-5969 (R18, R19) — the stored-Tiptap-doc twin of the legacy-HTML tests above: a colour-only
+ * patch recolours every run (keeping a link's own colour) and clears the now-redundant style
+ * colour, unless the doc is empty (no run to hold it); a real role switch relinks every run, but
+ * only when the call carries no new text for the field — new text is the text builder's own job.
+ */
+describe('applyStyleFields — stored Tiptap doc consequences of a style-only patch (R18, R19)', () => {
+  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 runsOf = (doc: unknown): RunNode[] =>
+    (doc as { content: { content: RunNode[] }[] }).content[0].content;
+
+  const markAttrs = (
+    run: RunNode,
+    type = 'textStyle',
+  ): Record<string, unknown> | undefined =>
+    run.marks?.find((m) => m.type === type)?.attrs;
+
+  it('colour-only patch on a doc recolours every run and clears the style colour; a link keeps its own colour', () => {
+    const content = {
+      type: 'about-section',
+      title: rteDoc([
+        {
+          text: 'Fine ',
+          marks: [{ type: 'textStyle', attrs: { color: '#111111' } }],
+        },
+        {
+          text: 'Grooming',
+          marks: [
+            { type: 'link', attrs: { href: '/x' } },
+            { type: 'textStyle', attrs: { color: DEFAULT_LINK_COLOR } },
+          ],
+        },
+      ]),
+      titleStyle: { color: '#111111' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      { title_style: { color: '#f8f2e9' } },
+      'about-section',
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+    const runs = runsOf(record.title);
+
+    expect(markAttrs(runs[0])?.color).toBe('#f8f2e9');
+    expect(markAttrs(runs[1])?.color).toBe(DEFAULT_LINK_COLOR);
+    expect(
+      (record.titleStyle as Record<string, unknown>).color,
+    ).toBeUndefined();
+  });
+
+  it('colour-only patch on an empty doc leaves the colour on the style — there is no run to carry it', () => {
+    const content = {
+      type: 'about-section',
+      title: rteDoc([]),
+      titleStyle: { color: '#111111' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      { title_style: { color: '#f8f2e9' } },
+      'about-section',
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+
+    expect((record.titleStyle as Record<string, unknown>).color).toBe(
+      '#f8f2e9',
+    );
+  });
+
+  it('colour-only patch on a whitespace-only doc leaves the colour on the style — there is no run to carry it (S7)', () => {
+    const content = {
+      type: 'about-section',
+      // The only run is unmarked whitespace: setRteTextColor deliberately skips it (no glyph to
+      // colour), so the doc comes back structurally unchanged. The style colour must not be
+      // deleted on the strength of that no-op — the colour would have nowhere left to live.
+      title: rteDoc([{ text: '  ' }]),
+      titleStyle: { color: '#111111' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      { title_style: { color: '#f8f2e9' } },
+      'about-section',
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+
+    expect((record.titleStyle as Record<string, unknown>).color).toBe(
+      '#f8f2e9',
+    );
+  });
+
+  it('role switch relinks the stored doc when the call carries no new text', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const content = {
+      type: 'about-section',
+      title: rteDoc([
+        {
+          text: 'Fine',
+          marks: [{ type: 'textStyle', attrs: { fontFamily: 'Oswald' } }],
+        },
+      ]),
+      titleStyle: { textStyleType: 'heading4', fontFamily: 'Oswald' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      { title_style: { textStyleType: 'heading2' } },
+      'about-section',
+      options,
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+    const run = runsOf(record.title)[0];
+
+    expect(
+      (record.titleStyle as Record<string, unknown>).fontFamily,
+    ).toBeUndefined();
+    expect(markAttrs(run)?.fontFamily).toBe('var(--role-font-family)');
+  });
+
+  it('role switch with new text in the same call: the stored doc is left for the text builder, not relinked here', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const original = rteDoc([
+      {
+        text: 'Fine',
+        marks: [{ type: 'textStyle', attrs: { fontFamily: 'Oswald' } }],
+      },
+    ]);
+    const content = {
+      type: 'about-section',
+      title: original,
+      titleStyle: { textStyleType: 'heading4', fontFamily: 'Oswald' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      {
+        title: { type: 'doc', content: [] },
+        title_style: { textStyleType: 'heading2' },
+      },
+      'about-section',
+      options,
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+
+    expect(record.title).toEqual(original);
+    expect(
+      (record.titleStyle as Record<string, unknown>).fontFamily,
+    ).toBeUndefined();
+  });
+
+  it('role switch and a colour in the same call both apply: the relinked doc is recoloured (B1)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const content = {
+      type: 'about-section',
+      title: rteDoc([
+        {
+          text: 'Fine',
+          marks: [{ type: 'textStyle', attrs: { fontFamily: 'Oswald' } }],
+        },
+      ]),
+      titleStyle: { textStyleType: 'heading4', fontFamily: 'Oswald' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      { title_style: { textStyleType: 'heading2', color: '#ffffff' } },
+      'about-section',
+      options,
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+    const run = runsOf(record.title)[0];
+
+    expect(markAttrs(run)?.fontFamily).toBe('var(--role-font-family)');
+    expect(markAttrs(run)?.color).toBe('#ffffff');
+    expect(
+      (record.titleStyle as Record<string, unknown>).color,
+    ).toBeUndefined();
+  });
+
+  it("role switch keeps the call's own typography override on the relinked doc (B2)", () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+    const content = {
+      type: 'about-section',
+      title: rteDoc([
+        {
+          text: 'Fine',
+          marks: [{ type: 'textStyle', attrs: { fontFamily: 'Oswald' } }],
+        },
+      ]),
+      titleStyle: { textStyleType: 'heading4', fontFamily: 'Oswald' },
+    } as unknown as Content;
+
+    applyStyleFields(
+      content,
+      {
+        title_style: {
+          textStyleType: 'heading2',
+          fontFamily: 'Playfair Display',
+        },
+      },
+      'about-section',
+      options,
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+    const run = runsOf(record.title)[0];
+    const titleStyle = record.titleStyle as Record<string, unknown>;
+
+    expect(titleStyle.fontFamily).toBe('Playfair Display');
+    // The stored mark is left null for the call's own overridden attr — NOT a baked role ref,
+    // which would shadow the style override at render (B2) — so the render fill (below) is what
+    // actually resolves it.
+    expect(markAttrs(run)?.fontFamily).toBeNull();
+    // An attr the call didn't override still relinks to the new role.
+    expect(markAttrs(run)?.fontSize).toBe('var(--role-font-size)');
+
+    const filled = fillRteRunTypography(
+      record.title as never,
+      options.heading2.style as never,
+      titleStyle as never,
+    );
+    const filledRun = runsOf(filled)[0];
+
+    expect(markAttrs(filledRun)?.fontFamily).toBe('Playfair Display');
+    expect(markAttrs(filledRun)?.fontSize).toBe('var(--role-font-size)');
+  });
+
+  it('a retired-key reconnect landing on a different canonical role is NOT a switch: the stored doc is left alone (S1)', () => {
+    const options = TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+    options.buttons.style.fontFamily = 'Oswald';
+
+    const content = {
+      type: 'about-section',
+      title: rteDoc([
+        {
+          text: 'Fine',
+          marks: [{ type: 'textStyle', attrs: { fontFamily: 'Georgia' } }],
+        },
+      ]),
+      // The stored role (heading1) and the reconnected role (button, via the retired `buttons`
+      // key) are both canonical and differ — the exact shape a naive "compare the RESULT's role
+      // to the stored one" switch check misreads as a switch (S1). It isn't one: applyAiStyle
+      // took the reconnect path (incoming.textStyleType 'buttons' isn't canonical), which keeps
+      // the look as overrides, not a reset — the stored doc must stay exactly as it was.
+      titleStyle: { textStyleType: 'heading1' },
+    } as unknown as Content;
+    const originalDoc = JSON.parse(
+      JSON.stringify((content as unknown as Record<string, unknown>).title),
+    );
+
+    applyStyleFields(
+      content,
+      {
+        title_style: { textStyleType: 'buttons', fontSize: '1.25em' },
+      } as unknown as Parameters<typeof applyStyleFields>[1],
+      'about-section',
+      options,
+    );
+
+    const record = content as unknown as Record<string, unknown>;
+
+    expect((record.titleStyle as Record<string, unknown>).textStyleType).toBe(
+      'button',
+    );
+    expect(record.title).toEqual(originalDoc);
+  });
+});