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

package/lib/src/brand-page/utils/migration/migration-21.js

@@ -4,10 +4,17 @@ import { isHexTransparent } from '../color.util';
 import { isLogoContent } from '../model.util';
 import { PALETTE_COLOR_IDS, ColorPaletteBuilder, DEFAULT_PRIMARY, DEFAULT_SECONDARY, isBlankColorValue, classifyColor, paletteRoleIdForToken, generateNeutralPalette, walkModelColors, colourBearingParts, makeReferencifyTransform, roleIdsByCanonicalValue, } from '../color-palette.util';
 import { parseShapeMatch, shapeMatchValue, } from '../shape-color-match.util';
-import { resolveTextColor } from '../text-style.util';
-import { rteFrameFallbackColour, CONTAINER_BOUND_TEXT_STYLE_KEYS, } from '../container-text-color.util';
+import { rteFrameFallbackColour } from '../container-text-color.util';
 import { RTE_SECTION_FIELD_PAIRS } from '@shared/color-strategies/rte-field-pairs';
 import { collectRteTextColors, fillUncolouredRteText, } from '@shared/color-strategies/rte-color';
+/**
+ * FROZEN copy of `resolveTextColor`'s three-rung cascade as it was when this migration
+ * shipped: `element.color || fallbackBeforeGlobal || role.color`. migration-21 is
+ * immutable, so it must keep baking the exact colours it always did — but the shared
+ * `resolveTextColor` dropped the role rung (ADR-0020). Resolving against this local copy
+ * keeps this migration's output byte-identical instead of tracking the live util.
+ */
+const resolveTextColorV1 = (elementStyle, globalStyle, fallbackBeforeGlobal) => elementStyle?.color || fallbackBeforeGlobal || globalStyle?.color;
 /**
  * Migration 21 (Global Color V2): move every concrete colour in the metadata into a
  * central `styles.colors` palette and rewrite each reference to `var(--<id>)`. The
@@ -347,6 +354,9 @@ export const moveRootTextColourIntoGlobalStyles = (brandPageModel) => {
     };
     // Explicit keys, not Object.values — a stray persisted key is not a text style.
     for (const [type, source] of Object.entries(seedSourceByType)) {
+        // `color` was retired from `GlobalTextStyleDeclaration` (ADR-0020); this frozen
+        // migration still seeds it as the pre-decouple root colour (a later migration bakes it
+        // onto elements and clears it). Colour view only — typing-only, behaviour-identical.
         const style = options[type]?.style;
         if (style && !isBlankColorValue(source) && isBlankColorValue(style.color)) {
             style.color = source;
@@ -481,6 +491,22 @@ export const seedLogoBackgroundColour = (brandPageModel) => {
 /* -------------------------------------------------------------------------- *
  * Step FINAL+1: bake resolved text colours into RTE content
  * -------------------------------------------------------------------------- */
+/**
+ * The container-bound text fields as this migration was released with them. Pinned: the live
+ * `CONTAINER_BOUND_TEXT_STYLE_KEYS` later gained the payment success message (BP-5969), which
+ * this released migration never baked.
+ */
+const CONTAINER_BOUND_TEXT_STYLE_KEYS_V21 = {
+    'mailing-list': ['titleStyle'],
+    'request-payment': ['titleStyle', 'descriptionStyle', 'itemTextStyle'],
+    'support-me': [
+        'titleStyle',
+        'headingStyle',
+        'descriptionStyle',
+        'itemTextStyle',
+    ],
+    'contact-form': ['titleStyle', 'descriptionStyle', 'successMessageStyle'],
+};
 /**
  * Blocks whose `successMessage` needs its own baked RTE colour. It carries no colour of
  * its own — no `successMessageStyle`, stored as plain text — so on legacy metadata both
@@ -511,7 +537,7 @@ const SUCCESS_MESSAGE_RTE_TYPES = new Set([
  */
 const bakeSuccessMessageColour = (fields, descriptionStyle, frameColour, globalStyleFor) => {
     const successMessage = fields.successMessage;
-    const colour = resolveTextColor(descriptionStyle, globalStyleFor(descriptionStyle?.textStyleType), frameColour);
+    const colour = resolveTextColorV1(descriptionStyle, globalStyleFor(descriptionStyle?.textStyleType), frameColour);
     if (isBlankColorValue(colour)) {
         return;
     }
@@ -560,7 +586,7 @@ const bakeSuccessMessageColour = (fields, descriptionStyle, frameColour, globalS
  * the resolved `titleStyle.color`. So a run whose mark carries no colour inherits the
  * nearest coloured ancestor, and a container block's frame (`sectionFrameStyle`) paints
  * the BUTTON colour: the title renders the button/primary colour, not its linked heading
- * colour. This bakes a resolved colour into the uncoloured runs via `resolveTextColor` —
+ * colour. This bakes a resolved colour into the uncoloured runs via `resolveTextColorV1` —
  * element colour, else the render-neutral frame fallback (`rteFrameFallbackColour`: the
  * section frame's button-label colour for every framed block — text/profile on a solid
  * background and the container-bound blocks — so a legacy run keeps exactly the colour it
@@ -602,7 +628,8 @@ const bakeResolvedTextColoursIntoContents = (brandPageModel, baseCoatColour) =>
         // `|| baseCoatColour` is the terminal rung: an unframed, unlinked run inherited the page
         // base coat pre-V2 (the root text colour on the Page root element). Baking it reproduces
         // V1 instead of the post-V2 inherit, which re-pointed the root to the paragraphs colour.
-        const resolved = resolveTextColor(styleObj, globalStyleFor(styleObj?.textStyleType), fallbackBeforeGlobal) || baseCoatColour;
+        // Resolve against the frozen V1 copy — the shared resolver dropped the role rung (ADR-0020).
+        const resolved = resolveTextColorV1(styleObj, globalStyleFor(styleObj?.textStyleType), fallbackBeforeGlobal) || baseCoatColour;
         if (isBlankColorValue(resolved)) {
             return;
         }
@@ -656,7 +683,8 @@ const bakeResolvedTextColoursIntoContents = (brandPageModel, baseCoatColour) =>
             // — the `isBlankColorValue` guard skips those, keeping their contrast colour.
             if (frameColour) {
                 const rteStyleFields = new Set(pairs.map((pair) => pair.styleField));
-                for (const key of CONTAINER_BOUND_TEXT_STYLE_KEYS[content.type] ?? []) {
+                for (const key of CONTAINER_BOUND_TEXT_STYLE_KEYS_V21[content.type] ??
+                    []) {
                     if (rteStyleFields.has(key)) {
                         continue; // RTE field — its mark already carries the frame colour.
                     }

package/lib/src/brand-page/utils/migration/migration-22.d.ts

@@ -0,0 +1,99 @@
+import type { MigrationData, MigrationOptions } from '../migration.util';
+import { type BrandPageModel } from '../../models';
+import { type TextStyleOptions } from '../../models/styles.model';
+import { computeLegacyTargets, type LegacyTargetMap } from '../text-role-reconnect.util';
+/**
+ * BP-5969 migration-22 — the single-source text-style migration. Version-gated: runs
+ * once when `v < 22`. The durable decisions are `0019-retire-rte-object-style-sync.md`,
+ * `0020-role-is-typography-only-colour-is-contrast-derived.md`, and
+ * `0021-migrated-content-reconnects-to-nearest-role-with-override.md`.
+ *
+ * A/B/C are appearance-preserving. D/E/G finish the ADR-0020 colour decouple in the same
+ * (still-unreleased) migration — they too preserve appearance, by freezing each element's
+ * currently-resolved colour before the role colour and base coat that fed it are removed.
+ * One decided exception (ADR-0020, Update 2026-09-29): a social-links section with no base
+ * coat to freeze bakes its icon fill to the title's contrast colour instead — a new colour,
+ * not a literal freeze of whatever `currentColor` happened to paint under `:root`.
+ *  A.  Seed each old role's colour onto its target tier (D3 base coat) — `seedRoleColours`.
+ *      Roles keep their §4 size, weight and line height; the old size is preserved as a per-block
+ *      override by B. The legacy → tier map is computed per-site by `computeLegacyTargets`.
+ *  A2. (R16) Count the font the site's title/heading, description/paragraph and button text shows,
+ *      and give each family the winner — each family's font comes from the site's text, not §4 —
+ *      before B and C link equal text to it — `seedRoleFonts`.
+ *  B.  Seed the absent header-button / brand.contact Save Contact styles (they rendered as
+ *      `buttons`), then reconnect every text field outside the ten — content, text items, footer
+ *      copyright, nav, header button, Save Contact — to its nearest role, keeping its look as
+ *      overrides — `reconnectContentRoles` (the shared `text-role-reconnect.util`). The three old
+ *      no-role renderer defaults (mailing-list title, Support Me title, text block) are materialised
+ *      here only, before reconnect persists their effective values; no runtime reader keeps them. A colourless nav
+ *      link's colour is baked here, not in D: it comes from the legacy role, which B replaces. A
+ *      payment or shop success message with no role of its own gets the look it drew
+ *      (`seedSuccessMessageStyle`); D then bakes its colour, like any non-RTE style.
+ *  C.  Baked→override strip/lift on RTE fields (D4) — `stripLiftContentRte`; per field it also folds
+ *      legacy bold/italic/underline/strike marks into the run's textStyle attrs (`foldSemanticFormattingMarks`)
+ *      and pins a not-bold legacy block's weight so a bold heading tier can't bold it (`pinLegacyRunWeight`).
+ *  B1. Convert plain-text RTE-eligible fields to Tiptap docs — `convertPlainRteFields`.
+ *  D.  Bake each element's resolved colour explicitly, social-links icon fills included —
+ *      `bakeElementColours`.
+ *  E.  Clear the retired role colour — `clearRoleColours`.
+ *  G.  Colour-decouple RTE-paired style objects: remove `color` only — `stripRteStyleColours`.
+ *  H.  Delete the retired site text font and its footer copies — `deleteTextFontFamily`
+ *      (`0036-retire-text-font-family.md`). A2 and B read it through `siteTextFontName`.
+ *
+ * Ordering is load-bearing: D reads the base coat off `paragraph1` and the role colours (which A
+ * seeds from the old roles), so it must run after A and before E; B must run before C and D, which
+ * read each field's reconnected role and pinned typography; G removes the RTE style object's
+ * colour, so it must run after D has baked that colour into the mark. B1 runs after C (so C's
+ * per-run typography bake sees real editor-baked docs, not a freshly-converted placeholder) and
+ * before D (so D colours the converted runs like any other doc). A2 runs before B, C, B1, which
+ * read the role's font: on the untouched model, so it counts what a legacy-role or no-role field
+ * showed before B relinks it, and links B and C to bake against the winner it seeds. H runs last,
+ * after every reader of the site text font.
+ *
+ * Version-gated (v only moves forward), so this runs exactly once. A hypothetical re-run is a
+ * no-op throughout: B (seed + reconnect), C (strip + weight pin) and B1 (convert) find every button
+ * style present and every field on one of the ten, no baked role-equal typography, every bare run
+ * already weight-pinned and no plain strings left; D/E/G find every element already coloured, role
+ * colours already cleared and RTE style objects already colourless; H finds nothing to delete; and
+ * A (`seedRoleColours`) finds nothing to copy — E already cleared the legacy roles' colour
+ * (persisted), so the tiers keep their §4 typography untouched. A2 re-counts what the migrated
+ * site shows, the same fonts, so it picks the same winners — also a no-op. Unreachable behind the
+ * gate; documented here per the migration rules.
+ */
+export { computeLegacyTargets };
+export { stripLiftRteDoc, foldSemanticFormattingMarks, pinLegacyRunWeight, stripLiftContentRte, } from '../rte-role-lift.util';
+/**
+ * Seed each old legacy role's colour onto its target tier — COLOUR ONLY; the tier keeps its
+ * §4 default typography. `bakeElementColours` (D) freezes each element's colour by reading its
+ * tier, and the base coat off `paragraph1`, so a legacy block's colour is preserved exactly as
+ * long as the tier it links to carries the old role's colour. `clearRoleColours` (E) then wipes
+ * the seed once D has read it — the tier ends typography-only, per ADR-0020.
+ */
+export declare const seedRoleColours: (options: TextStyleOptions, targets: LegacyTargetMap) => void;
+/**
+ * A2 — count the font the site's title/heading, description/paragraph and button text shows
+ * (`business-rules.md` *Text style roles*), and give each family the winner, before B and C link
+ * equal text to it. Runs on the untouched v21 model, after A and before B: a field's font is read
+ * the same way B will read its look (`drawnFontFamily`), so the count and the reconnect can't
+ * disagree about what a field showed. Only `fontFamily` changes on the ten canonical roles — size,
+ * weight and line height stay at their §4 defaults. A family with no vote keeps Lato.
+ */
+export declare const seedRoleFonts: (brandPageModel: BrandPageModel, options: TextStyleOptions) => void;
+export declare const reconnectContentRoles: (brandPageModel: BrandPageModel, targets: LegacyTargetMap, options: TextStyleOptions) => void;
+type NoRoleTextStyles = WeakMap<object, Set<string>>;
+/**
+ * D — freeze each text element's currently-resolved colour so removing the base coat (F)
+ * and the role colour (E) changes no pixels. migration-21 already baked element→frame→role
+ * colour into RTE runs, so the only uncoloured runs reaching here inherit the base coat;
+ * non-RTE fields (21 left them alone) resolve element→container-default→role→base coat.
+ * `buttonTextStyle` is excluded — the button label takes its colour from `buttonStyles`,
+ * never the base coat. A social-links section's unset icon fill is frozen here too.
+ */
+export declare const bakeElementColours: (brandPageModel: BrandPageModel, options: TextStyleOptions, noRoleTextStyles?: NoRoleTextStyles) => void;
+/** E — clear the retired role colour from every role definition (run after D reads it). */
+export declare const clearRoleColours: (options: TextStyleOptions) => void;
+export declare const stripRteStyleColours: (brandPageModel: BrandPageModel) => void;
+/** H — delete the retired site text font and the footers' stray copies. */
+export declare const deleteTextFontFamily: (brandPageModel: BrandPageModel) => void;
+export declare const convertPlainRteFields: (brandPageModel: BrandPageModel, options: TextStyleOptions) => Promise<void>;
+export declare const migration22: (migrationResult: MigrationData, _options: MigrationOptions) => Promise<MigrationData>;