@designcrowd/library.brand-page 6.2.11 → 6.2.12

package/src/brand-page-maker/utils/rte-clipboard.util.ts

@@ -0,0 +1,473 @@
+import { getSchema } from '@tiptap/core';
+import type { JSONContent } from '@tiptap/vue-3';
+import { Slice } from 'prosemirror-model';
+import type { Schema } from 'prosemirror-model';
+import type {
+  ColorItem,
+  GlobalTextStyleDeclaration,
+  TextStyleDeclaration,
+} from '@brand-page';
+import {
+  canonicalSolidHex,
+  isBlankColorValue,
+  isPaletteRoleId,
+  paletteRoleIdForToken,
+  resolveColorReference,
+  roleIdsByCanonicalValue,
+  toColorVarReference,
+} from '@brand-page/utils/color-palette.util';
+import {
+  ROLE_VAR_ATTRS,
+  roleVarRef,
+  runTypographyFillValue,
+  type RoleVarMarkAttr,
+  NEUTRAL_TYPOGRAPHY_VALUE,
+} from '@shared/text-role-typography.util';
+import { DEFAULT_LINK_COLOR } from '@src/constants/rich-text-editor.constants';
+import { isRoleVarRef, normTypographyValue } from './rich-text-editor.util';
+import { sanitizeRteJson } from './rte-sanitize.util';
+import { emToPx } from './text.util';
+import { getRteExtensions } from '@shared/rte-extensions.util';
+
+/**
+ * Pure transforms for the maker RTE's copy, cut and paste. No editor, no DOM: every
+ * function here takes and returns Tiptap JSON (or a bare value), so `RteClipboard.ts`
+ * can call them from real clipboard events without this module knowing ProseMirror's
+ * live `Node`/`Mark` instances exist. Kept off the `brand-page-maker/utils` barrel
+ * (imported by path) — see `rich-text-editor.md` *Entry points* for why it stays out
+ * of `getRteExtensions`.
+ */
+
+export const RTE_CLIPBOARD_MIME_TYPE = 'application/x-rte-slice';
+export const RTE_CLIPBOARD_VERSION = 1 as const;
+
+export interface RteClipboardContext {
+  /** The field's canonical role style, or undefined for a legacy/unlinked field. */
+  role: GlobalTextStyleDeclaration | undefined;
+  /** The field's own style object (whole-field overrides, colour, alignment). */
+  block: TextStyleDeclaration | undefined;
+  /** The site palette, for resolving and relinking colour references. */
+  colors: ColorItem[];
+}
+
+export type ResolvedRunStyle = Partial<Record<RoleVarMarkAttr, string>> & {
+  color?: string;
+};
+
+export interface RteClipboardSliceJSON {
+  content: JSONContent[];
+  openStart?: number;
+  openEnd?: number;
+}
+
+export interface RteClipboardPayload {
+  v: typeof RTE_CLIPBOARD_VERSION;
+  slice: RteClipboardSliceJSON;
+}
+
+type RteRunMark = { type: string; attrs?: Record<string, unknown> };
+
+type RteRunNode = { marks?: RteRunMark[] };
+
+/**
+ * The JSON-node twin of `runTypography` (`rich-text-editor.util.ts`): a run's own
+ * typography, falling back to a legacy semantic mark for un-migrated/pasted runs. Works
+ * on a Tiptap JSON node directly (no schema needed), because a copy/paste payload is
+ * JSON — never a live ProseMirror `Node` — end to end.
+ */
+const runTypographyFromJson = (
+  node: RteRunNode,
+): Partial<Record<RoleVarMarkAttr, string>> => {
+  const marks = node.marks ?? [];
+  const textStyle = marks.find((mark) => mark.type === 'textStyle');
+  const attrOf = (attr: string): string | undefined => {
+    const value = textStyle?.attrs?.[attr];
+
+    return typeof value === 'string' && value !== '' ? value : undefined;
+  };
+  const has = (markType: string): boolean =>
+    marks.some((mark) => mark.type === markType);
+  const legacyDecoration =
+    [has('underline') && 'underline', has('strike') && 'line-through']
+      .filter(Boolean)
+      .join(' ') || undefined;
+
+  return {
+    fontFamily: attrOf('fontFamily'),
+    fontSize: attrOf('fontSize'),
+    lineHeight: attrOf('lineHeight'),
+    letterSpacing: attrOf('letterSpacing'),
+    fontWeight: attrOf('fontWeight') ?? (has('bold') ? 'bold' : undefined),
+    fontStyle: attrOf('fontStyle') ?? (has('italic') ? 'italic' : undefined),
+    textDecoration: attrOf('textDecoration') ?? legacyDecoration,
+  };
+};
+
+/**
+ * Resolve one typography attr the way the canvas renders it: the run's own value
+ * (a role ref resolved to the source role's value, or its neutral; a literal — including
+ * a legacy bold/italic/underline/strike mark — kept as written), else, for an attr the
+ * run doesn't carry, `runTypographyFillValue`'s whole-field fill, resolved the same way.
+ * Never invents a value the canvas wouldn't show (D2).
+ */
+const resolveTypographyAttrForCopy = (
+  attr: RoleVarMarkAttr,
+  own: string | undefined,
+  role: GlobalTextStyleDeclaration | undefined,
+  block: TextStyleDeclaration | undefined,
+): string | undefined => {
+  const value =
+    own !== undefined
+      ? own
+      : runTypographyFillValue(
+          attr,
+          role as Partial<Record<RoleVarMarkAttr, string>> | undefined,
+          block as Partial<Record<RoleVarMarkAttr, string>> | undefined,
+        );
+
+  if (value === undefined) return undefined;
+
+  const resolved = isRoleVarRef(value)
+    ? (role?.[attr] ?? NEUTRAL_TYPOGRAPHY_VALUE[attr])
+    : value;
+
+  // A quoted family (`"Playfair Display"`, or a stack like `"Playfair Display", serif`)
+  // fails sanitizeRteJson's safe-CSS-value check and is dropped outright, not kept
+  // quoted — so strip every quote, not just an outer pair, rather than lose it.
+  return attr === 'fontFamily' ? resolved?.replace(/['"]+/g, '') : resolved;
+};
+
+/**
+ * Resolve a colour value (text or highlight) to what the canvas shows, in one
+ * normalised form: a legacy `logo-*` token maps to its palette role first; a
+ * `var(--id)` reference resolves against `colors` (a blank role reads as its default);
+ * a resolvable solid canonicalises to lowercase `#rrggbb`/`#rrggbbaa`. A reference the
+ * palette doesn't hold stays exactly as written (D3) — copy never invents a look the
+ * canvas doesn't have.
+ */
+export const resolveRunColorForCopy = (
+  value: string | undefined,
+  colors: ColorItem[],
+): string | undefined => {
+  if (!value) return undefined;
+
+  const roleId = paletteRoleIdForToken(value);
+  const ref = roleId ? toColorVarReference(roleId) : value;
+  const resolved = resolveColorReference(ref, colors, {
+    withRoleDefaults: true,
+  });
+
+  return canonicalSolidHex(resolved) ?? resolved;
+};
+
+/**
+ * A run's typography and colour, resolved to what the canvas shows (A5): every role
+ * reference becomes a literal value, so the slice carries "what it looks like" rather
+ * than "what it's linked to" — the destination decides what re-links (see
+ * `relinkRunTypographyToRole`). An uncoloured run stays uncoloured (ADR-0020: no base
+ * coat) — colour has no whole-field fallback, unlike typography.
+ */
+export const resolveRunStyleForCopy = (
+  node: RteRunNode,
+  context: RteClipboardContext,
+): ResolvedRunStyle => {
+  const own = runTypographyFromJson(node);
+  const style: ResolvedRunStyle = {};
+
+  for (const { markAttr } of ROLE_VAR_ATTRS) {
+    const value = resolveTypographyAttrForCopy(
+      markAttr,
+      own[markAttr],
+      context.role,
+      context.block,
+    );
+
+    if (value !== undefined) style[markAttr] = value;
+  }
+
+  const textStyle = node.marks?.find((mark) => mark.type === 'textStyle');
+  const color = resolveRunColorForCopy(
+    textStyle?.attrs?.color as string | undefined,
+    context.colors,
+  );
+
+  if (color !== undefined) style.color = color;
+
+  return style;
+};
+
+/**
+ * The external (`text/html`, other apps) reading of a run: the same resolved look, with
+ * `fontSize` converted from em to px at the 16px root (the toolbar's own readout) so an
+ * app with no `--role-*`/em context still shows the right size, and the run's link href
+ * (if any) carried through untouched.
+ */
+export const resolveRunStyleForExternal = (
+  node: RteRunNode,
+  context: RteClipboardContext,
+): ResolvedRunStyle & { href?: string } => {
+  const style = resolveRunStyleForCopy(node, context);
+  const link = (node.marks ?? []).find((mark) => mark.type === 'link');
+  const href = link?.attrs?.href as string | undefined;
+  const fontSizePx = sizeToPx(style.fontSize);
+
+  return {
+    ...style,
+    ...(fontSizePx !== undefined ? { fontSize: `${fontSizePx}px` } : {}),
+    ...(href ? { href } : {}),
+  };
+};
+
+const SIZE_UNIT = /^(-?[\d.]+)(px|em)$/;
+
+/** A typography value's px size at the 16px root, or undefined for anything else. */
+const sizeToPx = (value: string | undefined): number | undefined => {
+  const match = value?.trim().match(SIZE_UNIT);
+
+  if (!match) return undefined;
+
+  const [, amount, unit] = match;
+
+  return unit === 'px' ? parseFloat(amount) : parseFloat(emToPx(`${amount}em`));
+};
+
+/**
+ * "Same value written differently" (A6): family ignores quoting, weight/style/
+ * decoration/spacing treat their CSS-neutral keyword as equal to unset, and — local to
+ * this comparator, so the asterisk and relink paths don't widen — `fontSize` compares
+ * as px at the 16px root, so `1.375em` and `22px` are one size.
+ */
+export const isSameTypographyValue = (
+  attr: RoleVarMarkAttr,
+  a: string | undefined,
+  b: string | undefined,
+): boolean => {
+  if (attr === 'fontSize') {
+    const pxA = sizeToPx(a);
+
+    return pxA !== undefined && pxA === sizeToPx(b);
+  }
+
+  return normTypographyValue(attr, a) === normTypographyValue(attr, b);
+};
+
+/**
+ * Relink a resolved run to the destination role (A5 step 2, R2): a value equal to the
+ * destination's (or its neutral) becomes the role var, so it keeps following that role;
+ * any other value stays the run's own literal. With no canonical role at the
+ * destination, every value stays literal — `roleVarOrLiteral`'s rule, applied per run
+ * instead of at the mutation point. An attr the copy left absent stays absent.
+ */
+export const relinkRunTypographyToRole = (
+  resolved: ResolvedRunStyle,
+  destinationRole: GlobalTextStyleDeclaration | undefined,
+): ResolvedRunStyle => {
+  const relinked: ResolvedRunStyle = { ...resolved };
+
+  if (!destinationRole) return relinked;
+
+  for (const { markAttr } of ROLE_VAR_ATTRS) {
+    const value = resolved[markAttr];
+
+    if (value === undefined) continue;
+
+    relinked[markAttr] = isSameTypographyValue(
+      markAttr,
+      value,
+      destinationRole[markAttr],
+    )
+      ? roleVarRef(markAttr)!
+      : value;
+  }
+
+  return relinked;
+};
+
+/**
+ * Relink a resolved colour to the destination palette (A5 step 3, R3, D3). On a link
+ * run, the fixed link colour is never remapped, so a coincidental match doesn't mint a
+ * spurious reference. Otherwise (including a non-link run that happens to equal the
+ * fixed link colour): a destination palette ROLE holding the same canonical value wins
+ * first (lowest index — `roleIdsByCanonicalValue`'s tie-break), then a custom in stored
+ * order (blanks skipped); with no match, the canonical hex stays fixed and nothing is
+ * added to the palette.
+ */
+export const relinkColorToPalette = (
+  canonicalHex: string,
+  colors: ColorItem[],
+  isLinkColor = false,
+): string => {
+  if (isLinkColor && canonicalHex === DEFAULT_LINK_COLOR) return canonicalHex;
+
+  const roleId = roleIdsByCanonicalValue(colors).get(canonicalHex);
+
+  if (roleId) return toColorVarReference(roleId);
+
+  const custom = colors.find(
+    (color) =>
+      !isPaletteRoleId(color.id) &&
+      !isBlankColorValue(color.value) &&
+      canonicalSolidHex(color.value) === canonicalHex,
+  );
+
+  return custom ? toColorVarReference(custom.id) : canonicalHex;
+};
+
+/**
+ * Every paragraph/heading a paste touches takes the destination's alignment (Reading
+ * 14) — overriding whatever the source paragraphs carried. With no destination
+ * alignment resolved, the source's own alignment is cleared rather than left in place:
+ * an open-ended LAST paragraph merges into the following text using the SLICE's own
+ * attrs, so a leftover source alignment would repaint the destination's own trailing
+ * text — the open-ended FIRST paragraph merges the other way, keeping the destination
+ * paragraph's own attrs untouched.
+ */
+export const alignPastedParagraphs = (
+  content: JSONContent[],
+  destinationAlign: string | undefined,
+): JSONContent[] =>
+  content.map((node) => {
+    if (node.type !== 'paragraph' && node.type !== 'heading') return node;
+
+    const { textAlign: _sourceAlign, ...attrs } = (node.attrs ?? {}) as {
+      textAlign?: string;
+    };
+
+    return {
+      ...node,
+      attrs: destinationAlign
+        ? { ...attrs, textAlign: destinationAlign }
+        : attrs,
+    };
+  });
+
+const LINE_BREAK_RUN = /(?:\r\n?|\n)+/;
+
+/**
+ * A plain-text (no valid own-editor form) paste's paragraphs (Approach step 4): split on
+ * runs of line breaks — prosemirror-view's own rule — dropping empty pieces, each line
+ * becomes a paragraph carrying the caller's marks (the seed a first type, or the
+ * paste-point's marks, would take) and the destination's alignment. Open at both ends,
+ * so the first and last line join the surrounding text. `null` for text with no visible
+ * line (nothing to insert).
+ */
+export const plainTextToParagraphSlice = (
+  text: string,
+  marks: RteRunMark[],
+  textAlign: string | undefined,
+): RteClipboardSliceJSON | null => {
+  const lines = text.split(LINE_BREAK_RUN).filter((line) => line !== '');
+
+  if (!lines.length) return null;
+
+  return {
+    content: lines.map((line) => ({
+      type: 'paragraph',
+      ...(textAlign ? { attrs: { textAlign } } : {}),
+      content: [
+        {
+          type: 'text',
+          text: line,
+          ...(marks.length ? { marks } : {}),
+        },
+      ],
+    })),
+    openStart: 1,
+    openEnd: 1,
+  };
+};
+
+// The ProseMirror schema a paste is validated against: the SAME extension set the live
+// maker editor mounts (`restrictStarterKit`), so a node/mark the editor lacks — lists,
+// code — fails here exactly as it would fail reaching the real editor. `getSchema` is
+// DOM-less (mirrors `rte-schema-check.ts`), so this stays a pure check; built once and
+// cached.
+let cachedRteClipboardSchema: Schema | undefined;
+
+const getRteClipboardSchema = (): Schema =>
+  (cachedRteClipboardSchema ??= getSchema(
+    getRteExtensions({ restrictStarterKit: true }),
+  ));
+
+const canonicalSliceJSON = (
+  sliceJson: RteClipboardSliceJSON,
+): RteClipboardSliceJSON => {
+  const sanitized = sanitizeRteJson({
+    type: 'doc',
+    content: sliceJson.content,
+  });
+
+  return {
+    content: sanitized.content ?? [],
+    ...(sliceJson.openStart ? { openStart: sliceJson.openStart } : {}),
+    ...(sliceJson.openEnd ? { openEnd: sliceJson.openEnd } : {}),
+  };
+};
+
+/**
+ * Validate a clipboard string as our own, un-tampered `x-rte-slice` payload (R13): it
+ * parses, its version is ours, and it is byte-for-byte its own `sanitizeRteJson` form —
+ * an unsafe link or CSS value, an unknown mark, or even a key reordered from the
+ * sanitised form changes it and fails this. It must also build against the live editor
+ * schema — catching a node/mark `sanitizeRteJson`'s broader allowlist accepts but this
+ * editor's restricted schema doesn't (lists, code). `Slice.fromJSON` alone only checks
+ * that node/mark types exist; it neither validates a node's content against its type's
+ * content expression nor its mark set, and it accepts any `openStart`/`openEnd` number —
+ * fractional included — regardless of the content's actual depth — so every top-level node
+ * is also `check()`ed, and the open depths must be integers bounded by `Slice.maxOpen`. Any
+ * failure returns `null`, so the caller falls back to the text-only path instead of
+ * inserting a malformed slice.
+ */
+export const parseOwnRteClipboardPayload = (
+  raw: string,
+): RteClipboardPayload | null => {
+  let candidate: unknown;
+
+  try {
+    candidate = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+
+  if (
+    !candidate ||
+    typeof candidate !== 'object' ||
+    (candidate as { v?: unknown }).v !== RTE_CLIPBOARD_VERSION
+  ) {
+    return null;
+  }
+
+  const slice = (candidate as { slice?: unknown }).slice;
+
+  if (!slice || typeof slice !== 'object') return null;
+
+  const canonical: RteClipboardPayload = {
+    v: RTE_CLIPBOARD_VERSION,
+    slice: canonicalSliceJSON(slice as RteClipboardSliceJSON),
+  };
+
+  if (JSON.stringify(candidate) !== JSON.stringify(canonical)) return null;
+
+  try {
+    const parsed = Slice.fromJSON(getRteClipboardSchema(), slice);
+
+    parsed.content.forEach((node) => node.check());
+
+    const maxOpen = Slice.maxOpen(parsed.content);
+
+    if (
+      !Number.isInteger(parsed.openStart) ||
+      !Number.isInteger(parsed.openEnd) ||
+      parsed.openStart < 0 ||
+      parsed.openEnd < 0 ||
+      parsed.openStart > maxOpen.openStart ||
+      parsed.openEnd > maxOpen.openEnd
+    ) {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+
+  return canonical;
+};

package/src/brand-page-maker/utils/rte-features.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, afterEach } from 'vitest';
-import { Editor } from '@tiptap/vue-3';
-import { getRteExtensions } from '../composables/rich-text-editor/getRteExtensions';
-import { toRteJson, renderRteToHtml } from './rte-render.util';
+import { Editor, type JSONContent } from '@tiptap/vue-3';
+import { getRteExtensions } from '@shared/rte-extensions.util';
+import { toRteJson, renderRteToHtml } from '@shared/rte-render.util';
 import { sanitizeRteJson } from './rte-sanitize.util';
 
 /**
@@ -61,6 +61,102 @@ describe('RTE features — mark nesting (decoration must inherit font-size)', ()
 });
 
 describe('RTE features — textStyle attrs (colour/font/spacing)', () => {
+  it('keeps text-decoration in JSON and emits a class only for role-aware rendering', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'x',
+              marks: [
+                {
+                  type: 'textStyle',
+                  attrs: { textDecoration: 'line-through' },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    expect(doc.content[0].content[0].marks[0].attrs.textDecoration).toBe(
+      'line-through',
+    );
+    const storedDoc = JSON.stringify(doc);
+
+    expect(renderRteToHtml(doc)).toContain('text-decoration: line-through');
+    expect(renderRteToHtml(doc, { textDecorationClasses: true })).toContain(
+      'class="bp-rte-text-decoration-linethrough"',
+    );
+    expect(JSON.stringify(doc)).toBe(storedDoc);
+  });
+
+  it('keeps a role-reset decoration valid for renderers that do not know the reset marker', () => {
+    const doc = {
+      type: 'doc',
+      content: [
+        {
+          type: 'paragraph',
+          content: [
+            {
+              type: 'text',
+              text: 'x',
+              marks: [
+                {
+                  type: 'textStyle',
+                  attrs: {
+                    textDecoration: 'line-through',
+                    textDecorationReset: true,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    expect(renderRteToHtml(doc)).toContain('text-decoration: line-through');
+    expect(renderRteToHtml(doc)).not.toContain('none line-through');
+    expect(renderRteToHtml(doc, { textDecorationClasses: true })).toContain(
+      'class="bp-rte-text-decoration-reset-linethrough"',
+    );
+  });
+
+  const decoratedDoc = (textDecoration: string): JSONContent => ({
+    type: 'doc',
+    content: [
+      {
+        type: 'paragraph',
+        content: [
+          {
+            type: 'text',
+            text: 'x',
+            marks: [{ type: 'textStyle', attrs: { textDecoration } }],
+          },
+        ],
+      },
+    ],
+  });
+
+  it('keeps the role text-decoration link as written in style rendering', () => {
+    const html = renderRteToHtml(decoratedDoc('var(--role-text-decoration)'));
+
+    expect(html).toContain('text-decoration: var(--role-text-decoration)');
+    expect(html).not.toContain('undefined');
+  });
+
+  it('composes a literal text-decoration in style rendering', () => {
+    const html = renderRteToHtml(decoratedDoc('none underline'));
+
+    expect(html).toContain('text-decoration: underline');
+    expect(html).not.toContain('none underline');
+  });
+
   it('rgb colour is preserved', () => {
     expect(
       pipe('<p><span style="color: rgb(255, 0, 0)">x</span></p>'),

package/src/brand-page-maker/utils/rte-render-parity.test.ts

@@ -5,7 +5,7 @@ import {
   renderRteToHtml,
   toRteJson,
   getRteJsonPlainText,
-} from './rte-render.util';
+} from '@shared/rte-render.util';
 import {
   COMPLEX_RTE_HTML,
   THEME_TOKEN_REF,