@designcrowd/library.brand-page 6.2.11 → 6.2.12

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

@@ -0,0 +1,434 @@
+import { isLegacyTextStyleType, isCanonicalTextStyleType, CANONICAL_TEXT_STYLE_TYPES, } 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, } 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 };
+const parseEm = (value) => {
+    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'));
+export const FAMILY_TIERS = {
+    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, tiers) => 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) => {
+    const nearestHeading = (role, exclude) => {
+        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, family) => {
+    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 = {
+    fontWeight: 'normal',
+    fontStyle: 'normal',
+    textDecoration: 'none',
+    lineHeight: 'normal',
+    letterSpacing: 'normal',
+};
+const LEGACY_TYPOGRAPHY_PROPS = [
+    'fontFamily',
+    'fontSize',
+    'fontWeight',
+    'fontStyle',
+    'textDecoration',
+    'lineHeight',
+    'letterSpacing',
+];
+const isUnset = (value) => 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, oldRoleStyle, inheritedFontFamily) => {
+    const pinned = { ...style };
+    const old = oldRoleStyle;
+    const inherited = {
+        ...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;
+};
+// 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, oldRoleStyle, inheritedFontFamily) => {
+    const pinned = pinDrawnLook(style, oldRoleStyle, inheritedFontFamily);
+    const props = style;
+    for (const prop of LEGACY_TYPOGRAPHY_PROPS) {
+        if (prop in pinned)
+            props[prop] = pinned[prop];
+        else
+            delete props[prop];
+    }
+};
+const typographyOf = (style) => {
+    const props = (style ?? {});
+    return Object.fromEntries(LEGACY_TYPOGRAPHY_PROPS.map((prop) => [prop, props[prop]]));
+};
+const pinUnset = (style, values) => {
+    const props = style;
+    for (const [prop, value] of Object.entries(values ?? {})) {
+        if (isUnset(props[prop]) && value !== undefined)
+            props[prop] = value;
+    }
+};
+// 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 = {
+    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 = {
+    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 = {
+    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, key) => {
+    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 }))
+        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, options, siteFont) => {
+    const props = (style ?? {});
+    const type = props.textStyleType;
+    const ownFont = props.fontFamily;
+    if (isCanonicalTextStyleType(type)) {
+        const roleFont = options?.[type]?.style?.fontFamily;
+        return ownFont || roleFont || siteFont;
+    }
+    const retired = isLegacyTextStyleType(type)
+        ? type
+        : undefined;
+    const oldRoleStyle = retired ? options?.[retired]?.style : undefined;
+    if (!oldRoleStyle)
+        return ownFont || siteFont;
+    const pinned = pinDrawnLook(props, oldRoleStyle, siteFont);
+    return pinned.fontFamily ?? 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 = (style, targets, options, spec = {}) => {
+    const type = style.textStyleType;
+    if (isCanonicalTextStyleType(type))
+        return style;
+    const reconnected = { ...style };
+    const retired = isLegacyTextStyleType(type)
+        ? type
+        : 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;
+    // 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[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;
+    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;
+};
+// A role's colour, read defensively: the typed property is retired.
+const roleColourOf = (options, role) => options[role]?.style?.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, options, headerColour) => {
+    if (!style || typeof style !== 'object')
+        return;
+    const props = style;
+    const type = props.textStyleType;
+    if (!isBlankColorValue(props.color))
+        return;
+    if (isCanonicalTextStyleType(type))
+        return;
+    const colour = isLegacyTextStyleType(type)
+        ? roleColourOf(options, type)
+        : headerColour || roleColourOf(options, 'paragraphs');
+    if (!isBlankColorValue(colour))
+        props.color = colour;
+};
+// `isTiptapDocument`, which lives maker-side.
+const isTiptapDoc = (value) => typeof value === 'object' &&
+    value !== null &&
+    value.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 = 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) => SUCCESS_MESSAGE_TYPES.has(fields.type) &&
+    !isCanonicalTextStyleType(fields.successMessageStyle?.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, options) => drawnDescription?.color ||
+    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, drawnDescription, options, reconnectAt, walk) => {
+    const description = fields.descriptionStyle;
+    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;
+    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, 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) => {
+    const textStyles = brandPageModel.styles?.textStyles;
+    const textFontFamily = (textStyles?.['textFontFamily'] ||
+        DEFAULT_FONT_FAMILY_KEY);
+    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, targets, options, walk = {}) => {
+    const inheritedFontFamily = siteTextFontName(brandPageModel);
+    const reconnectAt = (holder, key, spec = {}) => {
+        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;
+            const seedsSuccessMessage = seedsSuccessMessageStyle(fields);
+            // The reconnect replaces the style object, so this stays the description as it was drawn.
+            const drawnDescription = fields.descriptionStyle;
+            if (seedsSuccessMessage)
+                delete fields.successMessageStyle;
+            for (const key of styleKeys) {
+                reconnectAt(fields, key, contentFieldReconnectSpec(fields.type, 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, 'textStyle');
+                    }
+                }
+            }
+        }
+    }
+    for (const footer of [
+        brandPageModel.pageFooterDesktop,
+        brandPageModel.pageFooterMobile,
+    ]) {
+        reconnectAt(footer, 'copyrightStyle');
+    }
+    for (const header of [
+        brandPageModel.pageHeaderDesktop,
+        brandPageModel.pageHeaderMobile,
+    ]) {
+        const navigation = header?.navigation;
+        const headerColour = header?.style
+            ?.color;
+        keepNavLinkColour(navigation?.defaultButtonStyle, options, headerColour);
+        keepNavLinkColour(navigation?.hamburgerMenuStyle?.defaultButtonStyle, options, undefined);
+        reconnectAt(navigation, 'defaultButtonStyle', {
+            startingRole: 'paragraph1',
+        });
+        reconnectAt(navigation?.hamburgerMenuStyle, 'defaultButtonStyle', { startingRole: 'button' });
+        reconnectAt(header?.headerButton, 'buttonTextStyle', BUTTON_ELEMENT_RECONNECT);
+    }
+    reconnectAt(brandPageModel.saveContactSettings, 'buttonTextStyle', { startingRole: 'button' });
+};

package/lib/src/brand-page/utils/text-style.util.d.ts

@@ -1,35 +1,65 @@
 /**
  * The element ↔ global-text-style resolution rules, in ONE place.
  *
- * Deliberately a leaf module with no imports so both the renderer
- * (`view-model.util.ts`) and the maker's Text Style panel can consume it. They
- * resolved colour independently and drifted, so the sidebar contradicted the canvas —
- * import from here rather than restating the chain.
+ * A near-leaf module: its only dependency is the role model (`styles.model`, a lower-level
+ * module with no back-edge to here, so no cycle). Both the renderer (`view-model.util.ts`) and
+ * the maker's Text Style panel consume it — they resolved colour independently and drifted, so
+ * the sidebar contradicted the canvas — import from here rather than restating the chain.
+ *
+ * MIGRATION-22 SNAPSHOT DEPENDENCY: `normalizeTextStyleAgainstRole` is called by its reconnect
+ * path. Do not change normalisation semantics after migration-22 releases without first pinning
+ * that migration's implementation.
  */
+import { type TextStyleOptions } from '../models/styles.model';
+import { type CascadeTypographyProp } from '@shared/text-role-typography.util';
+export { type CascadeTypographyProp, composeTextDecoration, NEUTRAL_TYPOGRAPHY_VALUE, rteTextDecorationClassName, TEXT_STYLE_CASCADE_PROPS, } from '@shared/text-role-typography.util';
+export { omitTypography, pickTypography, } from '@shared/text-role-typography.util';
 interface ColouredStyle {
     color?: string;
 }
 /**
- * **`color` cascades; typography does not.** A global text style
- * (`textStyleOptions[type]`) is only a *default* for colour: the element's own
- * `color` wins. Every other property still comes from the global style wholesale —
- * that all-or-nothing behaviour is deliberately unchanged, so don't "fix" the
- * inconsistency by reverting this; the resolution is to make every property cascade.
- *
- * The **site-wide default** (`textStyleOptions.paragraphs.style.color`) is
- * deliberately NOT in this chain — it reaches the text by CSS inheritance from the
- * root element (`Page.mixin.ts` → `rootElementStyles`). So `undefined` here validly
- * means "inherit", and mappers must not pre-seed the site default into an element
- * style (it would read as an element override and beat the global text style).
+ * BP-5969 (ADR-0020): **a role no longer contributes colour** — a text role defines
+ * typography only. Colour resolves element-first, then an optional container middle
+ * rung; with neither set it falls to the page base coat by CSS inheritance from the
+ * root element (`Page.mixin.ts` → `rootElementStyles`), so `undefined` here validly
+ * means "inherit" and mappers must not pre-seed a default into an element style.
  *
  * Empty-string is treated as unset (`||`, not `??`) — a cleared colour field falls
- * back to the global style rather than painting an invalid value.
+ * through rather than painting an invalid value.
+ *
+ * `fallbackBeforeGlobal` is the container middle rung: a context-derived default that
+ * wins over the base coat but still yields to an explicit element colour. Only
+ * container-bound blocks supply it (text on the block's own filled surface must
+ * contrast that surface, not the page — see `container-text-color.util.ts`).
+ */
+export declare const resolveTextColor: (elementStyle: ColouredStyle | undefined, fallbackBeforeGlobal?: string) => string | undefined;
+/**
+ * BP-5969 (ADR-0019) — the WRITE-side mirror of `overrideTypographyStyle`: drop any typography
+ * override equal to the block's linked role, so the persisted style stays a sparse diff and a later
+ * role edit repaints the block via the page-scoped role CSS. Colour, alignment and `applyAutoScale`
+ * are untouched. No-op for a non-style value, a legacy/unlinked role (no role class to fall back
+ * on), or an absent role table — the value passes through unchanged.
+ *
+ * Pure: the caller supplies the role table, so the maker store and the AI metadata builder share
+ * one normalization authority instead of drifting.
+ */
+export declare const normalizeTextStyleAgainstRole: <T>(value: T, textStyleOptions: TextStyleOptions | undefined) => T;
+type TypographyStyle = Partial<Record<CascadeTypographyProp, string | undefined>> & ColouredStyle;
+export declare const resolveTextStyle: <R extends TypographyStyle, E extends TypographyStyle>(elementStyle: E | undefined, roleStyle: R | undefined, fallbackBeforeGlobal?: string) => TypographyStyle;
+/**
+ * BP-5969 (ADR-0019, Option B) — the render-time inverse of `resolveTextStyle`.
+ * The role's typography is supplied by a page-scoped CSS class (`text-role-css.util`),
+ * so a linked block must inline ONLY the props that DIFFER from its role — those beat
+ * the class by specificity; the rest fall through to the class, and editing the role
+ * repaints them for free. Colour is deliberately absent (it isn't in the class — it
+ * stays on its own cascade / on RTE marks).
+ *
+ * `roleStyle` undefined (no role in scope, or a non-canonical/unlinked block) returns
+ * every present typography prop — i.e. the caller bakes the full resolved style inline,
+ * exactly as before this change. That is the safe fallback: the render stays
+ * pixel-identical when the role isn't visible to the renderer.
  *
- * `fallbackBeforeGlobal` is an optional middle rung: a context-derived default that
- * wins over the global style but still yields to an explicit element colour. Only
- * container-bound blocks supply it (text sitting on the block's own filled surface
- * must contrast that surface, not the page — see `container-text-color.util.ts`).
- * Omitting it is byte-for-byte the original two-rung cascade.
+ * Empty-string / null are treated as unset (matching the `||` in the resolvers), and
+ * `'0'` (a valid letter-spacing) stays.
  */
-export declare const resolveTextColor: (elementStyle: ColouredStyle | undefined, globalStyle: ColouredStyle | undefined, fallbackBeforeGlobal?: string) => string | undefined;
-export {};
+export declare const overrideTypographyStyle: (resolvedStyle: TypographyStyle | undefined, roleStyle: TypographyStyle | undefined) => Partial<Record<CascadeTypographyProp, string>>;