@globalpayments/vega 2.98.0 → 2.99.0

package/dist/collection/components/vega-rich-text-editor/extensions/paste/strategies/word-paste-strategy.js

@@ -0,0 +1,416 @@
+import { StylePreservator } from '../../../../../helpers/csp/styles-preservator';
+import { AbstractPasteProcessingStrategy, RTEPasteMode, PasteProcessingStrategyPriority, } from './paste-processing-strategy.abstract';
+import { WORD_SANITIZE_ALL_TAGS_KEY, } from '../word-paste-transformers/word-structure-transformer';
+import { WordParagraphRoleTransformer } from '../word-paste-transformers/word-structure-paragraph-transformer';
+import { WordListRoleTransformer } from '../word-paste-transformers/word-structure-list-transformer';
+import { WordImageTransformer } from '../word-paste-transformers/word-structure-image-transformer';
+import { WordTableTransformer } from '../word-paste-transformers/word-structure-table-transformer';
+import { WordCodeBlockTransformer } from '../word-paste-transformers/word-structure-code-block-transformer';
+/**
+ * Default Word transformers. Sanitizer allowlist is aggregated from these
+ * transformer contracts so adding a new transformer automatically extends the
+ * allowlist surface.
+ */
+export const WORD_STRUCTURE_TRANSFORMERS = [
+  new WordTableTransformer(),
+  new WordListRoleTransformer(),
+  new WordImageTransformer(),
+  new WordCodeBlockTransformer(),
+  new WordParagraphRoleTransformer(),
+];
+/**
+ * Aggregates the sanitizer allowlist from each transformer's declared contract
+ * (tags, attributes, style prefixes), removing duplicates and normalizing case
+ * so the strategy allowlist can never drift from the transformers that depend on
+ * it.
+ *
+ * @param {WordStructureTransformer[]} transformers Registered structure transformers.
+ * @returns {WordSanitizeConfig} Combined sanitizer configuration.
+ */
+function buildWordSanitizeConfig(transformers) {
+  const tags = new Set();
+  const stylePrefixes = new Set();
+  const attributesMap = new Map();
+  transformers.forEach((transformer) => {
+    transformer.getAllowedTags().forEach((tag) => {
+      tags.add(tag.toUpperCase());
+    });
+    transformer.getAllowedStyles().forEach((prefix) => {
+      stylePrefixes.add(prefix.toLowerCase());
+    });
+    transformer.getAllowedAttributes().forEach((attrs, tagName) => {
+      const normalizedTagName = tagName === WORD_SANITIZE_ALL_TAGS_KEY ? tagName : tagName.toUpperCase();
+      if (!attributesMap.has(normalizedTagName)) {
+        attributesMap.set(normalizedTagName, new Set());
+      }
+      const attrSet = attributesMap.get(normalizedTagName);
+      attrs.forEach((attr) => {
+        attrSet.add(attr.toLowerCase());
+      });
+    });
+  });
+  const allowedAttributes = {};
+  attributesMap.forEach((attrs, tagName) => {
+    allowedAttributes[tagName] = Array.from(attrs);
+  });
+  return {
+    allowedTags: Array.from(tags),
+    allowedAttributes,
+    allowedStylePrefixes: Array.from(stylePrefixes),
+  };
+}
+/**
+ * Default sanitizer allowlist aggregated from
+ * {@link WORD_STRUCTURE_TRANSFORMERS}. Exported so tests and callers can still
+ * provide stable overrides.
+ */
+export const WORD_SANITIZE_CONFIG = buildWordSanitizeConfig(WORD_STRUCTURE_TRANSFORMERS);
+/**
+ * Attribute name that carries inline styles after {@link StylePreservator} has
+ * renamed `style` to `data-style`. All sanitization runs against this name so
+ * the styles survive the CSP-sensitive `DOMParser` boundary.
+ */
+const PRESERVED_STYLE_ATTR = 'data-style';
+/**
+ * Block tag that can represent an intentional blank line pasted from Word
+ * (an "empty" paragraph whose only content is a non-breaking space). Headings
+ * are excluded — an empty heading is treated as noise, not an intentional
+ * blank line.
+ */
+const BLANK_LINE_ELIGIBLE_TAGS = 'p';
+/**
+ * Zero-width space used to keep an intentional blank line alive. Unlike a
+ * non-breaking space, it is not stripped by `String.prototype.trim()`, so the
+ * downstream empty-block removal keeps the paragraph while it still renders as
+ * blank.
+ */
+const ZERO_WIDTH_SPACE = '\u200B';
+/**
+ * Style values the RTE cannot resolve, so any declaration whose value contains
+ * one of them is dropped during sanitization. These ride on allowed properties
+ * (`color`, `border`, `background`, …), so the prefix allowlist alone cannot
+ * remove them. Add legacy Word keywords here to filter them everywhere.
+ */
+// eslint-disable-next-line spellcheck/spell-checker
+const INVALID_STYLE_VALUES = ['windowtext'];
+/**
+ * Pre processes raw Word/Office clipboard HTML into clean, RTE-friendly HTML.
+ *
+ * The pipeline mirrors the two-phase design of the source Word cleaner:
+ * 1. Structure fixing — maps Word paragraph styles onto RTE text styles and
+ *    drops Word list marker artifacts.
+ * 2. Dynamic allowlist sanitizing — recursively strips disallowed tags,
+ *    attributes and inline style declarations while keeping inner content.
+ */
+export class WordPasteProcessingStrategy extends AbstractPasteProcessingStrategy {
+  /**
+   * Downstream paste mode marker for Word-specific processing.
+   *
+   * @returns {RTEPasteMode} `word` so downstream handlers preserve Word annotations.
+   */
+  get type() {
+    return RTEPasteMode.WORD;
+  }
+  /**
+   * Detects whether raw clipboard HTML originated from Microsoft Word / Office.
+   *
+   * Used to auto-route a normal "rich text" paste through the Word cleaning
+   * pipeline when the source is actually Word, so users get correct formatting
+   * without having to explicitly pick the Word paste option.
+   *
+   * @param {string} html Raw `text/html` clipboard payload.
+   * @returns {boolean} `true` when the HTML carries Word/Office signatures.
+   */
+  canHandle(html) {
+    if (!html) {
+      return false;
+    }
+    return WordPasteProcessingStrategy.WORD_SIGNATURE_PATTERNS.some((pattern) => pattern.test(html));
+  }
+  /**
+   * Returns the priority of this strategy relative to others; higher values run first.
+   *
+   * @returns {number} The priority value.
+   */
+  get priority() {
+    return PasteProcessingStrategyPriority.WORD;
+  }
+  /**
+   * Whether this strategy extracts pasted images and produces local previews.
+   *
+   * @returns {boolean} Always `true`; Word paste swaps `file://` images to previews.
+   */
+  get supportsImageProcessing() {
+    return true;
+  }
+  /**
+   * Cleans raw Word clipboard HTML so it can flow through the normal RTE paste
+   * pipeline.
+   *
+   * @param {string} html Raw `text/html` clipboard payload from Word.
+   * @param {WordSanitizeConfig} [config] Optional allowlist override.
+   * @returns {string} Sanitized HTML string.
+   */
+  process(html, config = WORD_SANITIZE_CONFIG) {
+    if (!html) {
+      return '';
+    }
+    const withoutComments = this.stripWordComments(html);
+    // Preserve inline styles across the DOMParser boundary to avoid
+    // style-src-attr CSP violations (styles become data-style attributes).
+    const preservedHtml = StylePreservator.preserve(withoutComments).getProcessedHtml();
+    const parsedDoc = new DOMParser().parseFromString(preservedHtml, 'text/html');
+    const container = parsedDoc.body;
+    this.fixWordStructure(container);
+    // Sanitize each top-level child instead of the <body> itself so the body
+    // container is never unwrapped away.
+    Array.from(container.childNodes).forEach((child) => {
+      this.sanitizeNode(child, config);
+    });
+    // Collapse the source line wraps Word inserts inside text so a single
+    // logical line does not paste as multiple lines.
+    this.collapseInsignificantWhitespace(container);
+    // Drop the whitespace Word inserts directly between block elements so it
+    // does not paste as empty lines.
+    this.removeInterBlockWhitespace(container);
+    // Keep intentional blank lines (Word empty paragraphs) from being dropped by
+    // the downstream empty-block removal.
+    this.preserveWordEmptyLines(container);
+    return this.restoreStyleAttributeName(container.innerHTML);
+  }
+  /**
+   * Removes Office XML comments and down-level conditional markup that would
+   * otherwise confuse `DOMParser`.
+   *
+   * @param {string} html Raw HTML string.
+   * @returns {string} HTML without Word comment blocks.
+   */
+  stripWordComments(html) {
+    return html.replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[[\s\S]*?\]>/g, '');
+  }
+  /**
+   * First phase: repairs Word-specific structure so it aligns with RTE text
+   * styles before the allowlist pass runs.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  fixWordStructure(root) {
+    WordPasteProcessingStrategy.STRUCTURE_TRANSFORMERS.forEach((transformer) => {
+      transformer.apply(root);
+    });
+  }
+  /**
+   * Removes the whitespace-only text nodes Word emits directly between block
+   * elements (the `\n\n` at the top level of the fragment). After the allowlist
+   * pass, disallowed containers are already unwrapped, so any remaining
+   * top-level text node that is pure whitespace is an inter-block artifact.
+   * Whitespace inside inline/text elements is left untouched.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  removeInterBlockWhitespace(root) {
+    Array.from(root.childNodes).forEach((node) => {
+      if (node.nodeType === Node.TEXT_NODE && node.textContent.trim() === '') {
+        root.removeChild(node);
+      }
+    });
+  }
+  /**
+   * Collapses insignificant ASCII whitespace inside text nodes the way a
+   * browser would when rendering. Word wraps long runs of text across multiple
+   * source lines, so a single logical line such as "Number list 1" arrives as
+   * "Number\nlist 1"; without normalization the newline surfaces as a spurious
+   * line break in the editor. Non-breaking spaces (`\u00A0`) are left untouched
+   * so intentional Word spacing and blank lines survive.
+   *
+   * @param {Node} node Node whose text descendants are normalized in place.
+   */
+  collapseInsignificantWhitespace(node) {
+    // Code blocks preserve their original whitespace, so skip the whole subtree.
+    if (WordCodeBlockTransformer.isCodeBlock(node)) {
+      return;
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+      const original = node.textContent;
+      const collapsed = original.replace(/[ \t\r\n\f]+/g, ' ');
+      if (collapsed !== original) {
+        node.textContent = collapsed;
+      }
+      return;
+    }
+    Array.from(node.childNodes).forEach((child) => {
+      this.collapseInsignificantWhitespace(child);
+    });
+  }
+  /**
+   * Preserves intentional blank lines authored in Word (empty paragraphs whose
+   * only content is a non-breaking space). The downstream paste pipeline drops
+   * any block whose text content trims to empty, and `trim()` also removes a
+   * non-breaking space; replacing the content with a zero-width space keeps the
+   * blank line because it survives `trim()` while still rendering as empty.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  preserveWordEmptyLines(root) {
+    Array.from(root.querySelectorAll(BLANK_LINE_ELIGIBLE_TAGS)).forEach((block) => {
+      // Word paragraphs that host an image also carry a trailing
+      // `<o:p>&nbsp;</o:p>` whose non-breaking space would misidentify the
+      // paragraph as an empty line and wipe the image out.
+      if (block.querySelector('img')) {
+        return;
+      }
+      const text = block.textContent;
+      const hasRealText = text.replace(/[\s\u200B]+/g, '') !== '';
+      // Only an "empty" block that carries a non-breaking space is treated as
+      // an intentional Word blank line.
+      if (!hasRealText && /\u00A0/.test(text)) {
+        block.textContent = ZERO_WIDTH_SPACE;
+      }
+    });
+  }
+  /**
+   * Second phase: recursively enforces the dynamic allowlist on a node tree.
+   *
+   * @param {Node} node Node to sanitize in place.
+   * @param {WordSanitizeConfig} config Active allowlist configuration.
+   */
+  sanitizeNode(node, config) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      return;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+      this.removeSelf(node);
+      return;
+    }
+    const element = node;
+    const tagName = element.tagName.toUpperCase();
+    // Sanitize children first (reverse order keeps indices stable while nodes
+    // may be removed or unwrapped).
+    const children = Array.from(element.childNodes);
+    for (let i = children.length - 1; i >= 0; i--) {
+      this.sanitizeNode(children[i], config);
+    }
+    // Tag-level filter: unwrap disallowed elements but keep their content.
+    if (!config.allowedTags.includes(tagName)) {
+      while (element.firstChild) {
+        if (element.parentNode && typeof element.parentNode.insertBefore === 'function') {
+          element.parentNode.insertBefore(element.firstChild, element);
+        }
+      }
+      this.removeSelf(element);
+      return;
+    }
+    this.sanitizeAttributes(element, tagName, config);
+  }
+  /**
+   * Removes disallowed attributes and filters style declarations.
+   *
+   * @param {Element} element Element being sanitized.
+   * @param {string} tagName Upper-case tag name.
+   * @param {WordSanitizeConfig} config Active sanitize configuration.
+   */
+  sanitizeAttributes(element, tagName, config) {
+    const commonAttrs = config.allowedAttributes[WORD_SANITIZE_ALL_TAGS_KEY] || [];
+    const tagAttrs = config.allowedAttributes[tagName] || [];
+    const allowedAttrs = new Set([...commonAttrs, ...tagAttrs]);
+    Array.from(element.attributes).forEach((attr) => {
+      const attrName = attr.name.toLowerCase();
+      const isStyle = attrName === PRESERVED_STYLE_ATTR;
+      const normalizedName = isStyle ? 'style' : attrName;
+      if (!allowedAttrs.has(normalizedName)) {
+        element.removeAttribute(attr.name);
+        return;
+      }
+      if (isStyle) {
+        this.sanitizeStyleAttribute(element, attr.name, config);
+      }
+    });
+  }
+  /**
+   * Filters CSS declarations inside a preserved style attribute: keeps only
+   * properties matching a prefix in {@link WordSanitizeConfig.allowedStylePrefixes};
+   * all others (including `mso-*` Word artifacts) are stripped.
+   *
+   * @param {Element} element Element owning the style attribute.
+   * @param {string} attrName Preserved style attribute name.
+   * @param {WordSanitizeConfig} config Active sanitize configuration.
+   */
+  sanitizeStyleAttribute(element, attrName, config) {
+    const rawStyle = element.getAttribute(attrName) || '';
+    // Delegate CSS parsing to the browser engine via a temporary element so
+    // that edge cases (values containing semicolons, multi-value shorthand,
+    // etc.) are handled correctly without a hand-rolled parser.
+    const tempEl = element.ownerDocument.createElement('span');
+    tempEl.setAttribute('style', rawStyle);
+    const parsedStyle = tempEl.style;
+    const cleanDeclarations = [];
+    for (let i = 0; i < parsedStyle.length; i++) {
+      const key = parsedStyle[i];
+      // Keep only properties whose name starts with an allowed prefix.
+      const isAllowed = config.allowedStylePrefixes.some((prefix) => key === prefix || key.startsWith(`${prefix}-`));
+      const value = parsedStyle.getPropertyValue(key);
+      // Drop declarations carrying a value the RTE cannot resolve (e.g. Word's
+      // legacy `windowText` system color), even on otherwise allowed properties.
+      const lowerCaseValue = value.toLowerCase();
+      const hasInvalidValue = INVALID_STYLE_VALUES.some((invalid) => lowerCaseValue.includes(invalid));
+      if (isAllowed && !hasInvalidValue) {
+        cleanDeclarations.push(`${key}: ${value}`);
+      }
+    }
+    const cleanStyle = cleanDeclarations.join('; ');
+    if (cleanStyle) {
+      element.setAttribute(attrName, cleanStyle);
+    }
+    else {
+      element.removeAttribute(attrName);
+    }
+  }
+  /**
+   * Converts preserved `data-style` attributes back to `style` in the final
+   * HTML string so downstream paste handling receives standard markup.
+   *
+   * @param {string} html Serialized sanitized HTML.
+   * @returns {string} HTML with `style` attributes restored.
+   */
+  restoreStyleAttributeName(html) {
+    return html.replace(/\sdata-style=/g, ' style=');
+  }
+  /**
+   * Removes the element from its parent node if it has one.
+   *
+   * @param {Node | Element} elementToBeRemoved The element to be removed from the DOM.
+   */
+  removeSelf(elementToBeRemoved) {
+    if (elementToBeRemoved.parentNode &&
+      typeof elementToBeRemoved.parentNode.removeChild === 'function') {
+      elementToBeRemoved.parentNode.removeChild(elementToBeRemoved);
+    }
+  }
+}
+/**
+ * Ordered list of structure transformers applied in Phase 1 before allowlist
+ * sanitization. To add support for a new node type (table, image, list…),
+ * create a class that implements {@link WordStructureTransformer} and append
+ * it here — no other changes to the pipeline are needed.
+ */
+WordPasteProcessingStrategy.STRUCTURE_TRANSFORMERS = [
+  ...WORD_STRUCTURE_TRANSFORMERS,
+];
+/**
+ * Signatures that identify clipboard HTML produced by Microsoft Word / Office.
+ * Any single match is enough to treat the payload as Word content because
+ * these markers do not appear in ordinary web or plain rich-text clipboards.
+ */
+WordPasteProcessingStrategy.WORD_SIGNATURE_PATTERNS = [
+  // <meta name=Generator content="Microsoft Word ...">
+  /content=["']?Microsoft\s+Word/i,
+  // eslint-disable-next-line spellcheck/spell-checker
+  // Office namespace declarations (urn:schemas-microsoft-com:office:word).
+  /urn:schemas-microsoft-com:office/i,
+  // Word paragraph/character style classes (MsoNormal, MsoTitle, MsoListParagraph…).
+  /class=["']?Mso[A-Za-z]/i,
+  // Word-only inline style properties.
+  /mso-[a-z-]+\s*:/i,
+  // Office XML paragraph marker elements (<o:p></o:p>).
+  /<\/?o:p>/i,
+];

package/dist/collection/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-code-block-transformer.js

@@ -0,0 +1,106 @@
+/**
+ * Attribute that the RTE code-block parser uses to recognize code content.
+ */
+const CODE_LANGUAGE_ATTR = 'data-language';
+/**
+ * Default language applied when pasted code has no language metadata.
+ */
+const DEFAULT_CODE_LANGUAGE = 'plainText';
+/**
+ * Matches language hints encoded as CSS classes (for example `language-js`).
+ */
+const LANGUAGE_CLASS_PATTERN = /(?:^|\s)(?:language|lang)-([a-z0-9+_.-]+)(?:\s|$)/i;
+/**
+ * Removes Word-only class artifacts from code elements while preserving other
+ * classes. Kept as defense-in-depth: even though the shared sanitizer allowlist
+ * generally strips `Mso*` classes, this transformer normalizes the `<pre>`
+ * class list before language resolution so a stray `MsoPlainText` can never
+ * leak into `LANGUAGE_CLASS_PATTERN` matching.
+ */
+const WORD_CLASS_NAME_PATTERN = /^mso[a-z0-9_-]*$/i;
+/**
+ * Normalizes pasted `<pre>` nodes so they can be parsed as RTE code blocks.
+ *
+ * The RTE recognizes a code block only when `data-language` is present on
+ * `<pre>`. Word-exported snippets commonly use plain `<pre>` with no
+ * language metadata, so this transformer adds a default language and copies any
+ * detectable language hint from nested code markup when available.
+ */
+export class WordCodeBlockTransformer {
+  /**
+   * Determines whether a node is a code block whose whitespace must be preserved.
+   *
+   * @param {Node} node Node to inspect.
+   * @returns {boolean} `true` when the node is a `<pre>` element.
+   */
+  static isCodeBlock(node) {
+    return node.nodeType === Node.ELEMENT_NODE && node.tagName.toUpperCase() === 'PRE';
+  }
+  /** @inheritDoc */
+  apply(root) {
+    Array.from(root.querySelectorAll('pre')).forEach((preElement) => {
+      this.stripWordClassArtifacts(preElement);
+      if (!preElement.hasAttribute(CODE_LANGUAGE_ATTR)) {
+        preElement.setAttribute(CODE_LANGUAGE_ATTR, this.resolveLanguage(preElement));
+      }
+    });
+  }
+  /** @inheritDoc */
+  getAllowedTags() {
+    return ['PRE'];
+  }
+  /** @inheritDoc */
+  getAllowedAttributes() {
+    return new Map([['PRE', [CODE_LANGUAGE_ATTR]]]);
+  }
+  /** @inheritDoc */
+  getAllowedStyles() {
+    return [];
+  }
+  /**
+   * Resolves code language metadata from `<pre>` class hints, falling back to
+   * {@link DEFAULT_CODE_LANGUAGE}.
+   *
+   * `apply()` only invokes this method when the `<pre>` has no
+   * `data-language` attribute, so class-based inference is the only source
+   * this method needs to consult.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   * @returns {string} Resolved language id or `plainText` fallback.
+   */
+  resolveLanguage(preElement) {
+    const classLanguage = this.resolveLanguageFromClassName(preElement).trim();
+    return classLanguage !== '' ? classLanguage : DEFAULT_CODE_LANGUAGE;
+  }
+  /**
+   * Extracts a language id from class names like `language-js` or `lang-ts`.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   * @returns {string} Extracted language id or empty string.
+   */
+  resolveLanguageFromClassName(preElement) {
+    const className = preElement.getAttribute('class') || '';
+    const match = LANGUAGE_CLASS_PATTERN.exec(className);
+    return match ? match[1] : '';
+  }
+  /**
+   * Removes Word-only `Mso*` class names and keeps any non-Word classes.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   */
+  stripWordClassArtifacts(preElement) {
+    const className = preElement.getAttribute('class') || '';
+    if (!className) {
+      return;
+    }
+    const filteredClasses = className
+      .split(/\s+/)
+      .map((name) => name.trim())
+      .filter((name) => name !== '' && !WORD_CLASS_NAME_PATTERN.test(name));
+    if (filteredClasses.length === 0) {
+      preElement.removeAttribute('class');
+      return;
+    }
+    preElement.setAttribute('class', filteredClasses.join(' '));
+  }
+}