@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -0,0 +1,727 @@
+import type { BrandPageModel, Content, TextStyleDeclaration } from '../models';
+import {
+  isLegacyTextStyleType,
+  isCanonicalTextStyleType,
+  CANONICAL_TEXT_STYLE_TYPES,
+  type TextStyleOptions,
+  type LegacyTextStyleType,
+  type CanonicalTextStyleType,
+} from '../models/styles.model';
+import {
+  CONTENT_TEXT_STYLE_PROPERTY_KEYS,
+  DEFAULT_FONT_FAMILY_KEY,
+  FONT_FAMILY_CONFIGS,
+  FONT_SIZE_BODY,
+  FONT_SIZE_HEADINGS,
+  LINE_HEIGHT_BODY,
+  LINE_HEIGHT_HEADINGS,
+  TEXT_ROLE_STYLE_DEFAULTS,
+  type FontFamilyKey,
+} from '../constants';
+import { normalizeTextStyleAgainstRole } from './text-style.util';
+import { isButtonContent } from './model.util';
+import { isBlankColorValue } from './color-palette.util';
+import { liftRteFieldOntoRole } from './rte-role-lift.util';
+
+// Re-exported for migrations that already import the guard from here (a released migration's
+// imports must not move) — render components import it from `styles.model.ts` directly.
+export { isCanonicalTextStyleType };
+
+/**
+ * The one definition of "a text field whose role isn't one of the ten reconnects to its nearest
+ * role and keeps its look" (ADR 0021), shared by migration-22 (upgrade) and the AI write
+ * boundary (`applyAiStyle`).
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: this is shared with maker and AI writes, but migration-22 reads
+ * it as part of its v21 -> v22 output. Before changing reconnect behaviour after that migration
+ * releases, copy the v22 semantics into the migration (or add a later migration).
+ */
+
+/**
+ * The per-site legacy → canonical target map. `paragraphs` and `buttons` are fixed; `titles`/
+ * `headings` snap to the heading tier whose default size is nearest the OLD role's size, kept on
+ * DISTINCT tiers so migration-22's colour seed is unambiguous.
+ */
+export type LegacyTargetMap = Record<
+  LegacyTextStyleType,
+  CanonicalTextStyleType
+>;
+
+const parseEm = (value: string | undefined): number | undefined => {
+  if (!value) return undefined;
+
+  const match = /([\d.]+)\s*em/.exec(value);
+
+  return match ? parseFloat(match[1]) : undefined;
+};
+
+// Exported so migration-22 job A2 votes onto the same tiers, rather than a second list of them.
+export const HEADING_TIERS = CANONICAL_TEXT_STYLE_TYPES.filter((t) =>
+  t.startsWith('heading'),
+);
+export const PARAGRAPH_TIERS = CANONICAL_TEXT_STYLE_TYPES.filter((t) =>
+  t.startsWith('paragraph'),
+);
+
+/** The kind of text a field holds — the tiers a site-wide edit of that kind reaches. */
+export type TextRoleFamily = 'headings' | 'paragraphs' | 'button';
+
+export const FAMILY_TIERS: Record<
+  TextRoleFamily,
+  readonly CanonicalTextStyleType[]
+> = {
+  headings: HEADING_TIERS,
+  paragraphs: PARAGRAPH_TIERS,
+  button: ['button'],
+};
+
+// Above this em size a detached block reads as a heading, below it as body text.
+const HEADING_SIZE_THRESHOLD_EM = 1.125;
+
+export const nearestBySize = (
+  size: number,
+  tiers: readonly CanonicalTextStyleType[],
+): CanonicalTextStyleType =>
+  tiers.reduce((best, tier) => {
+    const diff = Math.abs(
+      (parseEm(TEXT_ROLE_STYLE_DEFAULTS[tier].fontSize) ?? 1) - size,
+    );
+    const bestDiff = Math.abs(
+      (parseEm(TEXT_ROLE_STYLE_DEFAULTS[best].fontSize) ?? 1) - size,
+    );
+
+    return diff < bestDiff ? tier : best;
+  }, tiers[0]);
+
+export const computeLegacyTargets = (
+  options: Partial<TextStyleOptions> | undefined,
+): LegacyTargetMap => {
+  const nearestHeading = (
+    role: LegacyTextStyleType,
+    exclude?: CanonicalTextStyleType,
+  ): CanonicalTextStyleType | undefined => {
+    const size = parseEm(options?.[role]?.style.fontSize);
+
+    if (size === undefined) return undefined;
+
+    const tiers = exclude
+      ? HEADING_TIERS.filter((t) => t !== exclude)
+      : HEADING_TIERS;
+
+    return nearestBySize(size, tiers);
+  };
+
+  const titles = nearestHeading('titles') ?? 'heading1';
+  // Fallback must still respect the exclusion — a bare `?? 'heading4'` could collide with `titles`
+  // (its default mapping), and the colour seed relies on the two tiers being distinct.
+  const headings =
+    nearestHeading('headings', titles) ??
+    HEADING_TIERS.find((t) => t !== titles) ??
+    'heading4';
+
+  return { titles, headings, paragraphs: 'paragraph1', buttons: 'button' };
+};
+
+/**
+ * The role nearest a field's own font size: heading tiers for display-sized text, paragraph tiers
+ * for body, `paragraph1` when there is no size. A `paragraphs`-family field stays on a paragraph
+ * tier however big it is, so a site-wide heading edit never repaints it. `button` is never a best
+ * fit — a button field reaches it through its starting role or the retired `buttons` successor.
+ */
+export const bestFitRole = (
+  style: TextStyleDeclaration,
+  family?: TextRoleFamily,
+): CanonicalTextStyleType => {
+  const size = parseEm(style.fontSize);
+
+  if (size === undefined) return 'paragraph1';
+
+  // Not bounded the other way: a small `headings`-family title still takes a paragraph tier, as
+  // migration-22's frozen output expects.
+  return size >= HEADING_SIZE_THRESHOLD_EM && family !== 'paragraphs'
+    ? nearestBySize(size, HEADING_TIERS)
+    : nearestBySize(size, PARAGRAPH_TIERS);
+};
+
+// A field on no role rendered its UNSET typography from inheritance — normal weight and style, no
+// decoration, browser-default line-height/spacing — never from a role. The role class paints all
+// of these, so each unset one is pinned to its effective value; the new role gives identity, not
+// appearance. Family/size are left alone: they inherit from the page as before.
+export const DETACHED_UNSET_EFFECTIVE: Record<string, string> = {
+  fontWeight: 'normal',
+  fontStyle: 'normal',
+  textDecoration: 'none',
+  lineHeight: 'normal',
+  letterSpacing: 'normal',
+};
+
+const LEGACY_TYPOGRAPHY_PROPS = [
+  'fontFamily',
+  'fontSize',
+  'fontWeight',
+  'fontStyle',
+  'textDecoration',
+  'lineHeight',
+  'letterSpacing',
+] as const;
+
+const isUnset = (value: unknown): boolean =>
+  value === undefined || value === null || value === '';
+
+// The page root sets no font size, so an unsized field drew `1em` of its parent — which is what
+// `1em` still means once the role class is in play.
+const INHERITED_FONT_SIZE = '1em';
+
+// Before the per-property cascade, a field on a role drew that role's typography and none of its
+// own (`getTextStyleByContentTextStyleProperty` on origin/develop): each prop is replaced with the
+// old role's value, else what the page gave it. Pure — returns a new object, the seven typography
+// props only — so `drawnFontFamily` (R16) can read just the font this way, without mutating a
+// field that migration-22 job A2 only counts, never rewrites.
+const pinDrawnLook = (
+  style: TextStyleDeclaration,
+  oldRoleStyle: object,
+  inheritedFontFamily?: string,
+): TextStyleDeclaration => {
+  const pinned = { ...style } as unknown as Record<string, unknown>;
+  const old = oldRoleStyle as Record<string, unknown>;
+  const inherited: Record<string, string | undefined> = {
+    ...DETACHED_UNSET_EFFECTIVE,
+    fontSize: INHERITED_FONT_SIZE,
+    fontFamily: inheritedFontFamily,
+  };
+
+  for (const prop of LEGACY_TYPOGRAPHY_PROPS) {
+    const value = isUnset(old[prop]) ? inherited[prop] : old[prop];
+
+    if (value === undefined) delete pinned[prop];
+    else pinned[prop] = value;
+  }
+
+  return pinned as unknown as TextStyleDeclaration;
+};
+
+// Applied to RTE style objects too: migration-22 job C reads them as the block override it bakes
+// onto bare runs (the renderer ignores RTE style-object typography — no double-em).
+export const materialiseLegacyTypography = (
+  style: TextStyleDeclaration,
+  oldRoleStyle: object,
+  inheritedFontFamily?: string,
+): void => {
+  const pinned = pinDrawnLook(
+    style,
+    oldRoleStyle,
+    inheritedFontFamily,
+  ) as unknown as Record<string, unknown>;
+  const props = style as unknown as Record<string, unknown>;
+
+  for (const prop of LEGACY_TYPOGRAPHY_PROPS) {
+    if (prop in pinned) props[prop] = pinned[prop];
+    else delete props[prop];
+  }
+};
+
+const typographyOf = (
+  style: object | undefined,
+): Record<string, string | undefined> => {
+  const props = (style ?? {}) as Record<string, string | undefined>;
+
+  return Object.fromEntries(
+    LEGACY_TYPOGRAPHY_PROPS.map((prop) => [prop, props[prop]]),
+  );
+};
+
+const pinUnset = (
+  style: TextStyleDeclaration,
+  values: Partial<Record<string, string | undefined>> | undefined,
+): void => {
+  const props = style as unknown as Record<string, unknown>;
+
+  for (const [prop, value] of Object.entries(values ?? {})) {
+    if (isUnset(props[prop]) && value !== undefined) props[prop] = value;
+  }
+};
+
+/**
+ * What a reconnect needs beyond the role table, all optional:
+ * - `startingRole` — the field's own role, which wins over successor and nearest-by-size;
+ * - `family` — the kind of text the field holds (`bestFitRole` keeps a paragraph on a paragraph
+ *   tier; migration-22 job A2 votes its font into that family);
+ * - `renderedDefaults` — values a renderer draws for an unset prop, which beat the role, so they
+ *   are the look to keep (the button view model's line height, the profile's sizes);
+ * - `inheritedFontFamily` — the site text font an unset family drew from the page root;
+ * - `drawnBeforeCascade` — the field was last drawn by the resolver before BP-5969's per-property
+ *   cascade (migration-22's input), where a role replaced its typography and those defaults.
+ */
+export interface ReconnectSpec {
+  startingRole?: CanonicalTextStyleType;
+  family?: TextRoleFamily;
+  renderedDefaults?: Partial<Record<string, string>>;
+  inheritedFontFamily?: string;
+  drawnBeforeCascade?: boolean;
+}
+
+export type RenderedDefaultsForContent = (
+  content: Record<string, unknown>,
+  key: string,
+) => Partial<Record<string, string>> | undefined;
+
+// Production's renderer drew an unset label line height as `LINE_HEIGHT_HEADINGS`, over the role
+// (Brief 3 R3 deletes that default outright; this is the look to keep on upgrade).
+const BUTTON_VIEW_MODEL_DEFAULTS = { lineHeight: LINE_HEIGHT_HEADINGS };
+const BUTTON_VIEW_MODEL_SECTIONS = new Set([
+  'banner-section',
+  'booking-section',
+  'images-section',
+]);
+// Production's renderer drew these defaults for an unset profile size and line height (R3
+// deletes them outright; this is the look to keep on upgrade).
+const PROFILE_VIEW_MODEL_DEFAULTS: Record<string, Record<string, string>> = {
+  titleStyle: { fontSize: FONT_SIZE_BODY, lineHeight: LINE_HEIGHT_BODY },
+  descriptionStyle: { fontSize: FONT_SIZE_BODY, lineHeight: LINE_HEIGHT_BODY },
+  nameStyle: { fontSize: FONT_SIZE_HEADINGS, lineHeight: LINE_HEIGHT_HEADINGS },
+};
+
+export const BUTTON_ELEMENT_RECONNECT: ReconnectSpec = {
+  startingRole: 'button',
+  family: 'button',
+  renderedDefaults: BUTTON_VIEW_MODEL_DEFAULTS,
+};
+
+// The kind of text each field holds, mirroring the pipeline's field → font slot map
+// (font_generation.py `_DEFAULT_FIELD_TO_SLOT`: h1–h4 are headings, body and caption paragraphs).
+// A field outside the map has no family, so only its size picks its tier. That includes a text
+// section's `textStyle` and `textItems`: real sites set heading-sized text blocks, and moving them
+// off heading tiers would change migration-22's frozen output.
+const KEY_FAMILIES: Partial<Record<string, TextRoleFamily>> = {
+  titleStyle: 'headings',
+  headingStyle: 'headings',
+  nameStyle: 'headings',
+  descriptionStyle: 'paragraphs',
+  paragraphStyle: 'paragraphs',
+  successMessageStyle: 'paragraphs',
+  testimonialStyle: 'paragraphs',
+  positionStyle: 'paragraphs',
+};
+
+/**
+ * The reconnect spec for one content style field. Every button element starts on Button text and
+ * keeps what makes it different as overrides (James Joung, 2026-09-28): a section's
+ * `buttonTextStyle` and a link button's `titleStyle`.
+ */
+export const contentFieldReconnectSpec = (
+  contentType: string | undefined,
+  key: string,
+): ReconnectSpec => {
+  if (key === 'buttonTextStyle') {
+    return {
+      startingRole: 'button',
+      family: 'button',
+      renderedDefaults: BUTTON_VIEW_MODEL_SECTIONS.has(contentType ?? '')
+        ? BUTTON_VIEW_MODEL_DEFAULTS
+        : undefined,
+    };
+  }
+
+  if (key === 'titleStyle' && isButtonContent({ type: contentType } as Content))
+    return BUTTON_ELEMENT_RECONNECT;
+
+  const family = KEY_FAMILIES[key];
+
+  if (contentType === 'profile')
+    return { family, renderedDefaults: PROFILE_VIEW_MODEL_DEFAULTS[key] };
+
+  return { family };
+};
+
+/**
+ * The font a field's own value shows, read the same way as the reconnect's look pin
+ * (`pinDrawnLook`), before its role's cascade would replace it (R16, migration-22 job A2, which
+ * only counts this — never mutates the field). A legacy role's font wins over the field's own, as
+ * production drew it; with no old role (undefined, `'none'`, an unknown string, or a retired role
+ * missing from the site's options) the field's own font wins, else the site's. A canonical role —
+ * which A2's input never holds — draws its own font, else the role's, else the site's.
+ */
+export const drawnFontFamily = (
+  style: Partial<TextStyleDeclaration> | undefined,
+  options: TextStyleOptions | undefined,
+  siteFont: string,
+): string => {
+  const props = (style ?? {}) as unknown as Record<string, unknown>;
+  const type = props.textStyleType;
+  const ownFont = props.fontFamily as string | undefined;
+
+  if (isCanonicalTextStyleType(type)) {
+    const roleFont = (
+      options?.[type]?.style as unknown as Record<string, unknown> | undefined
+    )?.fontFamily as string | undefined;
+
+    return ownFont || roleFont || siteFont;
+  }
+
+  const retired = isLegacyTextStyleType(type as string | undefined)
+    ? (type as LegacyTextStyleType)
+    : undefined;
+  const oldRoleStyle = retired ? options?.[retired]?.style : undefined;
+
+  if (!oldRoleStyle) return ownFont || siteFont;
+
+  const pinned = pinDrawnLook(
+    props as unknown as TextStyleDeclaration,
+    oldRoleStyle,
+    siteFont,
+  ) as unknown as Record<string, unknown>;
+
+  return (pinned.fontFamily as string | undefined) ?? siteFont;
+};
+
+/**
+ * Reconnect one style to a canonical role, keeping its look. A canonical role is returned as is.
+ * Otherwise the role is `startingRole ?? (retired ? its successor : nearest by size)`, the look is
+ * pinned, and values equal to the new role are dropped, so only a real difference remains as an
+ * override. The look is the retired role's typography where that role replaced the field's own
+ * (`drawnBeforeCascade`); else the field's own values, then a renderer's defaults, then the old
+ * role's or the inherited values.
+ */
+export const reconnectTextStyle = <T extends object>(
+  style: T,
+  targets: LegacyTargetMap,
+  options: TextStyleOptions | undefined,
+  spec: ReconnectSpec = {},
+): T => {
+  const type = (style as Record<string, unknown>).textStyleType;
+
+  if (isCanonicalTextStyleType(type)) return style;
+
+  const reconnected = { ...style } as TextStyleDeclaration;
+  const retired = isLegacyTextStyleType(type as string | undefined)
+    ? (type as LegacyTextStyleType)
+    : undefined;
+  // From the stored size, before any pin: a field with no size of its own goes to Paragraph 1.
+  const role =
+    spec.startingRole ??
+    (retired ? targets[retired] : bestFitRole(reconnected, spec.family));
+
+  const oldRoleStyle = retired ? options?.[retired]?.style : undefined;
+
+  if (oldRoleStyle && spec.drawnBeforeCascade) {
+    materialiseLegacyTypography(
+      reconnected,
+      oldRoleStyle,
+      spec.inheritedFontFamily,
+    );
+  } else {
+    pinUnset(reconnected, spec.renderedDefaults);
+    pinUnset(reconnected, typographyOf(oldRoleStyle));
+    pinUnset(reconnected, DETACHED_UNSET_EFFECTIVE);
+
+    if (!oldRoleStyle) {
+      pinUnset(reconnected, {
+        fontSize: INHERITED_FONT_SIZE,
+        fontFamily: spec.inheritedFontFamily,
+      });
+    }
+  }
+
+  reconnected.textStyleType = role;
+
+  const normalized = normalizeTextStyleAgainstRole(reconnected, options);
+  const kept = normalized as unknown as Record<string, unknown>;
+
+  // Where a renderer default beats the role, a value equal to the role still differs from what an
+  // unset prop would draw, so it stays.
+  for (const [prop, drawnDefault] of Object.entries(
+    spec.renderedDefaults ?? {},
+  )) {
+    const value = (reconnected as unknown as Record<string, unknown>)[prop];
+
+    if (!isUnset(value) && value !== drawnDefault) kept[prop] = value;
+  }
+
+  // A neutral (normal / none) the new role leaves unset draws the same unpinned, and unpinned a
+  // later role edit still reaches the field; keep it only where the role defines that prop.
+  const roleStyle = options?.[role]?.style as unknown as
+    | Record<string, unknown>
+    | undefined;
+
+  for (const [prop, neutral] of Object.entries(DETACHED_UNSET_EFFECTIVE)) {
+    if (
+      kept[prop] === neutral &&
+      isUnset(roleStyle?.[prop]) &&
+      !(prop in (spec.renderedDefaults ?? {}))
+    ) {
+      delete kept[prop];
+    }
+  }
+
+  return normalized as T;
+};
+
+// A role's colour, read defensively: the typed property is retired.
+const roleColourOf = (
+  options: TextStyleOptions,
+  role: unknown,
+): string | undefined =>
+  (
+    options[role as keyof TextStyleOptions]?.style as unknown as
+      | Record<string, string | undefined>
+      | undefined
+  )?.color;
+
+// A linked nav link draws `element || #000000` (`getTextStyleByContentTextStyle`). One with no colour
+// of its own drew its legacy role's colour, or on no role inherited its parent's: for a tab the
+// header's colour, else the page base coat (the paragraphs colour); for the hamburger menu, which
+// renders beside the header under the page root (`Page.vue`), the base coat. That colour is kept
+// before the link. Role colours are only still present during migration-22; later, only the
+// header's colour is left to inherit.
+const keepNavLinkColour = (
+  style: unknown,
+  options: TextStyleOptions,
+  headerColour: string | undefined,
+): void => {
+  if (!style || typeof style !== 'object') return;
+
+  const props = style as Record<string, unknown>;
+  const type = props.textStyleType;
+
+  if (!isBlankColorValue(props.color as string | undefined)) return;
+
+  if (isCanonicalTextStyleType(type)) return;
+
+  const colour = isLegacyTextStyleType(type as string | undefined)
+    ? roleColourOf(options, type)
+    : headerColour || roleColourOf(options, 'paragraphs');
+
+  if (!isBlankColorValue(colour)) props.color = colour;
+};
+
+type StyleHolder = Record<string, unknown> | undefined;
+
+// `isTiptapDocument`, which lives maker-side.
+const isTiptapDoc = (value: unknown): boolean =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { type?: unknown }).type === 'doc';
+
+// The sections whose success message now draws from its own `successMessageStyle`: the payment
+// block (`Payment.vue`) and the shop checkout (`PaymentModal.vue`).
+const SUCCESS_MESSAGE_TYPES: ReadonlySet<string> = new Set([
+  'support-me',
+  'request-payment',
+  'shop-section',
+]);
+
+// Before BP-5969 neither renderer drew `successMessageStyle`, so one on no canonical role (the
+// old maker editor's `{ textAlign }`) is treated as absent (James Joung, 2026-09-28).
+const seedsSuccessMessageStyle = (fields: Record<string, unknown>): boolean =>
+  SUCCESS_MESSAGE_TYPES.has(fields.type as string) &&
+  !isCanonicalTextStyleType(
+    (fields.successMessageStyle as StyleHolder)?.textStyleType,
+  );
+
+// What the shop checkout drew its message with: the drawn (pre-reconnect) description's colour,
+// less the container rung the shop lacks. On no role it drew `inherit`, which fe-shared-lib's `Modal`
+// passes to the page root's Paragraphs colour (`Page.mixin` `rootElementStyles`), seeded onto
+// Paragraph 1. Role colours are only still present during migration-22.
+const shopSuccessMessageColour = (
+  drawnDescription: StyleHolder,
+  options: TextStyleOptions,
+): string | undefined =>
+  (drawnDescription?.color as string | undefined) ||
+  roleColourOf(options, drawnDescription?.textStyleType) ||
+  roleColourOf(options, 'paragraphs');
+
+/**
+ * Give a success message the look it drew, on a role of its own (James Joung, 2026-09-28). The
+ * payment block drew it with its description's style, so it gets a copy of the reconnected
+ * description. With no description, and in the shop checkout (which took only the description's
+ * colour), it drew the page defaults, so it starts on Paragraph 2 keeping them, and the shop keeps
+ * that colour. A rich-text message drew only its runs and the page (`TextWrapper` gives rich text no
+ * typography from its style object), so on migration-22's input it keeps the page defaults on the
+ * description's role, lifted onto its runs: the render fill reads a neutral block value as "follow
+ * the role".
+ */
+const seedSuccessMessageStyle = (
+  fields: Record<string, unknown>,
+  drawnDescription: StyleHolder,
+  options: TextStyleOptions,
+  reconnectAt: (holder: StyleHolder, key: string, spec?: ReconnectSpec) => void,
+  walk: Pick<ReconnectSpec, 'drawnBeforeCascade'>,
+): void => {
+  const description = fields.descriptionStyle as StyleHolder;
+  const isShop = fields.type === 'shop-section';
+  const drewPageDefaults =
+    !!walk.drawnBeforeCascade && isTiptapDoc(fields.successMessage);
+
+  if (
+    !isShop &&
+    !drewPageDefaults &&
+    description &&
+    typeof description === 'object'
+  ) {
+    fields.successMessageStyle = { ...description };
+
+    return;
+  }
+
+  const colour = isShop
+    ? shopSuccessMessageColour(drawnDescription, options)
+    : (description?.color as string | undefined);
+  const descriptionRole = description?.textStyleType;
+
+  fields.successMessageStyle = isBlankColorValue(colour)
+    ? {}
+    : { color: colour };
+  reconnectAt(fields, 'successMessageStyle', {
+    startingRole:
+      !isShop && isCanonicalTextStyleType(descriptionRole)
+        ? descriptionRole
+        : 'paragraph2',
+  });
+
+  if (drewPageDefaults) {
+    liftRteFieldOntoRole(
+      fields.successMessage,
+      fields.successMessageStyle as TextStyleDeclaration,
+      options,
+    );
+  }
+};
+
+// The font the v21 page root drew: the retired site text font, else the default. Only migration-22
+// reads it (jobs A2 and B), before its last job deletes the field (`0036-retire-text-font-family.md`).
+export const siteTextFontName = (
+  brandPageModel: BrandPageModel,
+): string | undefined => {
+  const textStyles = brandPageModel.styles?.textStyles as unknown as
+    | Record<string, unknown>
+    | undefined;
+  const textFontFamily = (textStyles?.['textFontFamily'] ||
+    DEFAULT_FONT_FAMILY_KEY) as FontFamilyKey;
+
+  return FONT_FAMILY_CONFIGS[textFontFamily]?.name;
+};
+
+/**
+ * Reconnect every persisted text field outside the ten, in place: content style keys (each with
+ * `contentFieldReconnectSpec`) and `textItems[].textStyle`, then per viewport the footer copyright,
+ * the nav tabs (starting role `paragraph1`), the hamburger menu (`button`) and the header button
+ * (`button`), then the Save Contact button (`button`). An unset family keeps the site text font.
+ * A payment or shop success message with no role of its own gets the look it drew
+ * (`seedSuccessMessageStyle`). Otherwise a no-op on canonical data.
+ */
+export const reconnectTextStyleRoles = (
+  brandPageModel: BrandPageModel,
+  targets: LegacyTargetMap,
+  options: TextStyleOptions,
+  walk: Pick<ReconnectSpec, 'drawnBeforeCascade'> & {
+    renderedDefaultsForContent?: RenderedDefaultsForContent;
+  } = {},
+): void => {
+  const inheritedFontFamily = siteTextFontName(brandPageModel);
+
+  const reconnectAt = (
+    holder: StyleHolder,
+    key: string,
+    spec: ReconnectSpec = {},
+  ): void => {
+    const style = holder?.[key];
+
+    if (!holder || !style || typeof style !== 'object') return;
+
+    const renderedDefaults = walk.renderedDefaultsForContent?.(holder, key);
+
+    holder[key] = reconnectTextStyle(style, targets, options, {
+      ...spec,
+      drawnBeforeCascade: walk.drawnBeforeCascade,
+      renderedDefaults: {
+        ...spec.renderedDefaults,
+        ...renderedDefaults,
+      },
+      inheritedFontFamily,
+    });
+  };
+
+  const styleKeys = Object.keys(CONTENT_TEXT_STYLE_PROPERTY_KEYS);
+
+  for (const page of brandPageModel.pages ?? []) {
+    for (const content of page.contents ?? []) {
+      const fields = content as unknown as Record<string, unknown>;
+      const seedsSuccessMessage = seedsSuccessMessageStyle(fields);
+      // The reconnect replaces the style object, so this stays the description as it was drawn.
+      const drawnDescription = fields.descriptionStyle as StyleHolder;
+
+      if (seedsSuccessMessage) delete fields.successMessageStyle;
+
+      for (const key of styleKeys) {
+        reconnectAt(
+          fields,
+          key,
+          contentFieldReconnectSpec(fields.type as string | undefined, key),
+        );
+      }
+
+      if (seedsSuccessMessage) {
+        seedSuccessMessageStyle(
+          fields,
+          drawnDescription,
+          options,
+          reconnectAt,
+          walk,
+        );
+      }
+
+      const textItems = fields.textItems;
+
+      if (Array.isArray(textItems)) {
+        for (const item of textItems) {
+          if (item && typeof item === 'object') {
+            reconnectAt(item as StyleHolder, 'textStyle');
+          }
+        }
+      }
+    }
+  }
+
+  for (const footer of [
+    brandPageModel.pageFooterDesktop,
+    brandPageModel.pageFooterMobile,
+  ]) {
+    reconnectAt(footer as unknown as StyleHolder, 'copyrightStyle');
+  }
+
+  for (const header of [
+    brandPageModel.pageHeaderDesktop,
+    brandPageModel.pageHeaderMobile,
+  ]) {
+    const navigation = header?.navigation as unknown as StyleHolder;
+    const headerColour = (header?.style as { color?: string } | undefined)
+      ?.color;
+
+    keepNavLinkColour(navigation?.defaultButtonStyle, options, headerColour);
+    keepNavLinkColour(
+      (navigation?.hamburgerMenuStyle as StyleHolder)?.defaultButtonStyle,
+      options,
+      undefined,
+    );
+
+    reconnectAt(navigation, 'defaultButtonStyle', {
+      startingRole: 'paragraph1',
+    });
+    reconnectAt(
+      navigation?.hamburgerMenuStyle as StyleHolder,
+      'defaultButtonStyle',
+      { startingRole: 'button' },
+    );
+    reconnectAt(
+      header?.headerButton as unknown as StyleHolder,
+      'buttonTextStyle',
+      BUTTON_ELEMENT_RECONNECT,
+    );
+  }
+
+  reconnectAt(
+    brandPageModel.saveContactSettings as unknown as StyleHolder,
+    'buttonTextStyle',
+    { startingRole: 'button' },
+  );
+};