@globalpayments/vega 2.98.0 → 2.100.0

package/dist/types/components/vega-rich-text-editor/extensions/functions/utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Returns true when the element belongs to function extension blocks by semantic
+ * boundary attribute or known function element classes.
+ *
+ * Use this helper for broad detection (e.g., extension-level boundary predicate
+ * registration) where both container and child function elements should be
+ * treated as part of the function block structure.
+ *
+ * @param {HTMLElement} element - Element to inspect.
+ * @returns {boolean} Whether the element belongs to a function block structure.
+ * @example
+ * this.registerBlockBoundaryPredicate(isFunctionBlockElement);
+ */
+export declare const isFunctionBlockElement: (element: HTMLElement) => boolean;
+/**
+ * Returns true when the element is a function block boundary container.
+ *
+ * Use this helper when conversion logic must identify only the function block
+ * container element (the DIV that maps to RTEFunctionBlock), not function child
+ * elements such as syntax/content nodes.
+ *
+ * @param {HTMLElement} element - Element to inspect.
+ * @returns {boolean} Whether the element is a function block boundary container.
+ * @example
+ * if (isFunctionBoundaryContainer(element)) {
+ *     // map the DIV to RTEFunctionBlock
+ * }
+ */
+export declare const isFunctionBoundaryContainer: (element: HTMLElement) => boolean;

package/dist/types/components/vega-rich-text-editor/extensions/line-height/line-height-toolbar-button-renderer.d.ts

@@ -1,5 +1,5 @@
 import { VegaRTELineHeightOption } from '../type';
-import { VegaRTECreateElementFunction, VegaRTERenderResult, VegaRTEToolbarRenderContext } from '../../interface';
+import { RTEDropdownListItem, VegaRTECreateElementFunction, VegaRTERenderResult, VegaRTEToolbarRenderContext } from '../../interface';
 import { VegaRTEToolbarButtonRenderer } from '../base-toolbar-button-renderer';
 /**
  * Renderer for the line-height toolbar button in the Vega Rich Text Editor.
@@ -11,6 +11,19 @@ export declare class RTELineHeightToolbarButtonRenderer extends VegaRTEToolbarBu
    * @inheritDoc
    */
   render(createElement: VegaRTECreateElementFunction, editorContext: VegaRTEToolbarRenderContext): VegaRTERenderResult;
+  /**
+   * Renders each line-height option with its label as light-DOM children rather than the
+   * `label` prop. This gives the focusable menuitem a light-DOM text anchor so Safari
+   * VoiceOver's reading cursor follows focus into the item (Ctrl+Opt+Right walks item→item
+   * instead of escaping to the next toolbar button).
+   *
+   * The label is wrapped in a `<span>` (not a bare text node) so a click targeting the label
+   * lands on a slotted element that composes into the item's shadow `<li>`; a bare text node
+   * resolves to the `vega-dropdown-item` host, whose click never reaches the shadow handler.
+   *
+   * @inheritDoc
+   */
+  protected renderDropdownItem(h: VegaRTECreateElementFunction, item: RTEDropdownListItem, editorContext: VegaRTEToolbarRenderContext): VegaRTERenderResult;
   /**
    * @inheritDoc
    */

package/dist/types/components/vega-rich-text-editor/extensions/paste/action-handler-strategies/image-replace-src-strategy.d.ts

@@ -0,0 +1,12 @@
+import { ActionHandleStrategy } from '../../../dto/action-handle-strategies/action-handle-strategy.abstract';
+import { RTEImageNode } from '../../../dto/nodes/image-node';
+import { ImageReplaceSrcAction } from '../actions/image-replace-src-action';
+/**
+ * Strategy to handle the `ImageReplaceSrcAction` for replacing the `src` attribute of an `<img>` element in the RTE content.
+ */
+export declare class ImageReplaceSrcStrategy extends ActionHandleStrategy<ImageReplaceSrcAction, RTEImageNode> {
+  /**
+   * @inheritDoc
+   */
+  protected handleAction(action: ImageReplaceSrcAction, target: RTEImageNode): void;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/actions/image-replace-src-action.d.ts

@@ -0,0 +1,11 @@
+import { ModifyContentAction } from '../../../dto/actions/modify-content-action.abstract';
+export declare const REPLACE_IMAGE_SRC: string;
+/**
+ * Action to replace the `src` attribute of an `<img>` element in the RTE content.
+ */
+export declare class ImageReplaceSrcAction extends ModifyContentAction {
+  type: string;
+  img: HTMLImageElement;
+  url: string;
+  constructor(imageElement: HTMLImageElement, url: string);
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/parse-local-images-helper/paste-image-parser.d.ts

@@ -0,0 +1,136 @@
+import { ClipboardFileContent, VegaRTEPasteImage } from '../paste-extension';
+/**
+ * A pasted image whose upload is still pending: the public
+ * {@link VegaRTEPasteImage} payload plus the local object URL currently used as
+ * its preview `src`.
+ */
+export declare type PasteImagePreview = VegaRTEPasteImage & {
+  /** Local object URL used as the temporary preview source. */
+  objectUrl: string;
+};
+export declare type ParseLocalImagesResult = {
+  /** Rewritten HTML with `<img>` elements swapped to local object-URL previews. */
+  html: string;
+  /** Previews for the images that were resolved to a file. */
+  previews: PasteImagePreview[];
+};
+/**
+ * Extracts pasted image files from clipboard payloads and swaps matching
+ * `<img>` elements to local object-URL previews.
+ *
+ * The parser is stateless: callers own the returned {@link PasteImagePreview}
+ * list and decide how to track pending uploads.
+ */
+export declare class PasteImageParser {
+  static PREVIEW_IMG_KEY: string;
+  /**
+   * Parses local `file://` images from the HTML, swaps matching `<img>`
+   * elements to object-URL previews, and returns the rewritten HTML alongside
+   * the resolved pending previews.
+   *
+   * When no local images are resolved, the original HTML is returned unchanged
+   * with an empty preview list.
+   *
+   * @param {string} html HTML content to parse.
+   * @param {ClipboardFileContent | null} clipboardFileContent Clipboard payload for image extraction.
+   * @returns {ParseLocalImagesResult} Rewritten HTML and resolved previews.
+   */
+  parseLocalImages(html: string, clipboardFileContent: ClipboardFileContent | null): ParseLocalImagesResult;
+  /**
+   * Swaps each `<img>` src to a local object-URL preview using the provided
+   * image files (paired by order), returning one preview per resolved image.
+   *
+   * Images that live inside a list are dropped instead of being previewed: the
+   * RTE does not support list images. They are removed here (after holding their
+   * position while the RTF images are paired by order) so the remaining images
+   * stay aligned with their files even when a list image is not the last one.
+   *
+   * @param {HTMLImageElement[]} images Placeholder `<img>` elements in document order.
+   * @param {File[]} files Image files to pair with the elements, in the same order.
+   * @returns {PasteImagePreview[]} Previews for the images that were resolved to a file.
+   */
+  createImagePreviews(images: HTMLImageElement[], files: File[]): PasteImagePreview[];
+  /**
+   * Extracts image files from clipboard data, preferring Word RTF-decoded
+   * images and falling back to the clipboard file list when RTF yields none.
+   *
+   * @param {ClipboardFileContent | null} clipboardFileContent Clipboard payload from a paste event.
+   * @param {HTMLElement[]} images `<img>` elements the files will be paired with.
+   * @returns {File[]} Image files found on the clipboard.
+   */
+  extractImageFiles(clipboardFileContent: ClipboardFileContent | null, images: HTMLElement[]): File[];
+  /**
+   * Safely extracts image files from Word RTF clipboard data.
+   *
+   * @param {string} rtf Clipboard payload from a paste event.
+   * @param {HTMLElement[]} images Array of `<img>` elements that may be updated with staged previews.
+   * @returns {File[]} Image files found in the clipboard data.
+   */
+  private safeExtractWordImages;
+  /**
+   * Removes Word list-table picture-bullet definitions from the RTF so they are
+   * not counted as content images.
+   *
+   * Word declares a list's picture bullet once as a `{\*\listpicture ...}`
+   * destination inside the list table. It renders nothing on its own, so its
+   * blip has no matching content `<img>`; leaving it in shifts the ordinal
+   * pairing and makes the first real image resolve to the bullet. The per-item
+   * `{\listtext ...}` bullets are intentionally left untouched because each is
+   * kept as a placeholder `<img>` that consumes its blip downstream.
+   *
+   * @param {string} rtf Full RTF clipboard payload.
+   * @returns {string} RTF with list-table picture-bullet definitions removed.
+   */
+  private stripListPictureDefinitions;
+  /**
+   * Removes every balanced-brace RTF group that starts with the given marker.
+   *
+   * @param {string} rtf RTF payload to scan.
+   * @param {string} marker Opening delimiter of the group to remove (including its `{`).
+   * @returns {string} RTF with the matching groups removed.
+   */
+  private removeBalancedGroups;
+  /**
+   * Finds the index just past the brace that closes the group opened at `start`.
+   *
+   * A backslash escapes the next character (such as `\{` or `\}`) so escaped
+   * braces are not counted. When the group is unbalanced the RTF length is
+   * returned so the trailing remainder is dropped.
+   *
+   * @param {string} rtf RTF payload to scan.
+   * @param {number} start Index of the group's opening `{`.
+   * @returns {number} Index immediately after the matching closing `}`.
+   */
+  private findGroupEnd;
+  /**
+   * Extracts the raw image bytes that follow a Word RTF blip marker.
+   *
+   * Starting just after the blip control word, RTF control words (such as
+   * `\bliptag`) and nested groups (such as `{\*\blipuid ...}`) are skipped so
+   * their hex is not mistaken for image data. Hex digits are decoded into bytes
+   * until the enclosing `{\pict}` group is closed.
+   *
+   * @param {string} rtf Full RTF clipboard payload.
+   * @param {number} startIndex Index immediately after the blip marker.
+   * @returns {number[]} Decoded image byte values.
+   */
+  private extractImageBytes;
+  /**
+   * Converts a single hex character to its numeric value.
+   *
+   * @param {string} char Candidate hex character.
+   * @returns {number} Value in `[0, 15]`, or `-1` when not a hex digit.
+   */
+  private hexNibble;
+  /**
+   * Returns whether an `<img>` element is nested inside list content.
+   *
+   * The Word paste sanitizer strips non-allowlisted attributes but keeps the
+   * `ul`/`ol`/`li` structure, so list membership is detected by DOM ancestry
+   * here rather than by a marker attribute set upstream.
+   *
+   * @param {HTMLImageElement} imageElement Image element to test.
+   * @returns {boolean} Whether the image is part of list content.
+   */
+  private isListImage;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/parse-local-images-helper/pending-image-registry.d.ts

@@ -0,0 +1,68 @@
+import { RTEImageNode } from '../../../dto/nodes/image-node';
+import { PasteImagePreview } from './paste-image-parser';
+import type { VegaRTEPasteImage } from '../paste-extension';
+/** Consumer callback invoked once pasted images are inserted into the editor. */
+export declare type ImageInsertedCallback = (images: VegaRTEPasteImage[], replaceUrl: (imageId: string, url: string) => void) => void;
+/** Resolves the editable content element currently backing the editor. */
+export declare type GetEditableElement = () => HTMLDivElement | null;
+/** Resolves the image DTO node for a live preview `<img>` element. */
+export declare type ResolveImageNode = (imageElement: HTMLImageElement) => RTEImageNode | null;
+/**
+ * Owns the lifecycle of pasted images awaiting upload: it tracks their local
+ * object-URL previews, notifies the consumer once they are inserted, applies the
+ * uploaded URL back onto the live preview, and revokes object URLs on teardown.
+ *
+ * Keeping this state here rather than on the paste extension keeps the extension
+ * focused on clipboard capture and the chooser UI.
+ */
+export declare class PendingImageRegistry {
+  /**
+   * Pasted images awaiting upload, keyed by their {@link VegaRTEPasteImage.id}.
+   *
+   * Shared statically across instances so previews survive a paste-extension
+   * re-instantiation: the consumer may resolve `replaceUrl` after the editor
+   * has re-mounted and created a new extension/registry instance.
+   */
+  private static readonly pendingImages;
+  /** Ids of pending images still holding an object URL owned by this registry. */
+  private readonly ownedImageIds;
+  /** Ids queued for the next {@link notifyInserted} call. */
+  private pendingNotifyImageIds;
+  /**
+   * Registers freshly created previews so they can be notified and later
+   * resolved to their uploaded URLs.
+   *
+   * @param {PasteImagePreview[]} previews Previews produced for the current paste.
+   */
+  register(previews: PasteImagePreview[]): void;
+  /**
+   * @returns {boolean} Whether previews are queued for notification.
+   */
+  hasPendingNotifications(): boolean;
+  /**
+   * Notifies the consumer about newly inserted pasted images so they can upload
+   * them and fill in the real URLs via the supplied `replaceUrl` callback.
+   *
+   * @param {ImageInsertedCallback | undefined} callback Consumer callback to invoke.
+   * @param {GetEditableElement} getEditableElement Resolves the live editable element.
+   * @param {ResolveImageNode} resolveImageNode Resolves the DTO node for a preview element.
+   */
+  notifyInserted(callback: ImageInsertedCallback | undefined, getEditableElement: GetEditableElement, resolveImageNode: ResolveImageNode): void;
+  /**
+   * Revokes and forgets only previews that were never handed to a consumer for
+   * upload. Previews already notified via {@link notifyInserted} are left intact
+   * so an async {@link replaceUrl} can still resolve them after the extension is
+   * recreated; that callback owns their teardown.
+   */
+  discardUnsentPreviews(): void;
+  /**
+   * Applies the uploaded URL for a pending pasted image, replacing its local
+   * preview `src` and revoking the object URL.
+   *
+   * @param {string} imageId Pending image id supplied to the consumer callback.
+   * @param {string} url Uploaded image URL to apply.
+   * @param {GetEditableElement} getEditableElement Resolves the live editable element.
+   * @param {ResolveImageNode} resolveImageNode Resolves the DTO node for a preview element.
+   */
+  private replaceUrl;
+}

package/dist/types/components/vega-rich-text-editor/extensions/paste/paste-chooser-ui.d.ts

@@ -1,11 +1,14 @@
-export declare type PasteMode = 'rich';
+import { RTEPasteMode } from './strategies/paste-processing-strategy.abstract';
 export declare type PasteChooserPosition = {
   left: number;
   top: number;
   placement: ['bottom', 'top'] | ['top', 'bottom'];
 };
 export declare type PasteChooserCallbacks = {
-  onModeSelect: (mode: PasteMode) => void;
+  onModeSelect: (mode: RTEPasteMode) => void;
+};
+export declare type PasteChooserOptions = {
+  showWordOption?: boolean;
 };
 /**
  * Renders and manages the paste format chooser UI.
@@ -13,13 +16,15 @@ export declare type PasteChooserCallbacks = {
 export declare class RTEPasteChooserUI {
   private readonly hostRoot;
   private readonly callbacks;
+  private readonly options;
   static readonly CHOOSER_ATTR: string;
   static readonly CHOOSER_RICH_ATTR: string;
+  static readonly CHOOSER_WORD_ATTR: string;
   static readonly CHOOSER_TRIGGER_ATTR: string;
   private chooserEl;
   private dropdownEl;
   private triggerButtonEl;
-  constructor(hostRoot: ShadowRoot, callbacks: PasteChooserCallbacks);
+  constructor(hostRoot: ShadowRoot, callbacks: PasteChooserCallbacks, options?: PasteChooserOptions);
   /**
    * Opens the paste-mode chooser at the given position.
    *
@@ -49,7 +54,7 @@ export declare class RTEPasteChooserUI {
    * Creates a single dropdown item element for a paste mode.
    *
    * @param {Document} doc Document used to create the element.
-   * @param {PasteMode} key Paste mode key for the item.
+   * @param {RTEPasteMode} key Paste mode key for the item.
    * @param {string} label Display label for the item.
    * @param {string} dataAttrName Data attribute marker for the item.
    * @returns {HTMLVegaDropdownItemElement} Configured dropdown item element.

package/dist/types/components/vega-rich-text-editor/extensions/paste/paste-extension.d.ts

@@ -1,5 +1,19 @@
 import { VegaRTEExtension } from '../extension.abstract';
 import { RTEExtensionContext } from '../../interface';
+export declare type ClipboardFileContent = {
+  files: File[];
+  rtf: string;
+};
+export declare type VegaRTEPasteImage = {
+  /** Unique identifier used to fill in the uploaded URL later. */
+  id: string;
+  /** Pasted image file to upload. */
+  file: File;
+};
+export declare type VegaRTEPasteExtensionOptions = {
+  enableWordPaste?: boolean;
+  imageInsertedCallback?: (images: VegaRTEPasteImage[], replaceUrl: (imageId: string, url: string) => void) => void;
+};
 /**
  * Vega Rich Text Editor paste extension.
  * Intercepts keyboard paste and allows users to choose paste mode.
@@ -12,6 +26,13 @@ export declare class VegaRTEPasteExtension extends VegaRTEExtension {
   private pendingPastePayload;
   private listenerDocument;
   private listenerWindow;
+  private options;
+  private strategySelector;
+  private clipboardFileContent;
+  private imageParser;
+  /** Owns pending pasted-image previews awaiting upload and their URL replacement. */
+  private readonly pendingImageRegistry;
+  constructor(options?: VegaRTEPasteExtensionOptions);
   /** @inheritDoc */
   initialExtensionAfterLoad(context: RTEExtensionContext): void;
   /** @inheritDoc */
@@ -109,9 +130,25 @@ export declare class VegaRTEPasteExtension extends VegaRTEExtension {
   /**
    * Applies the chosen paste mode by dispatching a synthetic paste input event.
    *
-   * @param {PasteMode} mode Selected paste mode.
+   * `rich` keeps auto-detection enabled; any other explicit mode forces the
+   * corresponding registered strategy.
+   *
+   * @param {RTEPasteMode} mode Selected paste mode.
    */
   private applyPasteMode;
+  /**
+   * Parses local images from the HTML and emits events for further processing.
+   *
+   * @param {string} html HTML content to parse.
+   * @param {ClipboardFileContent} clipboardFileContent Clipboard file content for image extraction.
+   * @returns {string} Processed HTML with local image references replaced.
+   */
+  private parseLocalImages;
+  /**
+   * Emits the `imageInsertedCallback` for any pending previews, allowing the
+   * consumer to upload them and resolve their URLs.
+   */
+  private emitLocalImageInsertedEvent;
   /**
    * Restores SelectionController state from the captured selection so synthetic
    * beforeinput paste can replace the selected content instead of appending.
@@ -137,7 +174,7 @@ export declare class VegaRTEPasteExtension extends VegaRTEExtension {
    *
    * @param {string} html HTML clipboard content.
    * @param {string} text Plain text clipboard content.
-   * @param {PasteMode} [mode] Selected paste mode marker.
+   * @param {RTEPasteMode} [mode] Selected paste mode marker.
    * @returns {DataTransfer} Populated data transfer payload.
    */
   private createDataTransfer;

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;
+}