@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/src/metadata-builder/builders/global-role-propagation.ts

@@ -0,0 +1,430 @@
+import type { JSONContent } from '@tiptap/vue-3';
+import type {
+  BrandPageModel,
+  TextStyleDeclaration,
+} from '../../brand-page/models';
+import { CANONICAL_TEXT_STYLE_TYPES } from '../../brand-page/models/styles.model';
+import type {
+  CanonicalTextStyleType,
+  TextStyleOptions,
+} from '../../brand-page/models/styles.model';
+import {
+  NEUTRAL_TYPOGRAPHY_VALUE,
+  roleVarRef,
+  textDecorationFlags,
+} from '@shared/text-role-typography.util';
+import {
+  hasRTEContent,
+  getPlainTextFromRTE,
+  withoutTypographyMarks,
+} from '../../brand-page-maker/utils';
+import { useExternalRichTextEditor } from '../../brand-page-maker/composables/rich-text-editor/useRichTextEditor';
+import { applyStyleToRTEText } from '../helpers/rte.helpers';
+import { isTiptapDocument } from '../parsers/section-tool-arguments';
+import type { TextStyleOptionStyle } from '../parsers/ai-toolcall-parser';
+
+/**
+ * Propagation of an AI site-wide text-role change into existing content (R12).
+ *
+ * `tool_update_global_styles` changes a role's own definition — but a run whose
+ * typography was baked as a literal (an inline RTE mark, or a detached `*Style`
+ * override) does not follow that change: the literal wins over the role's CSS
+ * class at render (ADR-0019). This module walks every page's contents, the
+ * header and the footer and relinks every literal of a CHANGED role+property to
+ * the role's `var(--role-…)` reference, so the change reaches content the pipeline
+ * never re-sends. Unlike the maker's own "apply changes to all" (which only
+ * relinks a literal that already EQUALS the role — genuine overrides are left
+ * alone, ADR-0021), an AI site-wide ask relinks EVERY literal, accent words
+ * included; the one exception is a run or plain field the user named in
+ * `textStyles.keepRuns` (R16).
+ *
+ * All 7 role typography properties relink. Family, size, line height and letter
+ * spacing relink only when the sent value differs from the stored role: the
+ * pipeline re-sends them unchanged, and relinking then would erase accents.
+ * Weight, style and decoration relink on ANY sent value: the pipeline sends them
+ * only when the user asked, and migration-22 pinned literals (`fontWeight:
+ * 'normal'` under a bold heading role) that an equal value must still reach.
+ * They also drop the legacy `<strong>`/`<em>`/`<u>`/`<s>` marks that would win
+ * over the ref; a link keeps its underline.
+ *
+ * Both migrated Tiptap JSON and legacy HTML strings are handled because older sites can still
+ * carry the latter; leaving either shape unchanged would make role edits surface-dependent.
+ *
+ * A field's role comes from its own `textStyleType` — never guessed from the
+ * field name. Every field the metadata-builder touches carries a canonical role
+ * post-migration (the legacy→canonical gate is a hard one, `legacy-migrations.md`),
+ * so no detached/legacy fallback is needed here.
+ */
+
+/** The 7 role typography properties (ROLE_VAR_ATTRS) a site-wide change relinks. */
+export const ROLE_PROPAGATION_ATTRS = [
+  'fontFamily',
+  'fontSize',
+  'lineHeight',
+  'letterSpacing',
+  'fontWeight',
+  'fontStyle',
+  'textDecoration',
+] as const;
+
+export type RolePropagationAttr = (typeof ROLE_PROPAGATION_ATTRS)[number];
+
+export const ROLE_VAR_REF = Object.fromEntries(
+  ROLE_PROPAGATION_ATTRS.map((attr) => [attr, roleVarRef(attr)]),
+) as Readonly<Record<RolePropagationAttr, string>>;
+
+// Relink on any sent value, even one equal to the stored role (see the header).
+const EMPHASIS_ATTRS: ReadonlySet<RolePropagationAttr> = new Set([
+  'fontWeight',
+  'fontStyle',
+  'textDecoration',
+]);
+
+export type ChangedRoleProps = Partial<
+  Record<CanonicalTextStyleType, Partial<Record<RolePropagationAttr, string>>>
+>;
+
+const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === 'object' && !Array.isArray(v);
+
+const isCanonicalRole = (v: unknown): v is CanonicalTextStyleType =>
+  typeof v === 'string' &&
+  (CANONICAL_TEXT_STYLE_TYPES as readonly string[]).includes(v);
+
+const isKeptText = (
+  text: string,
+  keepRuns: readonly string[] | undefined,
+): boolean => {
+  if (!keepRuns?.length) return false;
+
+  const trimmed = text.trim().toLowerCase();
+
+  return keepRuns.some((run) => run.trim().toLowerCase() === trimmed);
+};
+
+const normalizedRoleValue = (
+  value: unknown,
+  attr: RolePropagationAttr,
+): string | undefined => {
+  if (typeof value === 'string' && value.trim()) return value.trim();
+
+  return Object.prototype.hasOwnProperty.call(NEUTRAL_TYPOGRAPHY_VALUE, attr)
+    ? NEUTRAL_TYPOGRAPHY_VALUE[attr as keyof typeof NEUTRAL_TYPOGRAPHY_VALUE]
+    : undefined;
+};
+
+// One value can be written several ways ('3.0em' / '3em', a quoted family). Comparing the
+// written form would read an unchanged value as a change and relink every word that overrides it.
+const comparableValue = (attr: RolePropagationAttr, value: string): string => {
+  if (attr === 'fontFamily') return value.replace(/['"]/g, '').trim();
+
+  const numeric = /^(-?(?:\d+\.?\d*|\.\d+))([a-z%]*)$/i.exec(value);
+
+  return numeric
+    ? `${Number(numeric[1])}${numeric[2].toLowerCase()}`
+    : value.toLowerCase();
+};
+
+/**
+ * Extract the changed canonical roles + properties from a RESOLVED (canonical-only)
+ * `textStyleOptions` merge — the caller (`GlobalStylesBuilder`) has already redirected any
+ * retired key onto its successor role(s) (R7) before calling this.
+ */
+export const collectChangedRoleProps = (
+  textStyleOptions:
+    | Partial<Record<CanonicalTextStyleType, { style?: TextStyleOptionStyle }>>
+    | undefined,
+  existingOptions: TextStyleOptions = {} as TextStyleOptions,
+): ChangedRoleProps => {
+  const changed: ChangedRoleProps = {};
+
+  if (!textStyleOptions) return changed;
+
+  for (const role of CANONICAL_TEXT_STYLE_TYPES) {
+    const style = textStyleOptions[role]?.style;
+
+    if (!style) continue;
+
+    const props: Partial<Record<RolePropagationAttr, string>> = {};
+    const existing = existingOptions[role]?.style as unknown as
+      | Record<string, unknown>
+      | undefined;
+
+    for (const attr of ROLE_PROPAGATION_ATTRS) {
+      const value = style[attr];
+      const replacement =
+        typeof value === 'string' && value.trim()
+          ? value.trim()
+          : (value === null || value === '') &&
+              Object.prototype.hasOwnProperty.call(
+                NEUTRAL_TYPOGRAPHY_VALUE,
+                attr,
+              )
+            ? NEUTRAL_TYPOGRAPHY_VALUE[
+                attr as keyof typeof NEUTRAL_TYPOGRAPHY_VALUE
+              ]
+            : undefined;
+
+      if (replacement === undefined) continue;
+
+      if (EMPHASIS_ATTRS.has(attr)) {
+        props[attr] = replacement;
+        continue;
+      }
+
+      const stored = normalizedRoleValue(existing?.[attr], attr);
+
+      if (
+        stored === undefined ||
+        comparableValue(attr, replacement) !== comparableValue(attr, stored)
+      ) {
+        props[attr] = replacement;
+      }
+    }
+
+    if (Object.keys(props).length) changed[role] = props;
+  }
+
+  return changed;
+};
+
+type RteRunNode = {
+  type?: string;
+  text?: string;
+  marks?: { type: string; attrs?: Record<string, unknown> }[];
+  content?: RteRunNode[];
+};
+
+/**
+ * Force every literal of a changed attr on every run to its role ref, accent words included, and
+ * drop the legacy marks that compete with it. A ref already in place is left alone ("refs stay");
+ * a run named in `keepRuns` is untouched.
+ */
+export const relinkRoleChangedMarks = (
+  doc: JSONContent,
+  changedAttrs: readonly RolePropagationAttr[],
+  keepRuns: readonly string[] | undefined,
+): JSONContent => {
+  const clone = JSON.parse(JSON.stringify(doc)) as RteRunNode;
+  const decorationChanged = changedAttrs.includes('textDecoration');
+
+  const visit = (node: RteRunNode): void => {
+    if (node.type === 'text' && node.text && !isKeptText(node.text, keepRuns)) {
+      const mark = node.marks?.find((m) => m.type === 'textStyle');
+      const isLink = !!node.marks?.some((m) => m.type === 'link');
+      // Migration-22 folded a link's `<u>` into this literal; relinking it must keep the link's look.
+      const keepsLinkUnderline =
+        isLink &&
+        decorationChanged &&
+        textDecorationFlags(
+          mark?.attrs?.textDecoration as string | undefined,
+        ).has('underline');
+
+      changedAttrs.forEach((attr) => {
+        const value = mark?.attrs?.[attr];
+
+        if (
+          typeof value === 'string' &&
+          value &&
+          value !== ROLE_VAR_REF[attr]
+        ) {
+          mark!.attrs![attr] = ROLE_VAR_REF[attr];
+        }
+      });
+
+      if (decorationChanged) delete mark?.attrs?.textDecorationReset;
+
+      if (node.marks) {
+        node.marks = withoutTypographyMarks(node.marks, changedAttrs, isLink);
+
+        if (
+          keepsLinkUnderline &&
+          !node.marks.some((m) => m.type === 'underline')
+        ) {
+          node.marks.push({ type: 'underline' });
+        }
+      }
+    }
+
+    node.content?.forEach(visit);
+  };
+
+  visit(clone);
+
+  return clone as JSONContent;
+};
+
+/** Rewrites a legacy RTE HTML string's marks to the given role refs. Injectable for tests. */
+export type ApplyRoleRefsToRTE = (
+  html: string,
+  refs: Partial<Record<RolePropagationAttr, string>>,
+  keepRuns?: readonly string[],
+) => string;
+
+const dropStyleOverrides = (
+  style: Record<string, unknown>,
+  changedAttrs: readonly RolePropagationAttr[],
+): void => {
+  changedAttrs.forEach((attr) => {
+    if (attr in style) delete style[attr];
+  });
+};
+
+const refsFor = (
+  changedAttrs: readonly RolePropagationAttr[],
+): Partial<Record<RolePropagationAttr, string>> =>
+  Object.fromEntries(changedAttrs.map((attr) => [attr, ROLE_VAR_REF[attr]]));
+
+const walkRecord = (
+  record: Record<string, unknown>,
+  changed: ChangedRoleProps,
+  keepRuns: readonly string[] | undefined,
+  applyRefs: ApplyRoleRefsToRTE,
+): void => {
+  for (const [key, value] of Object.entries(record)) {
+    let handled = false;
+
+    if (key.endsWith('Style') && isPlainObject(value)) {
+      const role = value.textStyleType;
+
+      if (isCanonicalRole(role) && changed[role]) {
+        handled = true;
+
+        const changedAttrs = Object.keys(
+          changed[role]!,
+        ) as RolePropagationAttr[];
+
+        if (
+          key === 'defaultButtonStyle' &&
+          isPlainObject(record.selectedButtonStyle)
+        ) {
+          dropStyleOverrides(
+            record.selectedButtonStyle as Record<string, unknown>,
+            changedAttrs,
+          );
+        }
+
+        const fieldBase = key.slice(0, -'Style'.length);
+        const textKey =
+          fieldBase in record
+            ? fieldBase
+            : `${fieldBase}Text` in record
+              ? `${fieldBase}Text`
+              : undefined;
+        const textValue = textKey ? record[textKey] : undefined;
+
+        if (isTiptapDocument(textValue)) {
+          record[textKey!] = relinkRoleChangedMarks(
+            textValue,
+            changedAttrs,
+            keepRuns,
+          );
+          dropStyleOverrides(value, changedAttrs);
+        } else if (typeof textValue === 'string' && hasRTEContent(textValue)) {
+          if (!isKeptText(getPlainTextFromRTE(textValue), keepRuns)) {
+            record[textKey!] = applyRefs(
+              textValue,
+              refsFor(changedAttrs),
+              keepRuns,
+            );
+            dropStyleOverrides(value, changedAttrs);
+          }
+        } else {
+          const plainText =
+            typeof textValue === 'string' ? textValue : undefined;
+
+          if (plainText === undefined || !isKeptText(plainText, keepRuns)) {
+            dropStyleOverrides(value, changedAttrs);
+          }
+        }
+      }
+    }
+
+    if (handled) continue;
+
+    if (Array.isArray(value)) {
+      value.forEach(
+        (item) =>
+          isPlainObject(item) && walkRecord(item, changed, keepRuns, applyRefs),
+      );
+    } else if (isPlainObject(value)) {
+      walkRecord(value, changed, keepRuns, applyRefs);
+    }
+  }
+};
+
+export const propagateRolePropsToContents = (
+  model: BrandPageModel,
+  changed: ChangedRoleProps,
+  keepRuns?: readonly string[],
+  applyRefs?: ApplyRoleRefsToRTE,
+): void => {
+  if (!Object.keys(changed).length) return;
+
+  let editor:
+    | ReturnType<typeof useExternalRichTextEditor>['externalEditor']
+    | undefined;
+  const apply: ApplyRoleRefsToRTE =
+    applyRefs ??
+    ((text, refs) => {
+      editor = editor ?? useExternalRichTextEditor().externalEditor;
+
+      return applyStyleToRTEText(
+        editor,
+        text,
+        refs as TextStyleDeclaration,
+        keepRuns,
+      );
+    });
+
+  try {
+    for (const page of model.pages) {
+      for (const content of page.contents) {
+        walkRecord(
+          content as unknown as Record<string, unknown>,
+          changed,
+          keepRuns,
+          apply,
+        );
+      }
+    }
+
+    if (model.pageHeaderDesktop) {
+      walkRecord(
+        model.pageHeaderDesktop as unknown as Record<string, unknown>,
+        changed,
+        keepRuns,
+        apply,
+      );
+    }
+
+    if (model.pageHeaderMobile) {
+      walkRecord(
+        model.pageHeaderMobile as unknown as Record<string, unknown>,
+        changed,
+        keepRuns,
+        apply,
+      );
+    }
+
+    if (model.pageFooterDesktop) {
+      walkRecord(
+        model.pageFooterDesktop as unknown as Record<string, unknown>,
+        changed,
+        keepRuns,
+        apply,
+      );
+    }
+
+    if (model.pageFooterMobile) {
+      walkRecord(
+        model.pageFooterMobile as unknown as Record<string, unknown>,
+        changed,
+        keepRuns,
+        apply,
+      );
+    }
+  } finally {
+    editor?.destroy();
+  }
+};