@globalpayments/vega 2.91.0 → 2.92.0

package/dist/collection/components/vega-rich-text-editor/extensions/cut/cut-toolbar-button-renderer.js

@@ -0,0 +1,44 @@
+import { VegaInternalIconManager } from '../../../../helpers/icon/internal-icon-manager';
+import { RTECopyToolbarButtonRenderer } from '../copy/copy-toolbar-button-renderer';
+import cutIcon from '../../assets/cut';
+import { CopySelectedContentAction } from '../copy/actions/copy-selected-content-action';
+import { DeleteSelectedContentAction } from '../../dto/actions/delete-selected-content-action';
+/**
+ * Toolbar button renderer for the Cut extension.
+ * Reuses the Copy renderer to write the selected editor content to the clipboard,
+ * then removes the selected content from the editor.
+ */
+export class RTECutToolbarButtonRenderer extends RTECopyToolbarButtonRenderer {
+  /**
+   * Renders the cut toolbar button.
+   *
+   * @param {VegaRTECreateElementFunction} h - Create element function.
+   * @param {VegaRTEToolbarRenderContext} editorContext - The render context for the editor.
+   * @returns {VegaRTERenderResult} - The toolbar button render result.
+   */
+  render(h, editorContext) {
+    return this.renderButton(h, editorContext, {
+      icon: 'rte-cut',
+      tooltip: { text: 'Cut' },
+    });
+  }
+  /**
+   * Handles the cut button click event.
+   * Copies the current editor selection to the clipboard and then deletes it from the editor.
+   *
+   * @param {VegaRTEToolbarRenderContext} editorContext - The render context for the editor.
+   */
+  async handleButtonClick(editorContext) {
+    const context = this.getExtensionContext(editorContext.host);
+    if (context && context.host) {
+      const { host } = context;
+      const copySelectedContentAction = new CopySelectedContentAction(context.getSelection(), context.getSelectedNodes());
+      host.value.apply(copySelectedContentAction);
+      const isCopySuccessful = await copySelectedContentAction.copyResult;
+      isCopySuccessful && host.value.apply(new DeleteSelectedContentAction(host, true, true));
+    }
+  }
+}
+(() => {
+  VegaInternalIconManager.register({ 'rte-cut': cutIcon });
+})();

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/assets/find-and-replace.js

@@ -0,0 +1,3 @@
+export default {
+  icon: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Pro 7.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license (Commercial License) Copyright 2026 Fonticons, Inc. --><path fill="currentColor" d="M208 48c39.6 0 75.9 14.4 103.8 38.2L279 119c-6.9 6.9-8.9 17.2-5.2 26.2S286.3 160 296 160l96 0c13.3 0 24-10.7 24-24l0-96c0-9.7-5.8-18.5-14.8-22.2S381.9 16.2 375 23L345.8 52.2c-36.7-32.5-85-52.2-137.8-52.2-99.4 0-182.4 69.7-203.1 162.8-2.9 12.9 5.3 25.8 18.2 28.6 1.4 .3 2.7 .5 4.1 .5l2.3 0C40.1 191.5 49.4 184 51.8 173.2 67.7 101.6 131.6 48 208 48zM386 224c-10.4 .7-19.4 8.1-21.8 18.8-15.9 71.7-79.8 125.2-156.2 125.2-39.6 0-75.9-14.4-103.8-38.2L137 297c6.9-6.9 8.9-17.2 5.2-26.2S129.7 256 120 256l-96 0c-13.3 0-24 10.7-24 24l0 96c0 9.7 5.8 18.5 14.8 22.2S34.1 399.8 41 393l29.2-29.2c36.7 32.5 85 52.2 137.8 52.2 48.8 0 93.7-16.8 129.1-44.9L471 505c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9L371.1 337.1c19.2-24.2 33.1-52.8 40-84 2.9-12.9-5.3-25.8-18.2-28.6-1.2-.3-2.4-.4-3.6-.5l-3.2 0z"/></svg>`,
+};

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/find-replace-extension.js

@@ -0,0 +1,18 @@
+import { VegaRTEExtension } from '../extension.abstract';
+import { FindReplaceToolbarButtonRenderer } from './slimmer/renderers/find-replace-toolbar-button-renderer';
+/**
+ * Find & Replace extension for Vega Rich Text Editor.
+ *
+ * Registers a toolbar button (magnifying-glass icon) that toggles the find-replace panel.
+ * Each editor host gets its own isolated FindReplaceState and toolbar renderer instance,
+ * created during the per-host prepareBeforeLoad lifecycle hook.
+ *
+ * Toolbar key: 'findReplace'
+ */
+export class VegaRTEFindReplaceExtension extends VegaRTEExtension {
+  /** @inheritDoc */
+  prepareBeforeLoad(host) {
+    this.registerToolbarButtonRenderer(VegaRTEFindReplaceExtension.TOOLBAR_BUTTON_KEY, new FindReplaceToolbarButtonRenderer(), host);
+  }
+}
+VegaRTEFindReplaceExtension.TOOLBAR_BUTTON_KEY = 'findReplace';

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/find-controller.js

@@ -0,0 +1,105 @@
+import { FindReplaceControllerAbstract, } from './find-replace-controller.abstract';
+/**
+ * Concrete find controller.
+ *
+ * Provides search, navigation, highlight, and lifecycle capabilities.
+ * Shares state with {@link ReplaceController} via the injected
+ * {@link FindReplaceControllerContext}.
+ */
+export class FindController extends FindReplaceControllerAbstract {
+  constructor(context) {
+    super(context);
+  }
+  /**
+   * Runs a search with the current keyword on the host's content.
+   * Applies highlights and returns the result for panel display.
+   *
+   * @returns {FindReplaceResult} The match count and current position.
+   */
+  find() {
+    if (!this.context.hostRef) {
+      return { current: 0, total: 0 };
+    }
+    this.context.state.search(this.context.hostRef.value, this.context.keyword);
+    return this.applyAndGetResult();
+  }
+  /**
+   * Navigates to the next match.
+   *
+   * @returns {FindReplaceResult} Updated position.
+   */
+  next() {
+    this.context.state.next();
+    return this.applyAndGetResult();
+  }
+  /**
+   * Navigates to the previous match.
+   *
+   * @returns {FindReplaceResult} Updated position.
+   */
+  prev() {
+    this.context.state.prev();
+    return this.applyAndGetResult();
+  }
+  /**
+   * Clears all search state and removes highlight overlays.
+   */
+  clear() {
+    this.context.state.clear();
+    if (this.context.hostRef) {
+      this.context.highlightManager.clear();
+    }
+  }
+  /**
+   * Re-runs the search after content has changed (e.g. user typed while
+   * panel is open). Attempts to preserve the previous navigation position.
+   *
+   * @param {boolean} scrollToActive - Whether to scroll the active highlight into view.
+   * @returns {FindReplaceResult | null} Updated result, or null if no search is active.
+   */
+  refresh(scrollToActive = true) {
+    if (!this.context.keyword || !this.context.hostRef) {
+      return null;
+    }
+    const prevIndex = this.context.state.getCurrentIndex();
+    this.context.state.search(this.context.hostRef.value, this.context.keyword);
+    this.context.state.setCurrentIndex(prevIndex);
+    return this.applyAndGetResult(scrollToActive);
+  }
+  /**
+   * Toggles the match-case search option, clears previous results,
+   * and re-runs the search if a keyword is set.
+   *
+   * @param {boolean} enabled - Whether match-case should be enabled.
+   * @returns {FindReplaceResult} The updated search result.
+   */
+  setMatchCase(enabled) {
+    this.context.state.setMatchCase(enabled);
+    return this.updateFindResults();
+  }
+  /**
+   * Toggles the whole-words search option, clears previous results,
+   * and re-runs the search if a keyword is set.
+   *
+   * @param {boolean} enabled - Whether whole-words should be enabled.
+   * @returns {FindReplaceResult} The updated search result.
+   */
+  setWholeWords(enabled) {
+    this.context.state.setWholeWords(enabled);
+    return this.updateFindResults();
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────────
+  /**
+   * Clears previous results and re-runs the search with the current keyword and options.
+   *
+   * @returns {FindReplaceResult} The updated search result.
+   */
+  updateFindResults() {
+    this.context.state.clearResults();
+    if (this.context.keyword && this.context.hostRef) {
+      this.context.state.search(this.context.hostRef.value, this.context.keyword);
+      return this.applyAndGetResult();
+    }
+    return { current: 0, total: 0 };
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/find-replace-controller.abstract.js

@@ -0,0 +1,68 @@
+import { FindReplaceState } from './helper/find-replace-state';
+import { FindReplaceHighlightManager } from './helper/find-replace-highlight-manager';
+/**
+ * Creates a new shared controller context with default (empty) state.
+ *
+ * @returns {FindReplaceControllerContext} A fresh context instance.
+ */
+export function createFindReplaceControllerContext() {
+  return {
+    state: new FindReplaceState(),
+    highlightManager: new FindReplaceHighlightManager(),
+    hostRef: null,
+    keyword: '',
+  };
+}
+/**
+ * Abstract base controller for the Find & Replace extension.
+ *
+ * Holds shared operations ({@link setHost}, {@link setKeyword}) and the
+ * common helper {@link applyAndGetResult}. Concrete implementations
+ * ({@link FindController}, {@link ReplaceController}) add the respective
+ * search/navigation and mutation capabilities.
+ */
+export class FindReplaceControllerAbstract {
+  constructor(context) {
+    this.context = context;
+  }
+  /**
+   * Updates the cached host reference. Called on each render cycle.
+   *
+   * @typedef HTMLVegaRichTextEditorElement - The type of the host rich text editor element.
+   * @param {HTMLVegaRichTextEditorElement} host - The RTE host element.
+   */
+  setHost(host) {
+    this.context.hostRef = host;
+  }
+  /**
+   * Updates the keyword. Clears previous match results and highlights,
+   * but preserves the flat-text cache so the next find() on the same
+   * document does not re-flatten every block.
+   *
+   * @param {string} keyword - The new search keyword.
+   * @returns {FindReplaceResult} Reset result (0/0).
+   */
+  setKeyword(keyword) {
+    this.context.keyword = keyword;
+    this.context.state.clearResults();
+    if (this.context.hostRef) {
+      this.context.highlightManager.clear();
+    }
+    return { current: 0, total: 0 };
+  }
+  // ─── Protected ────────────────────────────────────────────────────────────────
+  /**
+   * Applies highlight overlays and returns the current result for the panel.
+   *
+   * @param {boolean} scrollToActive - Whether to scroll the active highlight into view.
+   * @returns {FindReplaceResult} The current match position and total count.
+   */
+  applyAndGetResult(scrollToActive = true) {
+    const total = this.context.state.getTotal();
+    const current = total > 0 ? this.context.state.getCurrentIndex() + 1 : 0;
+    if (this.context.hostRef) {
+      this.context.highlightManager.apply(this.context.state.getMatches(), this.context.state.getCurrentIndex(), this.context.hostRef, scrollToActive);
+    }
+    return { current, total };
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/block-search-strategy.abstract.js

@@ -0,0 +1,8 @@
+/**
+ * Defines how a specific type of RTEBlock contributes searchable leaf blocks.
+ *
+ * Implementations are registered on FindReplaceState in priority order.
+ * The first strategy whose `canHandle` returns true is used.
+ */
+export class BlockSearchStrategy {
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/code-block-search-strategy.js

@@ -0,0 +1,19 @@
+import { RTECodeBlock } from '../../../../../../dto/blocks/code-block';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Handles RTECodeBlock — a searchable leaf block whose text lives in children[0].text.
+ */
+export class CodeBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return block instanceof RTECodeBlock;
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block) {
+    return [block];
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/container-block-search-strategy.js

@@ -0,0 +1,23 @@
+import { RTETextNode } from '../../../../../../dto/nodes/text-node';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Fallback strategy for generic container blocks whose concrete type is not
+ * known at compile time (RTEHtmlBlock, table blocks, extension-defined blocks, …).
+ *
+ * A block is treated as a container when its children array is non-empty and
+ * the first child is not an RTETextNode (i.e. children are blocks, not nodes).
+ */
+export class ContainerBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return (block.children != null && block.children.length > 0 && !(block.children[0] instanceof RTETextNode));
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block, recurse) {
+    return recurse(block.children);
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/list-item-block-search-strategy.js

@@ -0,0 +1,30 @@
+import { RTEListItemBlock } from '../../../../../../dto/blocks/list-item-block';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Handles RTEListItemBlock — a searchable leaf block that may also carry
+ * nested RTEListBlocks via its `nestList` property.
+ *
+ * Must be registered before TextBlockSearchStrategy because RTEListItemBlock
+ * extends RTETextBlock and would otherwise be matched by the parent class check.
+ */
+export class ListItemBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return block instanceof RTEListItemBlock;
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block, recurse) {
+    const listItemBlock = block;
+    const result = [listItemBlock];
+    if (listItemBlock.nestList && listItemBlock.nestList.length > 0) {
+      for (const nestedList of listItemBlock.nestList) {
+        result.push(...recurse(nestedList.children));
+      }
+    }
+    return result;
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/block-search-strategies/text-block-search-strategy.js

@@ -0,0 +1,20 @@
+import { RTETextBlock } from '../../../../../../dto/blocks/text-block';
+import { BlockSearchStrategy } from './block-search-strategy.abstract';
+/**
+ * Handles plain RTETextBlock (paragraph, heading, etc.) — a searchable leaf
+ * block whose text lives in its RTETextNode children.
+ */
+export class TextBlockSearchStrategy extends BlockSearchStrategy {
+  /**
+   * @inheritDoc
+   */
+  canHandle(block) {
+    return block instanceof RTETextBlock;
+  }
+  /**
+   * @inheritDoc
+   */
+  collect(block) {
+    return [block];
+  }
+}

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/controllers/helper/find-replace-highlight-manager.js

@@ -0,0 +1,266 @@
+import stateEntityRenderingRegistry from '../../../../../slimmers/controllers/state-entity-rendering-registry';
+import { tryGetDocument } from '../../../../../../../utils/try-get-document';
+import { RTECodeBlockNode } from '../../../../../dto/nodes/code-block-node';
+import { VegaDarkModeStyleController } from '../../../../../../../helpers/theme/controllers/dark-mode-style-controller';
+// Light-mode values (used as CSS var() fall-backs).
+// Dark-mode values are registered via VegaDarkModeStyleController below.
+const HIGHLIGHT_BG_LIGHT = '255, 220, 0, 0.35';
+const HIGHLIGHT_ACTIVE_BG_LIGHT = '255, 150, 0, 0.5';
+// Dark-mode: brighter yellow/orange tones stand out on dark backgrounds.
+const HIGHLIGHT_BG_DARK = '255, 235, 0, 0.55';
+const HIGHLIGHT_ACTIVE_BG_DARK = '255, 190, 0, 0.7';
+// CSS var() expressions that auto-switch between light and dark.
+const HIGHLIGHT_BG = `rgba(var(--v-rte-find-highlight-bg, ${HIGHLIGHT_BG_LIGHT}))`;
+const HIGHLIGHT_ACTIVE_BG = `rgba(var(--v-rte-find-highlight-active-bg, ${HIGHLIGHT_ACTIVE_BG_LIGHT}))`;
+/**
+ * Manages highlights for the Find & Replace extension using a DOM overlay.
+ *
+ * Instead of modifying the RTE content tree (which causes re-renders, cursor
+ * jumping, and VegaChange events), this manager renders semi-transparent
+ * highlight rectangles in an absolutely-positioned overlay container.
+ *
+ * The overlay lives inside `.rich-text-editor-container` (the RTE's scroll
+ * container) so highlight divs scroll naturally with the text content.
+ * `pointer-events: none` ensures highlights don't interfere with user
+ * interaction (selection, typing, clicking).
+ *
+ * Position computation uses `Range.getClientRects()` on the actual text DOM
+ * nodes (resolved via `stateEntityRenderingRegistry.getDOMByEntity`).
+ */
+export class FindReplaceHighlightManager {
+  constructor() {
+    this.overlayContainer = null;
+    // Register dark-mode overrides so `html.dark { --v-rte-find-highlight-*: ... }` is generated.
+    // CSS variables cascade into shadow DOM and update automatically when html.dark is toggled.
+    VegaDarkModeStyleController.registerCustomDarkModeColor({
+      'rte-find-highlight-bg': HIGHLIGHT_BG_DARK,
+      'rte-find-highlight-active-bg': HIGHLIGHT_ACTIVE_BG_DARK,
+      'rte-find-highlight-blend': 'lighten',
+    });
+  }
+  /**
+   * Renders highlight overlays for all matches, with the active match
+   * visually distinct. Clears any existing highlights before applying.
+   *
+   * @typedef HTMLVegaRichTextEditorElement - The type of the host rich text editor element.
+   * @param {ReadonlyArray<FindMatch>} matches - All search results.
+   * @param {number} currentIndex - 0-based index of the active match (-1 = none).
+   * @param {HTMLVegaRichTextEditorElement} host - The RTE host element.
+   * @param {boolean} scrollToActive - Whether to scroll the active highlight into view.
+   */
+  apply(matches, currentIndex, host, scrollToActive = true) {
+    this.clear();
+    if (matches.length === 0) {
+      return;
+    }
+    const overlay = this.getOrCreateOverlay(host);
+    if (overlay) {
+      const overlayRect = overlay.getBoundingClientRect();
+      let activeHighlightDiv = null;
+      matches.forEach((match, matchIndex) => {
+        const isActive = matchIndex === currentIndex;
+        const bg = isActive ? HIGHLIGHT_ACTIVE_BG : HIGHLIGHT_BG;
+        match.nodes.forEach((nodePosition) => {
+          const highlightDiv = this.createHighlightRectangles(overlay, overlayRect, nodePosition, bg);
+          if (isActive && !activeHighlightDiv && highlightDiv) {
+            activeHighlightDiv = highlightDiv;
+          }
+        });
+      });
+      if (scrollToActive && activeHighlightDiv) {
+        activeHighlightDiv.scrollIntoView({ block: 'center', inline: 'nearest' });
+      }
+    }
+  }
+  /**
+   * Removes all highlight overlay elements.
+   * Safe to call multiple times or when no highlights are active.
+   */
+  clear() {
+    if (this.overlayContainer) {
+      this.overlayContainer.innerHTML = '';
+    }
+  }
+  // ─── Private helpers ──────────────────────────────────────────────────────────
+  /**
+   * Gets the existing overlay container or creates one inside the RTE's
+   * scroll container (`.rich-text-editor-container`).
+   *
+   * @typedef HTMLVegaRichTextEditorElement - The type of the host rich text editor element.
+   * @param {HTMLVegaRichTextEditorElement} host - The RTE host element.
+   * @returns {HTMLDivElement | null} The overlay container, or null in SSR environments.
+   */
+  getOrCreateOverlay(host) {
+    if (this.overlayContainer && this.overlayContainer.isConnected) {
+      return this.overlayContainer;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const scrollContainer = host.shadowRoot.querySelector('.rich-text-editor-container');
+      if (scrollContainer) {
+        // The overlay is appended as the last child (paints above content).
+        // Blend mode is controlled via CSS variable --v-rte-find-highlight-blend:
+        //   - Light (default): multiply (yellow darkens white bg, text readable)
+        //   - Dark (via html.dark override): lighten (yellow visible on dark bg,
+        //     white text unaffected since lighten(255, x) = 255)
+        // CSS vars cascade into shadow DOM and react to theme switches instantly.
+        const overlay = safeDocument.createElement('div');
+        overlay.style.position = 'absolute';
+        overlay.style.top = '0';
+        overlay.style.left = '0';
+        overlay.style.width = '100%';
+        overlay.style.height = '100%';
+        overlay.style.pointerEvents = 'none';
+        overlay.style.overflow = 'visible';
+        overlay.style.setProperty('mix-blend-mode', 'var(--v-rte-find-highlight-blend, multiply)');
+        scrollContainer.appendChild(overlay);
+        this.overlayContainer = overlay;
+        return overlay;
+      }
+    }
+    return null;
+  }
+  /**
+   * Creates absolutely-positioned highlight rectangles for a single node
+   * position within a match.
+   *
+   * Uses client rectangle extraction from `Range` to handle multi-line matches (where a
+   * single text range may produce multiple rectangles due to line wrapping).
+   *
+   * @param {HTMLDivElement} overlay - The overlay container.
+   * @param {DOMRect} overlayRect - The overlay's bounding client rect (for coordinate conversion).
+   * @param {NodePosition} nodePosition - The node and character offsets for this segment.
+   * @param {string} bg - The background color to apply.
+   * @returns {Nullable<HTMLDivElement>} The first created highlight div for this node segment.
+   */
+  createHighlightRectangles(overlay, overlayRect, nodePosition, bg) {
+    const domElement = stateEntityRenderingRegistry.getDOMByEntity(nodePosition.node);
+    if (!domElement) {
+      return null;
+    }
+    const range = this.buildRange(domElement, nodePosition);
+    if (!range) {
+      return null;
+    }
+    // eslint-disable-next-line spellcheck/spell-checker -- DOM API method name is fixed by platform.
+    const clientRectList = range.getClientRects();
+    const safeDocument = tryGetDocument();
+    let firstHighlightDiv = null;
+    if (safeDocument) {
+      for (let i = 0; i < clientRectList.length; i++) {
+        const rect = clientRectList[i];
+        if (rect.width === 0 || rect.height === 0) {
+          continue;
+        }
+        const div = safeDocument.createElement('div');
+        div.style.position = 'absolute';
+        div.style.top = `${rect.top - overlayRect.top}px`;
+        div.style.left = `${rect.left - overlayRect.left}px`;
+        div.style.width = `${rect.width}px`;
+        div.style.height = `${rect.height}px`;
+        div.style.backgroundColor = bg;
+        div.style.pointerEvents = 'none';
+        div.style.borderRadius = '2px';
+        overlay.appendChild(div);
+        if (!firstHighlightDiv) {
+          firstHighlightDiv = div;
+        }
+      }
+    }
+    return firstHighlightDiv;
+  }
+  /**
+   * Builds a DOM Range for the given node position.
+   *
+   * For standard text nodes (RTETextNode rendered as `<span>`), the first
+   * child is a Text node and offsets apply directly.
+   *
+   * For code block nodes (`<vega-code-block>` with shadow DOM), we traverse
+   * the shadow root's `<code>` element child spans to locate the correct
+   * text positions by accumulated character offset.
+   *
+   * @param {HTMLElement} domElement - The registered DOM element for the node.
+   * @param {NodePosition} nodePosition - The character offsets within the node.
+   * @returns {Nullable<Range>} A Range if successfully built, or null on failure.
+   */
+  buildRange(domElement, nodePosition) {
+    // <vega-code-block> wraps syntax-highlighted tokens inside a shadow root <code> element.
+    if (nodePosition.node instanceof RTECodeBlockNode) {
+      return this.buildCodeBlockRange(domElement, nodePosition);
+    }
+    // Standard text node: <span> with a direct Text child.
+    const textNode = domElement.firstChild;
+    if (!textNode) {
+      return null;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const range = safeDocument.createRange();
+      try {
+        range.setStart(textNode, nodePosition.startOffset);
+        range.setEnd(textNode, nodePosition.endOffset);
+        return range;
+      }
+      catch (_a) {
+        return null;
+      }
+    }
+    return null;
+  }
+  /**
+   * Builds a Range inside a `<vega-code-block>` shadow DOM element.
+   *
+   * `<vega-code-block>` renders its content inside a shadow root with a `<code>`
+   * element containing multiple child `<span>` nodes (one per syntax token).
+   * This method walks all Text nodes within that `<code>` element, accumulating
+   * character length until the positions corresponding to startOffset / endOffset
+   * are found.
+   *
+   * @param {HTMLElement} domElement - The `<vega-code-block>` host element.
+   * @param {NodePosition} nodePosition - The character offsets within the node.
+   * @returns {Range | null} A Range if successfully built, or null on failure.
+   */
+  buildCodeBlockRange(domElement, nodePosition) {
+    const shadowRoot = domElement.shadowRoot;
+    const codeEl = shadowRoot.querySelector('code');
+    if (!codeEl) {
+      return null;
+    }
+    const safeDocument = tryGetDocument();
+    if (safeDocument) {
+      const walker = safeDocument.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);
+      let accumulated = 0;
+      let startNode = null;
+      let startLocal = 0;
+      let endNode = null;
+      let endLocal = 0;
+      let current = walker.nextNode();
+      while (current) {
+        const len = current.textContent.length;
+        if (!startNode && accumulated + len > nodePosition.startOffset) {
+          startNode = current;
+          startLocal = nodePosition.startOffset - accumulated;
+        }
+        if (accumulated + len >= nodePosition.endOffset) {
+          endNode = current;
+          endLocal = nodePosition.endOffset - accumulated;
+          break;
+        }
+        accumulated += len;
+        current = walker.nextNode();
+      }
+      if (startNode && endNode) {
+        const range = safeDocument.createRange();
+        try {
+          range.setStart(startNode, startLocal);
+          range.setEnd(endNode, endLocal);
+          return range;
+        }
+        catch (_a) {
+          return null;
+        }
+      }
+    }
+    return null;
+  }
+}