@globalpayments/vega 2.98.0 → 2.99.0

package/dist/types/components/vega-rich-text-editor/extensions/paste/strategies/default-paste-strategy.d.ts

@@ -0,0 +1,29 @@
+import { AbstractPasteProcessingStrategy } from './paste-processing-strategy.abstract';
+/**
+ * Default paste processing strategy that acts as a fallback when no other
+ * strategy matches. This strategy always accepts the content and passes it
+ * through unchanged — the normal RTE paste pipeline (DOMParser +
+ * ElementToDtoStrategyProcessor) handles the rest.
+ */
+export declare class DefaultPasteProcessingStrategy extends AbstractPasteProcessingStrategy {
+  /**
+   * Always matches as the terminal fallback strategy.
+   *
+   * @param {string} html Raw clipboard HTML.
+   * @returns {boolean} Always `true`.
+   */
+  canHandle(html: string): boolean;
+  /**
+   * Returns the original HTML unchanged.
+   *
+   * @param {string} html Raw clipboard HTML.
+   * @returns {string} Unchanged HTML.
+   */
+  process(html: string): string;
+  /**
+   * Fallback priority so other strategies can win when matched.
+   *
+   * @returns {number} Strategy priority.
+   */
+  get priority(): number;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/strategies/paste-processing-strategy.abstract.d.ts

@@ -0,0 +1,61 @@
+export declare enum RTEPasteMode {
+  RICH = "rich",
+  WORD = "word"
+}
+/**
+ * Priority scale shared by all paste processing strategies.
+ */
+export declare enum PasteProcessingStrategyPriority {
+  /** Fallback strategy used only when no specialized strategy matches. */
+  DEFAULT_FALLBACK = -1,
+  /** Baseline priority for generic strategies. */
+  BASE = 0,
+  /** Word strategy priority so it outranks generic strategies. */
+  WORD = 10
+}
+/**
+ * Abstract base class for paste processing strategies.
+ *
+ * Each strategy implements detection logic (`canHandle`) and transformation
+ * logic (`process`) for a specific clipboard source (Word, Google Docs, etc.).
+ * The strategy selector chooses the highest-priority strategy that can handle
+ * the given HTML.
+ */
+export declare abstract class AbstractPasteProcessingStrategy {
+  /**
+   * Downstream paste mode marker associated with this strategy.
+   *
+   * Defaults to regular rich-text paste unless a specialized strategy overrides it.
+   *
+   * @returns {RTEPasteMode} Paste mode marker for downstream handlers.
+   */
+  get type(): RTEPasteMode;
+  /**
+   * Optional: Strategy priority when multiple strategies match.
+   * Higher numbers = higher priority. Default: 0.
+   *
+   * @returns {number} Strategy priority.
+   */
+  get priority(): number;
+  /**
+   * Whether pasted images from this source should be extracted into local
+   * previews by the paste extension after {@link process} runs.
+   *
+   * @returns {boolean} `false` unless a strategy opts into image processing.
+   */
+  get supportsImageProcessing(): boolean;
+  /**
+   * Detect whether this strategy should handle the given HTML content.
+   *
+   * @param html Raw clipboard HTML
+   * @returns true if this strategy should process the content
+   */
+  abstract canHandle(html: string): boolean;
+  /**
+   * Transform/sanitize the HTML content for this paste source.
+   *
+   * @param html Raw clipboard HTML
+   * @returns Processed HTML ready for the RTE pipeline
+   */
+  abstract process(html: string): string;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/strategies/paste-strategy-selector.d.ts

@@ -0,0 +1,45 @@
+import { AbstractPasteProcessingStrategy } from './paste-processing-strategy.abstract';
+import { RTEPasteMode } from './paste-processing-strategy.abstract';
+/**
+ * Centralized selector for paste processing strategies.
+ *
+ * Maintains a registry of available strategies and selects the highest-priority
+ * strategy that can handle the given clipboard HTML. Provides an extension
+ * point for adding support for new clipboard sources (e.g., Google Docs, Notion)
+ * without modifying the paste extension core logic.
+ */
+export declare class PasteStrategySelector {
+  private readonly defaultStrategy;
+  private strategies;
+  /**
+   * Select the appropriate strategy for the given HTML content.
+   * Returns the highest-priority strategy that can handle the content.
+   *
+   * @param {string} html Raw clipboard HTML.
+   * @returns {AbstractPasteProcessingStrategy} The selected strategy (always returns a strategy; default is the fallback).
+   */
+  selectStrategy(html: string): AbstractPasteProcessingStrategy;
+  /**
+   * Selects the highest-priority registered strategy for an explicitly chosen paste mode.
+   *
+   * Used when the user manually chooses a non-default mode from the paste chooser.
+   *
+   * @param {RTEPasteMode} type Explicit paste mode selected by the user.
+   * @returns {AbstractPasteProcessingStrategy} The matching strategy or the default fallback.
+   */
+  selectStrategyByType(type: RTEPasteMode): AbstractPasteProcessingStrategy;
+  /**
+   * Register a new paste processing strategy.
+   * Useful for future extensions (e.g., GoogleDocsPasteStrategy).
+   *
+   * @param {AbstractPasteProcessingStrategy} strategy The strategy to register.
+   */
+  registerStrategy(strategy: AbstractPasteProcessingStrategy): void;
+  /**
+   * Returns the highest-priority strategy from a candidate set or the default fallback.
+   *
+   * @param {AbstractPasteProcessingStrategy[]} strategies Candidate strategies.
+   * @returns {AbstractPasteProcessingStrategy} Selected strategy.
+   */
+  private selectHighestPriorityStrategy;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/strategies/word-paste-strategy.d.ts

@@ -0,0 +1,186 @@
+import { AbstractPasteProcessingStrategy, RTEPasteMode } from './paste-processing-strategy.abstract';
+import { WordStructureTransformer } from '../word-paste-transformers/word-structure-transformer';
+/**
+ * Dynamic allowlist configuration for the Word paste sanitizer. Every rule is
+ * data-driven so the supported surface can grow per requirement without touching
+ * the sanitizer algorithm.
+ */
+export declare type WordSanitizeConfig = {
+  /** Allowed HTML tag names (upper case). */
+  allowedTags: string[];
+  /**
+   * Attribute names allowed per tag (upper case key). Use
+   * {@link WORD_SANITIZE_ALL_TAGS_KEY} for attributes allowed on every tag.
+   */
+  allowedAttributes: Record<string, string[]>;
+  /**
+   * CSS property **prefixes** to preserve. A property is kept if its canonical
+   * name (lower-case) starts with any prefix in this list; all others
+   * (including `mso-*` Word artifacts) are stripped.
+   *
+   * Examples:
+   * - `'margin'` keeps `margin`, `margin-left`, `margin-right`, etc.
+   * - `'background'` keeps `background`, `background-color`, etc.
+   * - `'text-align'` keeps only `text-align` (exact match when no variants).
+   */
+  allowedStylePrefixes: string[];
+};
+/**
+ * Default Word transformers. Sanitizer allowlist is aggregated from these
+ * transformer contracts so adding a new transformer automatically extends the
+ * allowlist surface.
+ */
+export declare const WORD_STRUCTURE_TRANSFORMERS: WordStructureTransformer[];
+/**
+ * Default sanitizer allowlist aggregated from
+ * {@link WORD_STRUCTURE_TRANSFORMERS}. Exported so tests and callers can still
+ * provide stable overrides.
+ */
+export declare const WORD_SANITIZE_CONFIG: WordSanitizeConfig;
+/**
+ * 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 declare class WordPasteProcessingStrategy extends AbstractPasteProcessingStrategy {
+  /**
+   * 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.
+   */
+  static readonly STRUCTURE_TRANSFORMERS: WordStructureTransformer[];
+  /**
+   * 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.
+   */
+  private static readonly WORD_SIGNATURE_PATTERNS;
+  /**
+   * Downstream paste mode marker for Word-specific processing.
+   *
+   * @returns {RTEPasteMode} `word` so downstream handlers preserve Word annotations.
+   */
+  get type(): RTEPasteMode;
+  /**
+   * 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: string): boolean;
+  /**
+   * Returns the priority of this strategy relative to others; higher values run first.
+   *
+   * @returns {number} The priority value.
+   */
+  get priority(): number;
+  /**
+   * Whether this strategy extracts pasted images and produces local previews.
+   *
+   * @returns {boolean} Always `true`; Word paste swaps `file://` images to previews.
+   */
+  get supportsImageProcessing(): boolean;
+  /**
+   * 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: string, config?: WordSanitizeConfig): string;
+  /**
+   * 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.
+   */
+  private stripWordComments;
+  /**
+   * First phase: repairs Word-specific structure so it aligns with RTE text
+   * styles before the allowlist pass runs.
+   *
+   * @param {HTMLElement} root Parsed body element.
+   */
+  private fixWordStructure;
+  /**
+   * 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.
+   */
+  private removeInterBlockWhitespace;
+  /**
+   * 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.
+   */
+  private collapseInsignificantWhitespace;
+  /**
+   * 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.
+   */
+  private preserveWordEmptyLines;
+  /**
+   * 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.
+   */
+  private sanitizeNode;
+  /**
+   * 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.
+   */
+  private sanitizeAttributes;
+  /**
+   * 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.
+   */
+  private sanitizeStyleAttribute;
+  /**
+   * 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.
+   */
+  private restoreStyleAttributeName;
+  /**
+   * Removes the element from its parent node if it has one.
+   *
+   * @param {Node | Element} elementToBeRemoved The element to be removed from the DOM.
+   */
+  private removeSelf;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-code-block-transformer.d.ts

@@ -0,0 +1,51 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * 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 declare class WordCodeBlockTransformer implements WordStructureTransformer {
+  /**
+   * 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: Node): boolean;
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /**
+   * 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.
+   */
+  private resolveLanguage;
+  /**
+   * 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.
+   */
+  private resolveLanguageFromClassName;
+  /**
+   * Removes Word-only `Mso*` class names and keeps any non-Word classes.
+   *
+   * @param {HTMLElement} preElement Source `<pre>` element.
+   */
+  private stripWordClassArtifacts;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/word-paste-transformers/word-structure-image-transformer.d.ts

@@ -0,0 +1,86 @@
+import { WordStructureTransformer } from './word-structure-transformer';
+/**
+ * Normalizes Word image markup into plain <img> tags, drops list-marker images,
+ * and optionally remaps image source paths.
+ */
+export declare class WordImageTransformer implements WordStructureTransformer {
+  /** @inheritDoc */
+  getAllowedTags(): string[];
+  /** @inheritDoc */
+  getAllowedAttributes(): Map<string, string[]>;
+  /** @inheritDoc */
+  getAllowedStyles(): string[];
+  /** @inheritDoc */
+  apply(root: HTMLElement): void;
+  /**
+   * Lifts images out of text-style blocks (`h1`-`h6`, Word title / subtitle
+   * paragraphs) so they become standalone top-level images.
+   *
+   * The RTE data model represents these blocks as text blocks whose children
+   * are text nodes only, so an `<img>` nested inside one has no text-node
+   * representation and would be silently dropped during DTO conversion. Moving
+   * each image to a sibling position right after its block lets the downstream
+   * image-block strategies pick it up. Images are re-inserted in document order
+   * so they stay aligned with the RTF files paired later.
+   *
+   * Word title / subtitle paragraphs still carry their raw `MsoTitle` /
+   * `MsoSubtitle` class here because {@link WordParagraphRoleTransformer} runs
+   * after this transformer.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private liftImagesOutOfTextStyleBlocks;
+  /**
+   * Reports whether a block hosts its images as text-only children, requiring
+   * nested images to be lifted out: any heading (`h1`-`h6`) or a Word title /
+   * subtitle paragraph.
+   *
+   * @param {HTMLElement} element Candidate block element.
+   * @returns {boolean} `true` when nested images must be lifted out of the block.
+   */
+  private isImageLiftTargetBlock;
+  /**
+   * Converts Word VML `v:imagedata` elements to plain `<img>` elements.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private normalizeWordImageDataElements;
+  /**
+   * Removes non-VML fallback images that reference a specific Word VML shape id.
+   *
+   * Word clipboard HTML often includes both `v:imagedata` and an `<img v:shapes="...">`
+   * fallback for the same visual image. Once VML is normalized, the fallback must
+   * be removed to avoid duplicated image handling.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   * @param {string} shapeId VML shape id referenced by fallback images.
+   */
+  private removeFallbackImagesForShapeId;
+  /**
+   * Removes list-marker images and sourceless `<img>` elements.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private normalizeStandardImages;
+  /**
+   * Inserts an empty `<span> </span>` between adjacent images to avoid
+   * downstream image-block parsing treating a compact image run as a single image.
+   *
+   * @param {HTMLElement} root Parsed Word fragment root.
+   */
+  private insertSpanBetweenAdjacentImages;
+  /**
+   * Currently the RTE does not support list images, so they must be removed from the paste content.
+   * Local (file://) list images are kept as placeholders here and removed later during preview pairing
+   * so the local images stay aligned with the RTF images; non-local list images are removed immediately.
+   * Returns true when the image is part of list content and should be ignored.
+   *
+   * Word list markup (`MsoListParagraph` / `mso-list`) is already normalized into
+   * real `li/ul/ol` by {@link WordListRoleTransformer}, which runs before this
+   * transformer, so a plain list-ancestor check is sufficient here.
+   *
+   * @param {Element} element Image element (or its wrapper).
+   * @returns {boolean} Whether this image belongs to list content.
+   */
+  private isListImage;
+}