npm - @globalpayments/vega - Versions diffs - 2.99.0 → 2.100.0 - Mend

@globalpayments/vega 2.99.0 → 2.100.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (509) hide show

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

@@ -18,6 +18,7 @@ export class RTECopyToolbarButtonRenderer extends VegaRTEToolbarButtonRenderer {
   render(h, editorContext) {
     return this.renderButton(h, editorContext, {
       icon: 'rte-copy',
+      ariaLabel: editorContext.translation.t('Copy'),
       tooltip: { text: 'Copy' },
     });
   }

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

@@ -19,6 +19,7 @@ export class RTECutToolbarButtonRenderer extends RTECopyToolbarButtonRenderer {
   render(h, editorContext) {
     return this.renderButton(h, editorContext, {
       icon: 'rte-cut',
+      ariaLabel: editorContext.translation.t('Cut'),
       tooltip: { text: 'Cut' },
     });
   }

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/slimmer/renderers/find-replace-toolbar-button-renderer.js CHANGED Viewed

@@ -8,6 +8,7 @@ import { FindController } from '../controllers/find-controller';
 import { ReplaceController } from '../controllers/replace-controller';
 import { VegaInternalTranslation } from '../../../../../../helpers/translation/internal-translation-controller';
 import { debounce } from '../../../../../../utils/timer';
+import { getDeepActiveElementInShadow } from '../../../../../../utils/ui';
 /**
  * Toolbar button renderer for the Find & Replace extension.
  *
@@ -60,14 +61,22 @@ export class FindReplaceToolbarButtonRenderer extends VegaRTEToolbarButtonRender
       placement: 'bottom',
       showArrow: false,
       isScreenPosition: true,
+      role: 'presentation',
       // eslint-disable-next-line jsdoc/require-jsdoc
       ref: (ref) => {
         if (ref) {
           this.popoverRef = ref;
           DomNodeSubjectObserverFactory.addUniqueObserverToNode(ref, VegaPopoverHide, () => {
+            const shouldRestoreFocus = this.shouldRestoreFocusToButton();
             this.isPopoverOpen = false;
             this.findController.clear();
             this.updatePanel({ current: 0, total: 0 });
+            if (shouldRestoreFocus) {
+              // Defer so it runs after the popover's own focus-restore
+              // (AriaDialogFocusableTrapSlimmer), returning focus to the toolbar
+              // button for keyboard and VoiceOver users when the panel is dismissed.
+              setTimeout(() => this.focusToolbarButton());
+            }
           });
           DomNodeSubjectObserverFactory.addUniqueObserverToNode(ref, VegaPopoverShow, () => {
             this.isPopoverOpen = true;
@@ -98,6 +107,7 @@ export class FindReplaceToolbarButtonRenderer extends VegaRTEToolbarButtonRender
       ]),
       h('div', { slot: 'popover-content' }, this.renderButton(h, editorContext, {
         icon: 'rte-find-replace',
+        ariaLabel: editorContext.translation.t('Find and replace'),
         tooltip: { text: VegaInternalTranslation.t('Find and replace') },
       })),
     ]);
@@ -200,6 +210,47 @@ export class FindReplaceToolbarButtonRenderer extends VegaRTEToolbarButtonRender
       void this.popoverRef.hide();
     }
   }
+  /**
+   * Decides whether closing the panel should return focus to the toolbar button.
+   *
+   * Focus is restored when the panel is dismissed while focus is still inside it
+   * (Escape key or the Close button) — including the VoiceOver case where the
+   * dialog's `inert` blur has already moved focus to `<body>`. It is not restored
+   * when focus has intentionally moved to another element (Tab out of the panel
+   * or interacting with something else), so we don't yank focus back.
+   *
+   * @returns {boolean} True when focus should return to the toolbar button.
+   */
+  shouldRestoreFocusToButton() {
+    // eslint-disable-next-line no-restricted-globals
+    const activeEl = getDeepActiveElementInShadow(document, true);
+    // eslint-disable-next-line no-restricted-globals
+    return !activeEl || activeEl === document.body || this.isElementWithinPanel(activeEl);
+  }
+  /**
+   * Checks whether an element is inside the panel, crossing shadow boundaries.
+   *
+   * @param {Nullable<HTMLElement>} el - The element to test.
+   * @returns {boolean} True when the element is contained by the panel.
+   */
+  isElementWithinPanel(el) {
+    if (!el || !this.panelRef) {
+      return false;
+    }
+    let node = el;
+    while (node) {
+      if (node === this.panelRef) {
+        return true;
+      }
+      const parent = node.parentNode;
+      // Cross shadow boundaries: a shadow root (nodeType 11) exposes its `host`.
+      node =
+        parent && parent.nodeType === Node.DOCUMENT_FRAGMENT_NODE
+          ? parent.host
+          : parent;
+    }
+    return false;
+  }
 }
 (() => {
   VegaInternalIconManager.register({ 'rte-find-replace': findReplaceIcon });

package/dist/collection/components/vega-rich-text-editor/extensions/find-replace/vega-rich-text-find-replace-panel/slimmers/renderers/find-replace-panel-renderer.js CHANGED Viewed

@@ -26,7 +26,7 @@ export class FindReplacePanelRenderer extends VegaSlimmer {
       h("div", { class: "find-replace-panel__field" },
         h("vega-field-label", { label: VegaInternalTranslation.t('Find in text') }),
         h("div", { class: "find-replace-panel__body" },
-          h("vega-input", { size: "small", label: "", class: "find-replace-panel__input", ref: (ref) => {
+          h("vega-input", { size: "small", label: "", "data-aria-label": VegaInternalTranslation.t('Find in text'), class: "find-replace-panel__input", ref: (ref) => {
               if (ref) {
                 DomNodeSubjectObserverFactory.addUniqueObserverToNode(ref, VegaChange, (e) => {
                   this.onKeywordChange(e.detail);
@@ -40,7 +40,7 @@ export class FindReplacePanelRenderer extends VegaSlimmer {
       h("div", { class: "find-replace-panel__field" },
         h("vega-field-label", { label: VegaInternalTranslation.t('Replace with') }),
         h("div", { class: "find-replace-panel__body" },
-          h("vega-input", { disabled: !hasResults, size: "small", label: "", class: "find-replace-panel__input", ref: (ref) => {
+          h("vega-input", { disabled: !hasResults, size: "small", label: "", "data-aria-label": VegaInternalTranslation.t('Replace with'), class: "find-replace-panel__input", ref: (ref) => {
               if (ref) {
                 DomNodeSubjectObserverFactory.addUniqueObserverToNode(ref, VegaChange, (e) => {
                   this.onReplacementChange(e.detail);

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

@@ -30,6 +30,9 @@ export class RTEFullscreenToolbarButtonRenderer extends VegaRTEToolbarButtonRend
     const selected = this.isSelected();
     return this.renderButton(createElement, editorContext, {
       icon: selected ? 'rte-fullscreen-exit' : 'rte-fullscreen-enter',
+      ariaLabel: selected
+        ? editorContext.translation.t('Exit fullscreen mode')
+        : editorContext.translation.t('Enter fullscreen mode'),
       tooltip: {
         text: selected
           ? VegaInternalTranslation.t('Exit fullscreen mode')

package/dist/collection/components/vega-rich-text-editor/extensions/functions/dto/logic-control-node.js CHANGED Viewed

@@ -67,5 +67,11 @@ export class RTELogicControlNode extends RTENode {
   isContentEditable() {
     return false;
   }
+  /**
+   * @inheritDoc
+   */
+  getPlainText() {
+    return this.text;
+  }
 }
 RTELogicControlNode.dtoName = 'RTELogicControlNode';

package/dist/collection/components/vega-rich-text-editor/extensions/functions/renderers/function-toolbar-button-renderer.js CHANGED Viewed

@@ -13,6 +13,7 @@ export class FunctionToolbarButtonRenderer extends VegaRTEToolbarButtonRenderer
     return this.renderDropdown(h, editorContext, {}, [
       this.renderButton(h, editorContext, {
         label: 'Functions',
+        ariaLabel: 'Functions',
         showArrowIcon: true,
         tooltip: { text: 'Insert function' },
       }),

package/dist/collection/components/vega-rich-text-editor/extensions/horizontal-line/renderers/horizontal-line-toolbar-button-renderer.js CHANGED Viewed

@@ -19,6 +19,7 @@ export class RTEHorizontalLineToolbarButtonRenderer extends VegaRTEToolbarButton
   render(createElement, editorContext) {
     return this.renderButton(createElement, editorContext, {
       icon: 'horizontal-line',
+      ariaLabel: VegaInternalTranslation.t('Horizontal line'),
       tooltip: { text: VegaInternalTranslation.t('Horizontal line') },
     });
   }

package/dist/collection/components/vega-rich-text-editor/extensions/languages/language-toolbar-button-renderer.js CHANGED Viewed

@@ -59,6 +59,7 @@ export class RTELanguageToolbarButtonRenderer extends VegaRTEToolbarButtonRender
     return this.renderDropdown(createElement, editorContext, { source: translatedSource }, [
       this.renderButton(createElement, editorContext, {
         label: this.getLanguageLabelByKey(this.selectedLanguage),
+        ariaLabel: 'Language',
         showArrowIcon: true,
         tooltip: { text: 'Select language' },
       }),
@@ -74,10 +75,11 @@ export class RTELanguageToolbarButtonRenderer extends VegaRTEToolbarButtonRender
     this.translation = editorContext.translation;
     const isDisabled = this.isDisabled(editorContext);
     return h('vega-font', {
-      variant: 'font-field-label-sm',
-      color: isDisabled ? 'text-disabled' : 'text-primary',
+      'variant': 'font-field-label-sm',
+      'color': isDisabled ? 'text-disabled' : 'text-primary',
+      'aria-hidden': 'true',
       // eslint-disable-next-line jsdoc/require-jsdoc
-      ref: (el) => {
+      'ref': (el) => {
         this.labelRef = el;
       },
     }, editorContext.translation.t(label));

package/dist/collection/components/vega-rich-text-editor/extensions/line-height/line-height-toolbar-button-renderer.js CHANGED Viewed

@@ -34,12 +34,28 @@ export class RTELineHeightToolbarButtonRenderer extends VegaRTEToolbarButtonRend
     }, [
       this.renderButton(createElement, editorContext, {
         icon: 'line-height',
+        ariaLabel: editorContext.translation.t('Line Height'),
         showArrowIcon: true,
         tooltip: { text: VegaInternalTranslation.t('Line Height') },
       }),
       this.renderDropdownListTemplate(createElement, dropdownItems, editorContext),
     ]);
   }
+  /**
+   * 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
+   */
+  renderDropdownItem(h, item, editorContext) {
+    return h('vega-dropdown-item', { key: item.key, itemKey: item.key, prefixIcon: item.icon }, h('span', undefined, editorContext.translation.t(item.label)));
+  }
   /**
    * @inheritDoc
    */

package/dist/collection/components/vega-rich-text-editor/extensions/special-characters/special-characters-toolbar-button-renderer.js CHANGED Viewed

@@ -33,6 +33,7 @@ export class RTESpecialCharactersToolbarButtonRenderer extends VegaRTEToolbarBut
       placement: 'bottom',
       showArrow: false,
       isScreenPosition: true,
+      role: 'presentation',
       // eslint-disable-next-line jsdoc/require-jsdoc
       ref: (ref) => {
         if (ref) {
@@ -60,6 +61,7 @@ export class RTESpecialCharactersToolbarButtonRenderer extends VegaRTEToolbarBut
       ]),
       h('div', { slot: 'popover-content' }, this.renderButton(h, editorContext, {
         icon: 'rte-special-characters',
+        ariaLabel: editorContext.translation.t('Special Characters'),
         tooltip: { text: 'Special Characters' },
       })),
     ]);

package/dist/collection/components/vega-rich-text-editor/extensions/table/renderers/table-caption-renderer.js CHANGED Viewed

@@ -8,15 +8,9 @@ export class RTETableCaptionRenderer extends VegaRTEExtensionRenderer {
   /**
    * @inheritDoc
    */
-  doRender(h, renderData) {
-    return h('caption', {
-      'key': renderData.id,
-      'ref': this.useRef(renderData),
-      'style': renderData.getStyles(),
-      'class': [renderData.getClasses(), renderData.isNotEmpty() ? null : 'showPlaceholder']
+  doRender(h, renderData, rteContext) {
+    return h('caption', Object.assign(Object.assign({ 'key': renderData.id, 'ref': this.useRef(renderData) }, (rteContext.editable ? { contentEditable: true } : undefined)), { 'style': renderData.getStyles(), 'class': [renderData.getClasses(), renderData.isNotEmpty() ? null : 'showPlaceholder']
         .filter(isNonNullable)
-        .join(' '),
-      'data-placeholder': TABLE_CAPTION_PLACEHOLDER_TEXT,
-    });
+        .join(' '), 'data-placeholder': TABLE_CAPTION_PLACEHOLDER_TEXT }));
   }
 }

package/dist/collection/components/vega-rich-text-editor/extensions/table/renderers/table-cell-renderer.js CHANGED Viewed

@@ -21,9 +21,9 @@ export class RTETableCellRenderer extends VegaRTEExtensionRenderer {
    */
   renderByCellType(h, renderData, rteContext, elementType) {
     var _a;
-    return h(elementType, Object.assign(Object.assign(Object.assign({ key: `${renderData.id}-${elementType}`,
+    return h(elementType, Object.assign(Object.assign(Object.assign(Object.assign({ key: `${renderData.id}-${elementType}`,
       // eslint-disable-next-line jsdoc/require-jsdoc
-      ref: this.useRef(renderData) }, (_a = renderData.getCustomAttributesAnnotation()) === null || _a === void 0 ? void 0 : _a.render()), { style: renderData.getStyles(rteContext), class: renderData.getClasses() }), (rteContext.editable ? this.onSelectionListeners(renderData, rteContext) : undefined)));
+      ref: this.useRef(renderData) }, (rteContext.editable ? { contentEditable: true, tabindex: -1 } : undefined)), (_a = renderData.getCustomAttributesAnnotation()) === null || _a === void 0 ? void 0 : _a.render()), { style: renderData.getStyles(rteContext), class: renderData.getClasses() }), (rteContext.editable ? this.onSelectionListeners(renderData, rteContext) : undefined)));
   }
   /**
    * Returns the mouse event listeners for selection handling.

package/dist/collection/components/vega-rich-text-editor/extensions/table/renderers/table-dynamic-popover-renderer.js CHANGED Viewed

@@ -83,6 +83,8 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
    * and clears the internal reference.
    */
   destroy() {
+    this.setEditorContentInert(false);
+    this.detachEscapeTracker();
     if (this.selectionAnchorRef && this.selectionAnchorRef.parentNode) {
       DomNodeSubjectObserverFactory.removeUniqueObserverFromNode(this.selectionAnchorRef, VegaInternalRTEExtensionTableCellsSelectionAnchor);
       this.selectionAnchorRef.parentNode.removeChild(this.selectionAnchorRef);
@@ -95,8 +97,13 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
    *
    * @param {string} type - The table setting type determining which
    *  content variant to display (for example, table properties or cell properties).
+   * @param {Nullable<HTMLElement>} returnCell - The cell to move focus into the dialog for and
+   *  return focus to if the dialog is dismissed with Escape (set for keyboard/screen-reader users).
    */
-  async show(type) {
+  async show(type, returnCell) {
+    // Remember the cell to return focus to if the dialog is dismissed with Escape, and clear any
+    // stale Escape recorded before the dialog was opened.
+    this.beginReturnFocusTracking(returnCell);
     let target = this.getTableRef();
     const extensionContext = this.getTableExtensionContext();
     let cells = [];
@@ -116,6 +123,11 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
     this.storeCurrentFocusNode();
     remoteInvocationRegistry.call(domNodeSubjectFactory.getSubject(this.popoverRef, VegaInternalPopoverUpdateTarget), target);
     await this.popoverRef.show();
+    // When opened for keyboard/screen-reader users (a return cell is known), move focus into the
+    // dialog so it lands on the first focusable field (the Border Style control).
+    if (returnCell) {
+      this.focusFirstFormField(type);
+    }
   }
   /**
    * hide the popover.
@@ -150,7 +162,11 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
         if (this.popoverCloseType === 'change' && extensionContext) {
           extensionContext.flushValue(extensionContext.host.value);
         }
+        this.handleDialogHide();
       });
+      // Escape inside the dialog (rendered in a portal) does not bubble back to the table, so
+      // observe it on the document (capture phase) to know when to return focus to the cell.
+      this.attachEscapeTracker(safeDocument);
       const slotDiv = safeDocument.createElement('div');
       slotDiv.setAttribute('slot', 'popover');
       slotDiv.className = 'rte-table-dynamic-popover-content';
@@ -177,6 +193,28 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
       return popover;
     }
   }
+  /**
+   * Whether the given event originated inside the properties dialog subtree (either the table or the
+   * cell properties form).
+   *
+   * @param {Event} event - The event to test.
+   * @returns {boolean} `true` when an active form is rendered and the event's composed path includes it.
+   */
+  isEventWithinPopover(event) {
+    const path = event.composedPath();
+    return ((!!this.tablePropertiesFormRef && path.includes(this.tablePropertiesFormRef)) ||
+      (!!this.cellPropertiesFormRef && path.includes(this.cellPropertiesFormRef)));
+  }
+  /**
+   * Resolves the `.rich-text-content` editor root from the current table ref so the content can be
+   * made inert while the properties dialog holds keyboard/VoiceOver focus.
+   *
+   * @returns {Nullable<HTMLElement>} The editor content element, or `null` when it cannot be resolved.
+   */
+  getInertContentTarget() {
+    var _a, _b, _c;
+    return (_c = (_b = (_a = this.getTableRef) === null || _a === void 0 ? void 0 : _a.call(this)) === null || _b === void 0 ? void 0 : _b.closest('.rich-text-content')) !== null && _c !== void 0 ? _c : null;
+  }
   /**
    * Updates the visibility of the pre-rendered content blocks based on type.
    *
@@ -214,6 +252,48 @@ export class TableDynamicPopoverRenderer extends TablePopoverBaseRenderer {
     const extensionContext = this.getTableExtensionContext();
     extensionContext && (this.currentFocusNode = extensionContext.getSelectedNodes()[0]);
   }
+  /**
+   * Moves focus to the first focusable control in the active properties form so keyboard and
+   * screen-reader users land inside the dialog when it opens. The first form field is the Border
+   * Style select; its focusable trigger is the `.vega-input-select-container` element.
+   *
+   * @param {string} type - The table setting type that determines which form is visible.
+   */
+  focusFirstFormField(type) {
+    const formRef = type === TableSettingType.TABLE ? this.tablePropertiesFormRef : this.cellPropertiesFormRef;
+    if (!formRef) {
+      return;
+    }
+    // Make the editor content inert up front so the table/cell cannot steal focus while the dialog
+    // lays out. The cell form applies the selected cell's styles on open, whose async reset fires a
+    // selectionchange that would otherwise re-focus the cell before we reach Border Style. Inert also
+    // gives VoiceOver no cell-caret text context, so its cursor follows the focus. Lifted on hide.
+    this.setEditorContentInert(true);
+    // The CELL form applies the selected cell's styles on open (it sets both `styleMap` and
+    // `defaultValue`), a heavier re-render than TABLE, so on the first open its Border Style control is
+    // present but 0×0 for a frame. WebKit's VoiceOver cursor does not follow `.focus()` onto a
+    // zero-area element, so defer through a double animation frame: the first schedules past the
+    // popover's async reveal, the second runs after the browser has committed the layout pass that
+    // sizes the control.
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        var _a, _b, _c, _d, _e;
+        const firstField = (_b = (_a = formRef.shadowRoot) === null || _a === void 0 ? void 0 : _a.querySelector('[data-vega-form]')) !== null && _b !== void 0 ? _b : null;
+        const container = (_d = (_c = firstField === null || firstField === void 0 ? void 0 : firstField.shadowRoot) === null || _c === void 0 ? void 0 : _c.querySelector('.vega-input-select-container')) !== null && _d !== void 0 ? _d : null;
+        (_e = (container !== null && container !== void 0 ? container : firstField)) === null || _e === void 0 ? void 0 : _e.focus();
+      });
+    });
+  }
+  /**
+   * When the properties dialog hides after an Escape press, returns focus (and the caret) to the
+   * table cell that had focus before the dialog was opened via the setting toolbar.
+   */
+  handleDialogHide() {
+    // Lift the inert guard on the editor content synchronously, before any focus restore runs, so the
+    // cell can receive focus and the editor is interactive again.
+    this.setEditorContentInert(false);
+    this.restoreFocusOnEscapeHide();
+  }
   /**
    * Create and position an invisible anchor element whose position and size are identical to the geometry of the current multi-cell selection.
    * This anchor element will then be used as the target of the popup, so that the popup appears near the entire selection area.

package/dist/collection/components/vega-rich-text-editor/extensions/table/renderers/table-popover-base-renderer.js CHANGED Viewed

@@ -1,9 +1,42 @@
 import RTEExtensionContextManager from '../../../helpers/extension-context-manager';
 /**
  * Base renderer for table-related popovers, providing common functionalities such as accessing the table extension context.
+ *
+ * Popovers that move keyboard/VoiceOver focus into themselves (the setting toolbar and the
+ * properties dialog) share the same focus-restoration machinery: they make the editor content
+ * `inert` while open, track Escape presses at the document level, and return focus (and the caret)
+ * to the originating cell when an Escape dismisses the popover. That behavior lives here so the two
+ * renderers do not each carry a copy; subclasses only supply the two pieces that differ — how to
+ * resolve the editor content root ({@link getInertContentTarget}) and how to tell whether an event
+ * originated inside their own popover subtree ({@link isEventWithinPopover}).
  */
 export class TablePopoverBaseRenderer {
   constructor(renderContext) {
+    /** The editor content element made inert while the popover holds focus, cached so it can be restored. */
+    this.inertedContentEl = null;
+    /** The table cell to return focus to when the popover is dismissed via Escape. */
+    this.returnFocusCell = null;
+    /** Tracks whether Escape was pressed while the popover was open. */
+    this.escapePressed = false;
+    /** Document the Escape tracker keydown listener is bound to, for later removal. */
+    this.keydownListenerDocument = null;
+    /**
+     * Tracks Escape key presses that originate inside the popover so focus can be returned to the
+     * originating cell when that Escape dismisses the popover. vega-popover's own Escape handler hides
+     * the popover without restoring focus, so the restore is coordinated here.
+     *
+     * The listener is bound at the document level (the popover renders in a portal, so its Escape does
+     * not bubble back to the table), so scope it to the popover subtree via {@link isEventWithinPopover}:
+     * a stray Escape elsewhere must not arm the restore and hijack focus on a later non-Escape dismissal
+     * (e.g. click-outside).
+     *
+     * @param {KeyboardEvent} event - The keydown event.
+     */
+    this.handleDocumentKeydown = (event) => {
+      if (event.code === 'Escape' && this.isEventWithinPopover(event)) {
+        this.escapePressed = true;
+      }
+    };
     this.renderContext = renderContext;
   }
   /**
@@ -16,4 +49,119 @@ export class TablePopoverBaseRenderer {
       ? RTEExtensionContextManager.getExtensionContext(this.renderContext.host)
       : null;
   }
+  /**
+   * Begins tracking so a later Escape can return focus to `returnCell`. Records the cell and clears
+   * any stale Escape observed before the popover was opened.
+   *
+   * @param {Nullable<HTMLElement>} returnCell - The cell to return focus to if the popover is dismissed with Escape.
+   */
+  beginReturnFocusTracking(returnCell) {
+    this.returnFocusCell = returnCell !== null && returnCell !== void 0 ? returnCell : null;
+    this.escapePressed = false;
+  }
+  /**
+   * Registers the document-level (capture phase) Escape tracker. The popover renders in a portal, so
+   * its Escape does not bubble back to the table; observing on the document lets us know when to
+   * return focus to the cell.
+   *
+   * @param {Document} doc - The document to bind the keydown listener to.
+   */
+  attachEscapeTracker(doc) {
+    doc.addEventListener('keydown', this.handleDocumentKeydown, { capture: true });
+    this.keydownListenerDocument = doc;
+  }
+  /**
+   * Removes the document-level Escape tracker if one was registered.
+   */
+  detachEscapeTracker() {
+    if (this.keydownListenerDocument) {
+      this.keydownListenerDocument.removeEventListener('keydown', this.handleDocumentKeydown, {
+        capture: true,
+      });
+      this.keydownListenerDocument = null;
+    }
+  }
+  /**
+   * Whether the given event originated inside this popover's subtree. Subclasses override this to
+   * match their own portal-rendered content; the base returns `false` so renderers that do not move
+   * focus never arm the restore.
+   *
+   * @param {Event} _event - The event to test.
+   * @returns {boolean} `true` when the event originated inside the popover subtree.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  isEventWithinPopover(_event) {
+    return false;
+  }
+  /**
+   * When the popover hides after an Escape press, returns focus (and the caret) to the table cell
+   * that had focus before the popover was opened.
+   *
+   * vegaPopoverHide fires synchronously from the popover's own Escape handler, before the
+   * document-capture keydown observes the key and before the popover settles focus on `<body>`.
+   * Defer past that so the flag is set and this focus restore wins.
+   */
+  restoreFocusOnEscapeHide() {
+    // eslint-disable-next-line no-restricted-globals
+    setTimeout(() => {
+      const shouldRestore = this.escapePressed;
+      const cell = this.returnFocusCell;
+      this.escapePressed = false;
+      this.returnFocusCell = null;
+      if (shouldRestore && cell && cell.isConnected) {
+        this.restoreFocusToCell(cell);
+      }
+    }, 0);
+  }
+  /**
+   * Focuses the given table cell and collapses the caret at its start.
+   *
+   * @param {HTMLElement} cell - The table cell to focus.
+   */
+  restoreFocusToCell(cell) {
+    var _a, _b, _c;
+    cell.focus();
+    const extensionContext = this.getTableExtensionContext();
+    const selection = (_c = (_a = extensionContext === null || extensionContext === void 0 ? void 0 : extensionContext.getSelection()) !== null && _a !== void 0 ? _a : (_b = cell.ownerDocument) === null || _b === void 0 ? void 0 : _b.getSelection()) !== null && _c !== void 0 ? _c : null;
+    if (selection) {
+      const range = new Range();
+      range.setStart(cell, 0);
+      range.setEnd(cell, 0);
+      selection.removeAllRanges();
+      selection.addRange(range);
+    }
+  }
+  /**
+   * Resolves the `.rich-text-content` editor root to toggle `inert` on while the popover holds focus.
+   * Subclasses override this because they reach the content from different anchors (the toolbar's
+   * target vs. the current table ref); the base returns `null` so renderers that do not use inert are
+   * unaffected.
+   *
+   * @returns {Nullable<HTMLElement>} The editor content element, or `null` when it cannot be resolved.
+   */
+  getInertContentTarget() {
+    return null;
+  }
+  /**
+   * Toggles `inert` on the editor content region while the popover holds keyboard/VoiceOver focus.
+   * Safari VoiceOver keeps its reading cursor anchored to the cell caret and does not follow the
+   * programmatic focus moved into the popover; making the editor content inert removes that text
+   * context so the VoiceOver cursor lands inside the popover. The popover is a body-level portal, so it
+   * is not a descendant of the inert content and stays interactive.
+   *
+   * @param {boolean} inert - Whether the editor content should be inert.
+   */
+  setEditorContentInert(inert) {
+    if (inert) {
+      const content = this.getInertContentTarget();
+      if (content) {
+        content.setAttribute('inert', '');
+        this.inertedContentEl = content;
+      }
+    }
+    else if (this.inertedContentEl) {
+      this.inertedContentEl.removeAttribute('inert');
+      this.inertedContentEl = null;
+    }
+  }
 }