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

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

@@ -0,0 +1,305 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveTextColor,
+  resolveTextStyle,
+  overrideTypographyStyle,
+  normalizeTextStyleAgainstRole,
+  composeTextDecoration,
+  rteTextDecorationClassName,
+} from './text-style.util';
+import type { TextStyleOptions } from '../models/styles.model';
+
+describe('text-style.util', () => {
+  describe('resolveTextColor (element-first; role rung retired — ADR-0020)', () => {
+    it('prefers element colour, then the container fallback; the role no longer contributes', () => {
+      expect(resolveTextColor({ color: 'red' }, 'blue')).toBe('red');
+      expect(resolveTextColor({}, 'green')).toBe('green');
+      // Role colour is ignored now — with no element colour and no fallback the value is
+      // unset, so the page base coat applies by root CSS inheritance.
+      expect(resolveTextColor({})).toBeUndefined();
+    });
+
+    it('treats empty-string element colour as unset (falls through; role ignored)', () => {
+      expect(resolveTextColor({ color: '' })).toBeUndefined();
+    });
+  });
+
+  describe('resolveTextStyle (per-property cascade, BP-5969)', () => {
+    const role = {
+      fontFamily: 'Lato',
+      fontSize: '2em',
+      fontWeight: '700',
+      lineHeight: '1.2',
+      color: 'navy',
+    };
+
+    it('falls through to the role for every unset TYPOGRAPHY property (colour is not a role prop)', () => {
+      const resolved = resolveTextStyle({}, role);
+
+      expect(resolved.fontFamily).toBe('Lato');
+      expect(resolved.fontSize).toBe('2em');
+      expect(resolved.fontWeight).toBe('700');
+      expect(resolved.lineHeight).toBe('1.2');
+      // ADR-0020: the role's colour does NOT cascade — unset element colour resolves to
+      // undefined (the page base coat applies by root inheritance, not the resolver).
+      expect(resolved.color).toBeUndefined();
+    });
+
+    it('lets an element override ONE property while the rest follow the role', () => {
+      const resolved = resolveTextStyle({ fontSize: '3em' }, role);
+
+      expect(resolved.fontSize).toBe('3em'); // overridden
+      expect(resolved.fontFamily).toBe('Lato'); // still from role
+      expect(resolved.fontWeight).toBe('700'); // still from role
+      expect(resolved.color).toBeUndefined(); // ADR-0020: role colour does not cascade
+    });
+
+    it('treats an empty-string override as unset (falls back to the role)', () => {
+      const resolved = resolveTextStyle({ fontSize: '' }, role);
+
+      expect(resolved.fontSize).toBe('2em');
+    });
+
+    it("keeps a '0' letter-spacing override (truthy string)", () => {
+      const resolved = resolveTextStyle(
+        { letterSpacing: '0' },
+        { ...role, letterSpacing: '0.1em' },
+      );
+
+      expect(resolved.letterSpacing).toBe('0');
+    });
+
+    it('never resolves textAlign (alignment is section-level, not a role prop)', () => {
+      const resolved = resolveTextStyle(
+        { textAlign: 'left' } as never,
+        role,
+      ) as Record<string, unknown>;
+
+      expect(resolved.textAlign).toBeUndefined();
+    });
+
+    it('applies the container fallback colour (the only rung below the element now)', () => {
+      const resolved = resolveTextStyle({}, role, 'contrastWhite');
+
+      expect(resolved.color).toBe('contrastWhite');
+    });
+
+    it('composes a local strike with the linked role underline', () => {
+      const resolved = resolveTextStyle(
+        { textDecoration: 'line-through' },
+        { textDecoration: 'underline' },
+      );
+
+      expect(resolved.textDecoration).toBe('underline line-through');
+    });
+  });
+
+  describe('text-decoration composition', () => {
+    it.each([
+      ['underline', 'line-through', 'underline line-through'],
+      ['line-through', 'underline', 'underline line-through'],
+      ['underline line-through', 'underline', 'underline line-through'],
+      ['underline', 'none', 'none'],
+      ['underline', 'none line-through', 'line-through'],
+      ['underline', undefined, 'underline'],
+      [undefined, 'line-through', 'line-through'],
+    ])('composes role %s with local %s as %s', (role, local, expected) => {
+      expect(composeTextDecoration(role, local)).toBe(expected);
+    });
+
+    it('ignores a reset marker when the run has no lines of its own', () => {
+      expect(composeTextDecoration('underline', undefined, true)).toBe(
+        'underline',
+      );
+      expect(
+        composeTextDecoration('underline', 'var(--role-text-decoration)', true),
+      ).toBe('underline');
+      expect(
+        rteTextDecorationClassName('var(--role-text-decoration)', true),
+      ).toBe('bp-rte-text-decoration-inherit');
+    });
+
+    it('maps the persisted line set to the rendered class without changing the value', () => {
+      expect(rteTextDecorationClassName('line-through')).toBe(
+        'bp-rte-text-decoration-linethrough',
+      );
+      expect(rteTextDecorationClassName('var(--role-text-decoration)')).toBe(
+        'bp-rte-text-decoration-inherit',
+      );
+      expect(rteTextDecorationClassName('none line-through')).toBe(
+        'bp-rte-text-decoration-reset-linethrough',
+      );
+      expect(rteTextDecorationClassName('line-through', true)).toBe(
+        'bp-rte-text-decoration-reset-linethrough',
+      );
+    });
+  });
+
+  describe('overrideTypographyStyle (render-time strip, BP-5969 Option B)', () => {
+    const role = {
+      fontFamily: 'Lato',
+      fontSize: '2em',
+      fontWeight: '700',
+      lineHeight: '1.2',
+    };
+
+    it('emits only the props that differ from the role (rest come from the class)', () => {
+      const resolved = { ...role, fontSize: '3em' };
+
+      expect(overrideTypographyStyle(resolved, role)).toEqual({
+        fontSize: '3em',
+      });
+    });
+
+    it('emits nothing when every prop equals the role (fully class-driven)', () => {
+      expect(overrideTypographyStyle({ ...role }, role)).toEqual({});
+    });
+
+    it('never emits colour (colour is not in the class)', () => {
+      const resolved = { ...role, color: 'red' } as Record<string, string>;
+
+      expect(overrideTypographyStyle(resolved, role)).not.toHaveProperty(
+        'color',
+      );
+    });
+
+    it('falls back to the full resolved typography when the role is not in scope', () => {
+      const resolved = {
+        fontFamily: 'Lato',
+        fontSize: '2em',
+        lineHeight: '1.2',
+        color: 'red',
+      } as Record<string, string>;
+
+      expect(overrideTypographyStyle(resolved, undefined)).toEqual({
+        fontFamily: 'Lato',
+        fontSize: '2em',
+        lineHeight: '1.2',
+      });
+    });
+
+    it('treats empty-string / null as unset but keeps a 0 letter-spacing override', () => {
+      const resolved = {
+        fontSize: '',
+        letterSpacing: '0',
+      } as Record<string, string>;
+
+      expect(
+        overrideTypographyStyle(resolved, { letterSpacing: '0.1em' }),
+      ).toEqual({ letterSpacing: '0' });
+    });
+  });
+
+  describe('normalizeTextStyleAgainstRole (write-side sparse override — ADR-0019)', () => {
+    const OPTIONS = {
+      heading1: {
+        style: { fontSize: '2.5em', fontFamily: 'Lato', fontWeight: '700' },
+      },
+    } as unknown as TextStyleOptions;
+
+    it('drops a prop equal to the role, keeps a differing prop, leaves colour alone', () => {
+      expect(
+        normalizeTextStyleAgainstRole(
+          {
+            textStyleType: 'heading1',
+            fontSize: '2.5em', // === role → dropped
+            fontFamily: 'Georgia', // !== role → kept
+            color: 'red', // not a cascade prop → kept
+          },
+          OPTIONS,
+        ),
+      ).toEqual({
+        textStyleType: 'heading1',
+        fontFamily: 'Georgia',
+        color: 'red',
+      });
+    });
+
+    it('leaves alignment and applyAutoScale untouched', () => {
+      expect(
+        normalizeTextStyleAgainstRole(
+          {
+            textStyleType: 'heading1',
+            textAlign: 'center',
+            applyAutoScale: true,
+            fontSize: '2.5em',
+          },
+          OPTIONS,
+        ),
+      ).toEqual({
+        textStyleType: 'heading1',
+        textAlign: 'center',
+        applyAutoScale: true,
+      });
+    });
+
+    it('keeps a neutral that turns off a role style, drops one the role already renders', () => {
+      const options = {
+        heading1: {
+          style: {
+            fontWeight: 'bold',
+            fontStyle: 'italic',
+            textDecoration: 'underline',
+          },
+        },
+        heading2: { style: { fontWeight: 'normal', textDecoration: '' } },
+      } as unknown as TextStyleOptions;
+      const off = {
+        fontWeight: 'normal',
+        fontStyle: 'normal',
+        textDecoration: 'none',
+      };
+
+      expect(
+        normalizeTextStyleAgainstRole(
+          { textStyleType: 'heading1', ...off },
+          options,
+        ),
+      ).toEqual({ textStyleType: 'heading1', ...off });
+      expect(
+        normalizeTextStyleAgainstRole(
+          { textStyleType: 'heading2', ...off },
+          options,
+        ),
+      ).toEqual({ textStyleType: 'heading2' });
+    });
+
+    it('drops an empty value (the resolver falls it through to the role)', () => {
+      expect(
+        normalizeTextStyleAgainstRole(
+          { textStyleType: 'heading1', fontFamily: '', textDecoration: '' },
+          OPTIONS,
+        ),
+      ).toEqual({ textStyleType: 'heading1' });
+    });
+
+    it('drops a zero letter-spacing slider value when the role stores zero', () => {
+      const options = {
+        heading1: { style: { letterSpacing: '0' } },
+      } as unknown as TextStyleOptions;
+
+      expect(
+        normalizeTextStyleAgainstRole(
+          { textStyleType: 'heading1', letterSpacing: '0em' },
+          options,
+        ),
+      ).toEqual({ textStyleType: 'heading1' });
+    });
+
+    it('is a no-op for a legacy/unlinked role (no page-scoped class to fall back on)', () => {
+      const style = { textStyleType: 'titles', fontSize: '2.5em' };
+
+      expect(normalizeTextStyleAgainstRole(style, OPTIONS)).toEqual(style);
+    });
+
+    it('is a no-op when the role table is absent', () => {
+      const style = { textStyleType: 'heading1', fontSize: '2.5em' };
+
+      expect(normalizeTextStyleAgainstRole(style, undefined)).toEqual(style);
+    });
+
+    it('passes a non-style value through unchanged', () => {
+      expect(normalizeTextStyleAgainstRole(undefined, OPTIONS)).toBeUndefined();
+    });
+  });
+});

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

@@ -1,41 +1,215 @@
 /**
  * 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 {
+  CANONICAL_TEXT_STYLE_TYPES,
+  type TextStyleOptions,
+} from '../models/styles.model';
+import {
+  type CascadeTypographyProp,
+  composeTextDecoration,
+  NEUTRAL_TYPOGRAPHY_VALUE,
+  TEXT_STYLE_CASCADE_PROPS,
+} 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 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.
+ * `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 const resolveTextColor = (
   elementStyle: ColouredStyle | undefined,
-  globalStyle: ColouredStyle | undefined,
   fallbackBeforeGlobal?: string,
-): string | undefined =>
-  elementStyle?.color || fallbackBeforeGlobal || globalStyle?.color;
+): string | undefined => elementStyle?.color || fallbackBeforeGlobal;
+
+/**
+ * BP-5969 — the per-property text-style cascade (ADR-0019). Supersedes the old
+ * all-or-nothing rule (where a linked element took ALL typography from the role and
+ * only colour cascaded). Every typography property now resolves independently:
+ * `element[prop] ?? role[prop]`, so an element can override one property and keep the
+ * rest following its role. Empty-string is treated as unset (`||`, matching
+ * `resolveTextColor`) — a cleared field falls back to the role, and `'0'`
+ * (a valid letter-spacing) stays truthy.
+ *
+ * Colour keeps its own three-rung cascade via `resolveTextColor` (with the optional
+ * container `fallbackBeforeGlobal` middle rung). Alignment is deliberately absent —
+ * it is section-level, never a role property, and must not be resolved here.
+ */
+/**
+ * What the role CSS emits for a prop the role leaves unset. Props a role always defines (family /
+ * size / line-height) have none.
+ */
+const isUnsetTypography = (value: unknown): boolean =>
+  value === undefined || value === null || value === '';
+
+// An unset role prop renders as its neutral, so `fontStyle: 'normal'` under a role with no
+// fontStyle is role-equal; under an italic role it is the override that turns italic off.
+const effectiveRoleValue = (
+  prop: CascadeTypographyProp,
+  value: unknown,
+): unknown =>
+  isUnsetTypography(value) ? NEUTRAL_TYPOGRAPHY_VALUE[prop] : value;
+
+const isZeroLetterSpacing = (value: unknown): boolean =>
+  typeof value === 'string' && /^[+-]?0(?:\.0+)?(?:em|rem|px)?$/.test(value);
+
+const typographyValuesMatch = (
+  prop: CascadeTypographyProp,
+  value: unknown,
+  roleValue: unknown,
+): boolean =>
+  value === roleValue ||
+  (prop === 'letterSpacing' &&
+    isZeroLetterSpacing(value) &&
+    isZeroLetterSpacing(roleValue));
+
+/**
+ * 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 const normalizeTextStyleAgainstRole = <T>(
+  value: T,
+  textStyleOptions: TextStyleOptions | undefined,
+): T => {
+  const style = value as Record<string, unknown> | null | undefined;
+  const type = style?.textStyleType as string | undefined;
+
+  if (
+    !style ||
+    typeof style !== 'object' ||
+    !type ||
+    !(CANONICAL_TEXT_STYLE_TYPES as readonly string[]).includes(type)
+  ) {
+    return value;
+  }
+
+  const role = textStyleOptions?.[type as keyof TextStyleOptions]?.style as
+    | Record<string, unknown>
+    | undefined;
+
+  if (!role) return value;
+
+  const normalized: Record<string, unknown> = { ...style };
+
+  for (const prop of TEXT_STYLE_CASCADE_PROPS) {
+    if (!(prop in normalized)) continue;
+
+    // An empty value is no override either: the resolver falls it through to the role.
+    if (
+      isUnsetTypography(normalized[prop]) ||
+      typographyValuesMatch(
+        prop,
+        effectiveRoleValue(prop, normalized[prop]),
+        effectiveRoleValue(prop, role[prop]),
+      )
+    ) {
+      delete normalized[prop];
+    }
+  }
+
+  return normalized as T;
+};
+
+type TypographyStyle = Partial<
+  Record<CascadeTypographyProp, string | undefined>
+> &
+  ColouredStyle;
+
+export const resolveTextStyle = <
+  R extends TypographyStyle,
+  E extends TypographyStyle,
+>(
+  elementStyle: E | undefined,
+  roleStyle: R | undefined,
+  fallbackBeforeGlobal?: string,
+): TypographyStyle => {
+  const resolved: TypographyStyle = {};
+
+  for (const prop of TEXT_STYLE_CASCADE_PROPS) {
+    resolved[prop] =
+      prop === 'textDecoration'
+        ? composeTextDecoration(roleStyle?.[prop], elementStyle?.[prop])
+        : elementStyle?.[prop] || roleStyle?.[prop];
+  }
+
+  resolved.color = resolveTextColor(elementStyle, fallbackBeforeGlobal);
+
+  return resolved;
+};
+
+/**
+ * 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.
+ *
+ * Empty-string / null are treated as unset (matching the `||` in the resolvers), and
+ * `'0'` (a valid letter-spacing) stays.
+ */
+export const overrideTypographyStyle = (
+  resolvedStyle: TypographyStyle | undefined,
+  roleStyle: TypographyStyle | undefined,
+): Partial<Record<CascadeTypographyProp, string>> => {
+  const overrides: Partial<Record<CascadeTypographyProp, string>> = {};
+
+  for (const prop of TEXT_STYLE_CASCADE_PROPS) {
+    const value = resolvedStyle?.[prop];
+
+    if (value === undefined || value === null || value === '') continue;
+
+    if (roleStyle && value === roleStyle[prop]) continue; // the class supplies it
+
+    overrides[prop] = value;
+  }
+
+  return overrides;
+};