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

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

@@ -0,0 +1,604 @@
+import { describe, it, expect } from 'vitest';
+import {
+  computeLegacyTargets,
+  reconnectTextStyle,
+  reconnectTextStyleRoles,
+  drawnFontFamily,
+  contentFieldReconnectSpec,
+  BUTTON_ELEMENT_RECONNECT,
+  DETACHED_UNSET_EFFECTIVE,
+} from './text-role-reconnect.util';
+import { resolveTextStyle, TEXT_STYLE_CASCADE_PROPS } from './text-style.util';
+import { TextStyles } from '../models';
+import type { BrandPageModel, TextStyleDeclaration } from '../models';
+import type {
+  CanonicalTextStyleType,
+  TextStyleOptions,
+  TextStyleType,
+} from '../models/styles.model';
+
+const withRoles = (): TextStyleOptions =>
+  TextStyles.GetDefaultTextStyle().textStyleOptions;
+
+const roleStyle = (options: TextStyleOptions, type: string) =>
+  options[type as TextStyleType]?.style;
+
+// 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],
+    ]),
+  );
+};
+
+const expectNoRoleEqualValues = (
+  style: TextStyleDeclaration,
+  options: TextStyleOptions,
+): void => {
+  const role = roleStyle(options, style.textStyleType as string) as unknown as
+    | Record<string, unknown>
+    | undefined;
+
+  for (const prop of TEXT_STYLE_CASCADE_PROPS) {
+    const value = (style as Record<string, unknown>)[prop];
+
+    if (value !== undefined) expect(value).not.toBe(role?.[prop]);
+  }
+};
+
+describe('text-role-reconnect.util · reconnectTextStyle (R14 precedence)', () => {
+  it('leaves a canonical role untouched', () => {
+    const options = withRoles();
+    const style = { textStyleType: 'heading2', fontSize: '5.25em' };
+
+    const result = reconnectTextStyle(
+      style,
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(result).toBe(style);
+    expect(result.fontSize).toBe('5.25em');
+  });
+
+  it('reconnects a starting role first: tab nav on buttons → paragraph1, look kept', () => {
+    const options = withRoles();
+
+    options.buttons.style.fontFamily = 'Oswald';
+    const before = {
+      textStyleType: 'buttons',
+      fontSize: '1em',
+      color: '#123456',
+    } as TextStyleDeclaration;
+
+    const after = reconnectTextStyle(
+      { ...before },
+      computeLegacyTargets(options),
+      options,
+      { startingRole: 'paragraph1' },
+    );
+
+    expect(after.textStyleType).toBe('paragraph1');
+    expect(lookOf(after, roleStyle(options, 'paragraph1'))).toEqual(
+      lookOf(before, roleStyle(options, 'buttons')),
+    );
+    expect(after.color).toBe('#123456');
+    expectNoRoleEqualValues(after, options);
+  });
+
+  it.each([
+    ['paragraphs', 'paragraph1'],
+    ['buttons', 'button'],
+  ] as const)(
+    'reconnects retired %s to its successor %s, look kept',
+    (retired, successor) => {
+      const options = withRoles();
+      const before = { textStyleType: retired } as TextStyleDeclaration;
+
+      const after = reconnectTextStyle(
+        { ...before },
+        computeLegacyTargets(options),
+        options,
+      );
+
+      expect(after.textStyleType).toBe(successor);
+      expect(lookOf(after, roleStyle(options, successor))).toEqual(
+        lookOf(before, roleStyle(options, retired)),
+      );
+      expectNoRoleEqualValues(after, options);
+    },
+  );
+
+  it('reconnects retired titles/headings to distinct heading tiers by the site sizes, look kept', () => {
+    const options = withRoles();
+    const targets = computeLegacyTargets(options);
+
+    const title = { textStyleType: 'titles' } as TextStyleDeclaration;
+    const heading = { textStyleType: 'headings' } as TextStyleDeclaration;
+    const titleAfter = reconnectTextStyle({ ...title }, targets, options);
+    const headingAfter = reconnectTextStyle({ ...heading }, targets, options);
+
+    // titles 2.25em → H4 (2.1875em); headings 1.5em → H5 (1.4375em)
+    expect(titleAfter.textStyleType).toBe('heading4');
+    expect(headingAfter.textStyleType).toBe('heading5');
+    expect(lookOf(titleAfter, roleStyle(options, 'heading4'))).toEqual(
+      lookOf(title, roleStyle(options, 'titles')),
+    );
+    expect(lookOf(headingAfter, roleStyle(options, 'heading5'))).toEqual(
+      lookOf(heading, roleStyle(options, 'headings')),
+    );
+    expectNoRoleEqualValues(titleAfter, options);
+    expectNoRoleEqualValues(headingAfter, options);
+  });
+
+  it.each([
+    ['no role', undefined, '2.5em', 'heading4'],
+    ['none', 'none', '2.5em', 'heading4'],
+    ['an unknown value', 'garbage', '2.5em', 'heading4'],
+    ['no role', undefined, '0.875em', 'paragraph3'],
+    ['none', 'none', '0.875em', 'paragraph3'],
+    ['an unknown value', 'garbage', '0.875em', 'paragraph3'],
+    ['no role', undefined, undefined, 'paragraph1'],
+    ['none', 'none', undefined, 'paragraph1'],
+    ['an unknown value', 'garbage', undefined, 'paragraph1'],
+  ] as const)(
+    'reconnects %s at %s to the nearest role %s, look kept',
+    (_label, type, fontSize, expected) => {
+      const options = withRoles();
+      const before = {
+        textStyleType: type,
+        ...(fontSize ? { fontSize } : {}),
+      } as unknown as TextStyleDeclaration;
+
+      const after = reconnectTextStyle(
+        { ...before },
+        computeLegacyTargets(options),
+        options,
+      );
+      const kept = lookOf(before, undefined);
+      const look = lookOf(after, roleStyle(options, expected));
+
+      expect(after.textStyleType).toBe(expected);
+
+      for (const [prop, value] of Object.entries(kept)) {
+        if (value !== undefined) expect(look[prop]).toBe(value);
+      }
+
+      expectNoRoleEqualValues(after, options);
+    },
+  );
+
+  // A body-text field stays on a paragraph tier however big it is, so a site-wide heading edit
+  // never repaints it; a title still reaches a heading tier. Either way the size stays as an override.
+  it.each([
+    ['banner-section', 'descriptionStyle', '2.25em', 'paragraph1'],
+    ['about-section', 'paragraphStyle', '3em', 'paragraph1'],
+    ['testimonial-section', 'testimonialStyle', '2em', 'paragraph1'],
+    ['banner-section', 'descriptionStyle', '0.8em', 'paragraph3'],
+    ['banner-section', 'titleStyle', '2.25em', 'heading4'],
+    ['images-section', 'headingStyle', '1.5em', 'heading5'],
+  ] as const)(
+    'reconnects a %s %s on no role at %s to %s, keeping its size',
+    (contentType, key, fontSize, expected) => {
+      const options = withRoles();
+
+      const after = reconnectTextStyle(
+        { fontSize } as TextStyleDeclaration,
+        computeLegacyTargets(options),
+        options,
+        contentFieldReconnectSpec(contentType, key),
+      );
+
+      expect(after.textStyleType).toBe(expected);
+      expect(after.fontSize).toBe(fontSize);
+    },
+  );
+
+  it('lets a starting role win over nearest-by-size for a field on no role', () => {
+    const options = withRoles();
+
+    const after = reconnectTextStyle(
+      { fontSize: '2.5em' } as TextStyleDeclaration,
+      computeLegacyTargets(options),
+      options,
+      { startingRole: 'button' as CanonicalTextStyleType },
+    );
+
+    expect(after.textStyleType).toBe('button');
+    expect(after.fontSize).toBe('2.5em');
+  });
+
+  it('keeps colour, alignment and auto-scale through a reconnect', () => {
+    const options = withRoles();
+
+    const after = reconnectTextStyle(
+      {
+        textStyleType: 'paragraphs',
+        color: 'var(--palette-1)',
+        textAlign: 'center',
+        applyAutoScale: true,
+      } as TextStyleDeclaration,
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(after).toMatchObject({
+      textStyleType: 'paragraph1',
+      color: 'var(--palette-1)',
+      textAlign: 'center',
+      applyAutoScale: true,
+    });
+  });
+});
+
+describe('text-role-reconnect.util · reconnectTextStyleRoles (the field walk)', () => {
+  it('reconnects every field outside the ten, each nav and button field on its starting role', () => {
+    const options = withRoles();
+    const header = () => ({
+      navigation: {
+        defaultButtonStyle: { textStyleType: 'buttons', fontSize: '1em' },
+        hamburgerMenuStyle: { defaultButtonStyle: { fontSize: '1em' } },
+      },
+      headerButton: { buttonTextStyle: { textStyleType: 'buttons' } },
+    });
+    const model = {
+      pages: [
+        {
+          contents: [
+            {
+              titleStyle: { textStyleType: 'none', fontSize: '2.5em' },
+              descriptionStyle: { textStyleType: 'heading3' },
+              textItems: [{ textStyle: { textStyleType: 'garbage' } }],
+            },
+          ],
+        },
+      ],
+      pageFooterDesktop: { copyrightStyle: { textStyleType: 'paragraphs' } },
+      pageFooterMobile: { copyrightStyle: { textStyleType: 'paragraphs' } },
+      pageHeaderDesktop: header(),
+      pageHeaderMobile: header(),
+      saveContactSettings: {
+        isSavingEnabled: true,
+        hideBranding: false,
+        buttonTextStyle: { textStyleType: 'buttons' },
+      },
+    } as unknown as BrandPageModel;
+
+    reconnectTextStyleRoles(model, computeLegacyTargets(options), options);
+
+    const content = model.pages[0].contents[0] as unknown as Record<
+      string,
+      { textStyleType?: string }
+    > & { textItems: { textStyle: { textStyleType?: string } }[] };
+
+    expect(content.titleStyle.textStyleType).toBe('heading4');
+    expect(content.descriptionStyle.textStyleType).toBe('heading3');
+    expect(content.textItems[0].textStyle.textStyleType).toBe('paragraph1');
+
+    for (const footer of [model.pageFooterDesktop, model.pageFooterMobile]) {
+      expect(footer.copyrightStyle.textStyleType).toBe('paragraph1');
+    }
+
+    for (const viewport of [model.pageHeaderDesktop, model.pageHeaderMobile]) {
+      expect(viewport.navigation.defaultButtonStyle.textStyleType).toBe(
+        'paragraph1',
+      );
+      expect(
+        viewport.navigation.hamburgerMenuStyle.defaultButtonStyle.textStyleType,
+      ).toBe('button');
+      expect(viewport.headerButton?.buttonTextStyle?.textStyleType).toBe(
+        'button',
+      );
+    }
+
+    expect(model.saveContactSettings?.buttonTextStyle?.textStyleType).toBe(
+      'button',
+    );
+  });
+
+  it('is a no-op on canonical data', () => {
+    const options = withRoles();
+    const model = {
+      pages: [{ contents: [{ titleStyle: { textStyleType: 'heading1' } }] }],
+    } as unknown as BrandPageModel;
+    const snapshot = JSON.parse(JSON.stringify(model));
+
+    reconnectTextStyleRoles(model, computeLegacyTargets(options), options);
+
+    expect(model).toEqual(snapshot);
+  });
+});
+
+// A field on no role with no size or font of its own rendered the page's: the size it inherited
+// (the page root sets none, so `1em` of its parent) and the site's text font. When those differ
+// from the role it reconnects to, they're kept as overrides (James Joung, 2026-09-28).
+describe('text-role-reconnect.util · keeps an inherited size and font', () => {
+  it('pins the inherited 1em size on a field with no size, which Paragraph 1 would otherwise enlarge', () => {
+    const options = withRoles();
+
+    const after = reconnectTextStyle(
+      { textAlign: 'left' } as TextStyleDeclaration,
+      computeLegacyTargets(options),
+      options,
+    );
+
+    expect(after.textStyleType).toBe('paragraph1');
+    expect(after.fontSize).toBe('1em'); // Paragraph 1 is 1.375em
+  });
+
+  it('pins the inherited site font through the field walk when it differs from the new role, and not when equal', () => {
+    const options = withRoles();
+    const modelWithFont = (textFontFamily: string) =>
+      ({
+        pages: [{ contents: [{ textStyle: { textAlign: 'left' } }] }],
+        styles: { textStyles: { textFontFamily, textStyleOptions: options } },
+      }) as unknown as BrandPageModel;
+    const textStyleOf = (model: BrandPageModel) =>
+      (
+        model.pages[0].contents[0] as unknown as {
+          textStyle: TextStyleDeclaration;
+        }
+      ).textStyle;
+
+    const oswaldSite = modelWithFont('oswald');
+    const latoSite = modelWithFont('lato');
+
+    reconnectTextStyleRoles(oswaldSite, computeLegacyTargets(options), options);
+    reconnectTextStyleRoles(latoSite, computeLegacyTargets(options), options);
+
+    expect(textStyleOf(oswaldSite).fontFamily).toBe('Oswald');
+    expect(textStyleOf(latoSite).fontFamily).toBeUndefined(); // equals Paragraph 1's Lato
+    expect(textStyleOf(latoSite).fontSize).toBe('1em');
+  });
+
+  // Production's resolver drew a field whose role the site doesn't hold from the field alone.
+  it.each([
+    ['drawn before the cascade', true],
+    ['drawn by the cascade', false],
+  ] as const)(
+    'pins the inherited 1em and site font on a retired role missing from the site, %s',
+    (_label, drawnBeforeCascade) => {
+      const options = withRoles();
+
+      delete (options as Partial<TextStyleOptions>).titles;
+
+      const after = reconnectTextStyle(
+        { textStyleType: 'titles', textAlign: 'left' } as TextStyleDeclaration,
+        computeLegacyTargets(options),
+        options,
+        { inheritedFontFamily: 'Oswald', drawnBeforeCascade },
+      );
+
+      expect(after.textStyleType).toBe('heading1');
+      expect(after.fontSize).toBe('1em'); // Heading 1 is 6.875em
+      expect(after.fontFamily).toBe('Oswald');
+      expect(after.fontWeight).toBe('normal'); // Heading 1 is bold
+    },
+  );
+});
+
+// A pinned neutral (normal / none) is kept only where the new role defines that prop: where the
+// role leaves it unset, unset draws the same, and a later role edit can still reach the field.
+describe('text-role-reconnect.util · reconnect pins a neutral only where it draws differently', () => {
+  it('keeps normal weight under a bold heading, and pins no style, decoration or spacing the role leaves unset', () => {
+    const options = withRoles();
+
+    const after = reconnectTextStyle(
+      { fontSize: '2.5em' } as TextStyleDeclaration,
+      computeLegacyTargets(options),
+      options,
+    ) as Record<string, unknown>;
+
+    expect(after.textStyleType).toBe('heading4');
+    expect(after.fontWeight).toBe('normal');
+    expect(after.lineHeight).toBe('normal');
+    expect(after.fontStyle).toBeUndefined();
+    expect(after.textDecoration).toBeUndefined();
+    expect(after.letterSpacing).toBeUndefined();
+  });
+
+  it('pins a neutral the role does define differently, for a retired role too', () => {
+    const options = withRoles();
+
+    options.button.style.fontStyle = 'italic';
+
+    const after = reconnectTextStyle(
+      { textStyleType: 'buttons' } as TextStyleDeclaration,
+      computeLegacyTargets(options),
+      options,
+    ) as Record<string, unknown>;
+
+    expect(after.textStyleType).toBe('button');
+    expect(after.fontStyle).toBe('normal'); // the old buttons label wasn't italic
+    expect(after.textDecoration).toBeUndefined();
+  });
+});
+
+describe('text-role-reconnect.util · inherited font falls back to the default site font', () => {
+  it('pins the default site font when the model names none and the role differs', () => {
+    const options = withRoles();
+
+    options.paragraph1.style.fontFamily = 'Oswald';
+
+    const model = {
+      pages: [{ contents: [{ textStyle: { textAlign: 'left' } }] }],
+      styles: { textStyles: { textStyleOptions: options } },
+    } as unknown as BrandPageModel;
+
+    reconnectTextStyleRoles(model, computeLegacyTargets(options), options);
+
+    expect(
+      (
+        model.pages[0].contents[0] as unknown as {
+          textStyle: TextStyleDeclaration;
+        }
+      ).textStyle.fontFamily,
+    ).toBe('Lato'); // the page root falls back to the default font (`Page.mixin`)
+  });
+});
+
+// Before the per-property cascade (migration-22's input) a field on a role drew only the role; the
+// AI boundary now draws its own values over the role.
+describe('text-role-reconnect.util · a retired role keeps the look its resolver drew', () => {
+  const buttonOnButtons = (): TextStyleDeclaration =>
+    ({
+      textStyleType: 'buttons',
+      fontSize: '2em',
+      fontWeight: '300',
+      lineHeight: '1.1',
+    }) as TextStyleDeclaration;
+
+  it('takes the old role’s typography over the field’s own when it was drawn before the cascade', () => {
+    const options = withRoles();
+    const before = lookOf(
+      {} as TextStyleDeclaration,
+      roleStyle(options, 'buttons'),
+    );
+    const after = reconnectTextStyle(
+      buttonOnButtons(),
+      computeLegacyTargets(options),
+      options,
+      { ...BUTTON_ELEMENT_RECONNECT, drawnBeforeCascade: true },
+    );
+    const look = lookOf(after, roleStyle(options, 'button'));
+
+    expect(after.textStyleType).toBe('button');
+
+    for (const [prop, value] of Object.entries(before)) {
+      if (value !== undefined) expect(look[prop], prop).toBe(value);
+    }
+  });
+
+  it('keeps the field’s own typography when it was drawn by the cascade', () => {
+    const options = withRoles();
+    const after = reconnectTextStyle(
+      buttonOnButtons(),
+      computeLegacyTargets(options),
+      options,
+      BUTTON_ELEMENT_RECONNECT,
+    );
+
+    expect(after).toMatchObject({
+      textStyleType: 'button',
+      fontSize: '2em',
+      fontWeight: '300',
+      lineHeight: '1.1',
+    });
+  });
+});
+
+// R16 (T16.14, migration-22 job A2): the font a field's own value shows, read the same way as the
+// look pin above, before its role's cascade would replace it.
+describe('text-role-reconnect.util · drawnFontFamily (R16)', () => {
+  it("an old role with a font draws the role's, over the field's own", () => {
+    const options = withRoles();
+
+    options.buttons.style.fontFamily = 'Oswald';
+
+    expect(
+      drawnFontFamily(
+        {
+          textStyleType: 'buttons',
+          fontFamily: 'Nunito',
+        } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Oswald');
+  });
+
+  it("an old role missing from the site's options draws the field's own font, else the site's", () => {
+    const options = withRoles();
+
+    delete (options as Record<string, unknown>).buttons;
+
+    expect(
+      drawnFontFamily(
+        {
+          textStyleType: 'buttons',
+          fontFamily: 'Nunito',
+        } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Nunito');
+    expect(
+      drawnFontFamily(
+        { textStyleType: 'buttons' } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Lato');
+  });
+
+  it("no role (undefined, `none`, an unknown string) draws its own font, else the site's", () => {
+    const options = withRoles();
+
+    for (const type of [undefined, 'none', 'garbage']) {
+      expect(
+        drawnFontFamily(
+          { textStyleType: type, fontFamily: 'Nunito' } as TextStyleDeclaration,
+          options,
+          'Lato',
+        ),
+        String(type),
+      ).toBe('Nunito');
+      expect(
+        drawnFontFamily(
+          { textStyleType: type } as TextStyleDeclaration,
+          options,
+          'Lato',
+        ),
+        String(type),
+      ).toBe('Lato');
+    }
+  });
+
+  it("a canonical role draws its own font, else the role's, else the site's", () => {
+    const options = withRoles();
+
+    options.heading1.style.fontFamily = 'Anton';
+
+    expect(
+      drawnFontFamily(
+        {
+          textStyleType: 'heading1',
+          fontFamily: 'Nunito',
+        } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Nunito');
+    expect(
+      drawnFontFamily(
+        { textStyleType: 'heading1' } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Anton');
+    delete (options.heading1.style as unknown as Record<string, unknown>)
+      .fontFamily;
+    expect(
+      drawnFontFamily(
+        { textStyleType: 'heading1' } as TextStyleDeclaration,
+        options,
+        'Lato',
+      ),
+    ).toBe('Lato');
+  });
+
+  it('an absent style draws the site font', () => {
+    expect(drawnFontFamily(undefined, withRoles(), 'Lato')).toBe('Lato');
+  });
+});