@mongodb-js/compass-editor 0.29.2 → 0.31.0

package/dist/codemirror/validation-autocompleter.js

@@ -18,21 +18,29 @@ const rootJsonSchemaCompletion = (from, to) => ({
     ],
 });
 const isCompletingRequired = (ancestors) => {
+    // Required is always an array.
     return ancestors[ancestors.length - 2] === 'required';
 };
 const isCompletingProperties = (ancestors) => {
     return ancestors[ancestors.length - 1] === 'properties';
 };
 const isCompletingBsonType = (ancestors) => {
+    // bsonType can either be a string or an array.
     const immediateParent = ancestors[ancestors.length - 1] ?? '';
     return (immediateParent === 'bsonType' ||
         ancestors[ancestors.length - 2] === 'bsonType');
 };
 const isCompletingQueryOperator = (ancestors, operators) => {
+    // The query operators also has a $jsonSchema, so we need to filter
+    // that out as the context in that case is jsonSchema and not query.
     return ancestors
         .filter((x) => x !== '$jsonSchema')
         .some((x) => operators.includes(x));
 };
+/**
+ * The $jsonSchema's *required* and *properties* fields are nested,
+ * so we need to get the ancestor to get the correct field name.
+ */
 const getNestingAncestor = (ancestors) => {
     return (ancestors
         .filter((x) => !['$jsonSchema'].includes(x))
@@ -42,8 +50,13 @@ const getNestingAncestor = (ancestors) => {
         }
     })
         .filter(Boolean)
+        // because field names are represented in dot notation
         .join('.'));
 };
+/**
+ * As the $jsonSchema's *required* and *properties* fields are nested,
+ * we need to filter the fields based on the nesting level (ancestor).
+ */
 const filterFieldsByAncestor = (fields, ancestor) => {
     if (ancestor === '') {
         return fields;
@@ -82,6 +95,7 @@ const createValidationAutocompleter = (options = {}) => {
         const token = (0, utils_1.resolveTokenAtCursor)(context);
         const document = context.state.sliceDoc(0);
         const prefix = context.matchBefore(ace_compat_autocompleter_1.ID_REGEX);
+        // At the root level
         if (token.type.isTop) {
             return rootJsonSchemaCompletion(0, document.length);
         }
@@ -89,6 +103,7 @@ const createValidationAutocompleter = (options = {}) => {
             return null;
         }
         const ancestors = (0, utils_1.getAncestryOfToken)(token, document);
+        // At the root object {} level.
         if (ancestors.length === 0) {
             return (0, ace_compat_autocompleter_1.createCompletionResultForIdPrefix)({
                 prefix,

package/dist/codemirror/validation-autocompleter.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-autocompleter.js","sourceRoot":"","sources":["../../src/codemirror/validation-autocompleter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validation-autocompleter.js","sourceRoot":"","sources":["../../src/codemirror/validation-autocompleter.ts"],"names":[],"mappings":"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"}

package/dist/editor.d.ts

@@ -103,6 +103,7 @@ export type EditorRef = {
     prettify: () => boolean;
     applySnippet: (template: string) => boolean;
     focus: () => boolean;
+    cursorDocEnd: () => boolean;
     startCompletion: () => boolean;
     readonly editorContents: string | null;
     readonly editor: EditorView | null;
@@ -130,8 +131,24 @@ type MultilineEditorProps = EditorProps & {
     actionsClassName?: string;
 };
 declare const MultilineEditor: React.ForwardRefExoticComponent<MultilineEditorProps & React.RefAttributes<EditorRef>>;
-declare function setCodemirrorEditorValue(element: HTMLElement | string | null, text: string): Promise<void>;
-declare function getCodemirrorEditorValue(element: HTMLElement | string | null): string;
+/**
+ * Sets the editor value, use this with RTL like this:
+ *
+ * ```
+ * render(<Editor data-testid='my-editor' />);
+ * setCodemirrorEditorValue(screen.getByTestId('editor-test-id'), 'my text');
+ * ```
+ */
+declare function setCodemirrorEditorValue(element: Element | string | null, text: string): Promise<void>;
+/**
+ * Retrieves the contents of an editor, use this with RTL like this:
+ *
+ * ```
+ * render(<Editor data-testid='my-editor' />);
+ * getCodemirrorEditorValue(screen.getByTestId('editor-test-id'));
+ * ```
+ */
+declare function getCodemirrorEditorValue(element: Element | string | null): string;
 export { BaseEditor };
 export { InlineEditor as CodemirrorInlineEditor };
 export { MultilineEditor as CodemirrorMultilineEditor };

package/dist/editor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../src/editor.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"editor.d.ts","sourceRoot":"","sources":["../src/editor.tsx"],"names":[],"mappings":"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"}

package/dist/editor.js

@@ -62,6 +62,11 @@ const hiddenScrollStyle = (0, compass_components_1.css)({
 function isReadOnly(state) {
     return state.facet(state_1.EditorState.readOnly);
 }
+// Breaks keyboard navigation out of the editor, but we want that.
+// A user has to hit `Escape` then `Tab` to enter keyboard navigation.
+// Note that the ordering of these matters as no more key handlers are called
+// after the first corresponding `run` function returns true.
+// https://codemirror.net/examples/tab/
 const tabKeymap = [
     {
         key: 'Tab',
@@ -78,6 +83,9 @@ const tabKeymap = [
             if (isReadOnly(state)) {
                 return false;
             }
+            // `indentWithTab` will indent when `Tab` is pressed without any selection (like
+            // in browser devtools for example). Instead we want to input the tab symbol in
+            //  that case, to have behavior similar to VSCode's editors.
             if (!state.selection.ranges.some((range) => !range.empty)) {
                 dispatch(state.update(state.replaceSelection('\t'), {
                     scrollIntoView: true,
@@ -101,6 +109,7 @@ exports.editorPalette = {
         gutterActiveLineBackgroundColor: (0, polished_1.rgba)(compass_components_1.palette.gray.light2, 0.5),
         gutterFoldButtonColor: compass_components_1.palette.black,
         cursorColor: compass_components_1.palette.gray.base,
+        // Semi-transparent opacity so that the selection background can still be seen.
         activeLineBackgroundColor: (0, polished_1.rgba)(compass_components_1.palette.gray.light2, 0.5),
         selectionBackgroundColor: compass_components_1.palette.blue.light2,
         bracketBorderColor: compass_components_1.palette.gray.light1,
@@ -125,6 +134,7 @@ exports.editorPalette = {
         gutterActiveLineBackgroundColor: (0, polished_1.rgba)(compass_components_1.palette.gray.dark2, 0.5),
         gutterFoldButtonColor: compass_components_1.palette.white,
         cursorColor: compass_components_1.palette.green.base,
+        // Semi-transparent opacity so that the selection background can still be seen.
         activeLineBackgroundColor: (0, polished_1.rgba)(compass_components_1.palette.gray.dark2, 0.5),
         selectionBackgroundColor: compass_components_1.palette.gray.dark2,
         bracketBorderColor: compass_components_1.palette.gray.light1,
@@ -362,7 +372,7 @@ function getStylesForTheme(theme) {
             marginTop: 0,
             paddingTop: 0,
             fontSize: '12px',
-            maxHeight: '70vh',
+            maxHeight: `${compass_components_1.spacing[1600] * 5}px`,
         },
         '& .cm-tooltip .completion-info p': {
             margin: 0,
@@ -377,6 +387,9 @@ function getStylesForTheme(theme) {
             marginBottom: 0,
         },
         '& .cm-widgetBuffer': {
+            // Default is text-top which causes weird 1px added to the line height
+            // when widget (in our case this is placeholder widget) is shown in the
+            // editor
             verticalAlign: 'top',
         },
     }, { dark: theme === 'dark' });
@@ -386,6 +399,9 @@ const themeStyles = {
     dark: getStylesForTheme('dark'),
 };
 function getHighlightStyleForTheme(theme) {
+    // For the full list of tags parsed by lezer for javascript / json see:
+    //   https://github.com/lezer-parser/javascript/blob/main/src/highlight.js
+    //   https://github.com/lezer-parser/json/blob/main/src/highlight.js
     return language_2.HighlightStyle.define([
         {
             tag: [
@@ -462,6 +478,7 @@ function createFoldGutterExtension() {
     });
 }
 const javascriptExpression = lang_javascript_1.javascriptLanguage.configure({
+    // We always use editor to edit single expressions in Compass
     top: 'SingleExpression',
 });
 exports.languages = {
@@ -486,12 +503,29 @@ async function waitUntilEditorIsReady(editorView, signal) {
     }
     return true;
 }
+/**
+ * Codemirror editor throws when the state update is being applied while another
+ * one is in progress and doesn't give us a way to schedule updates otherwise.
+ * They do have some good reasoning[0] for it, but as we are using this library
+ * in React context where having multiple effects instead of grouping them all
+ * in one place is preferable over grouping them all together, we have this
+ * method to allow to schedule updates and apply them when editor gets idle
+ *
+ * [0]: https://discuss.codemirror.net/t/should-dispatched-transactions-be-added-to-a-queue/4610/4
+ */
 async function scheduleDispatch(editorView, transactions, signal) {
     await waitUntilEditorIsReady(editorView, signal);
     transactions = Array.isArray(transactions) ? transactions : [transactions];
     editorView.dispatch(...transactions);
     return true;
 }
+/**
+ * https://codemirror.net/examples/config/#dynamic-configuration
+ * @param fn
+ * @param editorViewRef
+ * @param value
+ * @returns
+ */
 function useCodemirrorExtensionCompartment(fn, value, editorViewRef) {
     const extensionCreatorRef = (0, react_1.useRef)(fn);
     extensionCreatorRef.current = fn;
@@ -514,9 +548,13 @@ function useCodemirrorExtensionCompartment(fn, value, editorViewRef) {
     return initialExtensionRef.current;
 }
 const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText: _initialText, text, onChangeText, language = 'json', showLineNumbers = true, showFoldGutter = true, showAnnotationsGutter = true, showScroll = true, highlightActiveLine: shouldHighlightActiveLine = true, annotations, completer, darkMode: _darkMode, disabled = false, className, readOnly = false, onLoad = () => {
+    /**/
 }, onFocus = () => {
+    /**/
 }, onBlur = () => {
+    /**/
 }, onPaste = () => {
+    /**/
 }, minLines, maxLines, lineHeight = 16, placeholder, commands, initialJSONFoldAll: _initialJSONFoldAll = true, ...props }, ref) {
     const darkMode = (0, compass_components_1.useDarkMode)(_darkMode);
     const onChangeTextRef = (0, react_1.useRef)(onChangeText);
@@ -535,6 +573,7 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
         hasScroll: false,
     });
     const initialJSONFoldAll = (0, react_1.useRef)(_initialJSONFoldAll);
+    // Always keep the latest reference of the callbacks
     onChangeTextRef.current = onChangeText;
     onLoadRef.current = onLoad;
     onFocusRef.current = onFocus;
@@ -579,6 +618,12 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                 editorViewRef.current.focus();
                 return true;
             },
+            cursorDocEnd() {
+                if (!editorViewRef.current) {
+                    return false;
+                }
+                return (0, commands_1.cursorDocEnd)(editorViewRef.current);
+            },
             startCompletion() {
                 if (!editorViewRef.current) {
                     return false;
@@ -614,6 +659,7 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
         return themeStyles[darkMode ? 'dark' : 'light'];
     }, darkMode, editorViewRef);
     const lineHeightExtension = useCodemirrorExtensionCompartment(() => {
+        // See https://codemirror.net/examples/styling/#overflow-and-scrolling
         return view_1.EditorView.theme({
             '& .cm-scroller': {
                 lineHeight: `${lineHeight}px`,
@@ -635,6 +681,9 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
     const foldGutterExtension = useCodemirrorExtensionCompartment(() => {
         return showFoldGutter ? createFoldGutterExtension() : [];
     }, showFoldGutter, editorViewRef);
+    // By default we want to show annotations gutter so that the gutters don't
+    // jump when annotations are added / removed. This can be opted out by setting
+    // showAnnotationsGutter to false
     const shouldShowAnnotationsGutter = showAnnotationsGutter || (annotations && annotations.length === 0);
     const annotationsGutterExtension = useCodemirrorExtensionCompartment(() => {
         return shouldShowAnnotationsGutter ? (0, lint_1.lintGutter)() : [];
@@ -679,6 +728,10 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
         const domNode = editorContainerRef.current;
         const editor = (editorViewRef.current = new view_1.EditorView({
             doc: initialText.current,
+            // Cherry-picked from codemirror basicSetup extensions to match the ones
+            // we had with ace-editor. There are many more that we might want to add,
+            // but this is good as a starting point
+            // https://github.com/codemirror/basic-setup/blob/5b4dafdb3b02271bd3fd507d86982208457d8c5b/src/codemirror.ts#L12-L49
             extensions: [
                 state_1.EditorState.tabSize.of(2),
                 annotationsGutterExtension,
@@ -697,7 +750,11 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                 lineHeightExtension,
                 themeConfigExtension,
                 placeholderExtension,
+                // User provided commands should take precedence over default keybindings.
                 commandsExtension,
+                // The order of this keymap matters, when the `run` function of the corresponding key
+                // returns false it goes to the next corresponding key, if it returns true then
+                // it completes and does not try further handlers.
                 view_1.keymap.of([
                     {
                         key: 'Ctrl-Shift-b',
@@ -707,6 +764,8 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                         key: 'Ctrl-Shift-c',
                         run: copyAll,
                     },
+                    // Close brackets keymap overrides default backspace handler for
+                    // matching bracket case
                     ...autocomplete_1.closeBracketsKeymap,
                     ...commands_1.defaultKeymap,
                     ...commands_1.historyKeymap,
@@ -714,6 +773,9 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                     ...autocomplete_1.completionKeymap,
                     ...tabKeymap,
                 ]),
+                // Supply the document body as the tooltip parent
+                // because we are using containment contexts for container
+                // queries which offset things otherwise.
                 (0, view_1.tooltips)({
                     parent: document.body,
                 }),
@@ -726,6 +788,12 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                         onChangeTextRef.current?.(editorText, update);
                     }
                 }),
+                /**
+                 * EditorView.domEventHandlers use real DOM events. However,
+                 * we want to bubble these events up to our React components
+                 * properly. We will be casting them to React synthetic events,
+                 * as for our use case, they should behave identical.
+                 */
                 view_1.EditorView.domEventHandlers({
                     focus(event) {
                         onFocusRef.current?.(event);
@@ -740,9 +808,21 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
             ],
             parent: domNode,
         }));
+        // For debugging / e2e tests purposes
         domNode._cm = editor;
         onLoadRef.current(editor);
         if (editor && initialLanguage.current === 'json') {
+            // By default codemirror uses partial parser that will parse only visible
+            // part of the code on the screen. This is extremely performant, but
+            // collides with our folding logic for the json view. For json we collapse
+            // everything but the very top level document. To be able to do that we
+            // need to ensure that the whole syntax tree is available to the fold
+            // extension.
+            //
+            // WARNING: This is a massive performance bottleneck in editor rendering,
+            // we do parsing with a timeout to avoid locking main thread for too long,
+            // but even this is a compromise. If this becomes an issue, we might
+            // consider disabling this folding by default.
             const docLength = editor.state.doc.length;
             const isSyntaxTreeAvailable = (0, language_1.syntaxTreeAvailable)(editor.state, docLength) ||
                 (0, language_1.forceParsing)(editor, docLength, 150);
@@ -750,6 +830,7 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
                 foldAll(editor);
             }
             else {
+                // warn: document is to big to be parsed and folded, this is not a critical issue, just a ui problem
             }
         }
         updateEditorContentHeight();
@@ -758,6 +839,12 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
             editor.destroy();
         };
     }, [
+        // Make sure that this effect is never updated as this will cause the whole
+        // editor to re-mount causing weird behavior and possible performance
+        // bottlenecks
+        //
+        // All the following values are refs which will not change value after
+        // initial render and so will not re-trigger this effect
         annotationsGutterExtension,
         foldGutterExtension,
         languageExtension,
@@ -772,15 +859,21 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
         updateEditorContentHeight,
     ]);
     (0, react_1.useEffect)(() => {
+        // Ignore changes to `text` prop if `initialText` was provided
         if (initialTextProvided.current) {
             return;
         }
+        // When the outside value is out of sync with the editor value, hard reset
+        // the editor if we are in controlled mode (we might need to account for
+        // cursor position, but currently this sort of update can happen only on
+        // blur so we can ignore this for now)
         if (editorViewRef.current &&
             text !== (editorViewRef.current.state.sliceDoc() ?? '')) {
             const controller = new AbortController();
             void scheduleDispatch(editorViewRef.current, {
                 changes: {
                     from: 0,
+                    // Replace all the content
                     to: editorViewRef.current.state.doc.length,
                     insert: text,
                 },
@@ -802,6 +895,15 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
             controller.abort();
         };
     }, [annotations]);
+    // We wrap editor in a relatively positioned container followed by an absolute
+    // one to be able to create a new DOM layer that will prevent component
+    // changes from triggering pricey layout reflows for the whole document. We
+    // then manually keep conatiner height in sync with the editor height to make
+    // sure that the element actually takes all the required space in the page
+    // layout. This is a performance optimization that is mainly needed for the
+    // query bar component where typing anything in the editor might trigger a
+    // layout reflow for the whole document which causes .5s lag in the UI on
+    // every character input in worst case scenarios
     (0, react_1.useLayoutEffect)(() => {
         if (containerRef.current) {
             const scrollHeight = hasScroll && showScroll ? 10 : 0;
@@ -817,6 +919,13 @@ const BaseEditor = react_1.default.forwardRef(function BaseEditor({ initialText:
             maxHeight: '100%',
         } },
         react_1.default.createElement("div", { ref: editorContainerRef, className: (0, compass_components_1.cx)(editorStyle, !showScroll && hiddenScrollStyle), style: {
+                // We're forcing editor to it's own layer by setting position to
+                // absolute to prevent editor layout changes and style
+                // recalculations to cause layout reflows for the whole document
+                //
+                // Having position absolute here causes element to create it's
+                // own layer that keeps all pricey layout operations inside.
+                // This works in combination wit parent height update. See above
                 position: 'absolute',
                 width: '100%',
                 height: '100%',
@@ -856,12 +965,16 @@ const foldAll = (editor) => {
                 (0, language_1.foldable)(editor.state, nodeRef.from, nodeRef.to) &&
                 !isTopNode(nodeRef.node)) {
                 if (!nodeRef.node.parent) {
+                    // isTopNode guarantees that we are not trying to fold something
+                    // without a parent
                     throw new Error('Trying to fold node without parent');
                 }
                 const range = (0, language_1.foldInside)(nodeRef.node.parent);
                 if (range) {
                     foldableProperties.push(range);
                 }
+                // Returning `false` stops iteration over children, we don't need
+                // to iterate children if the node we entered is foldable
                 return false;
             }
         },
@@ -880,6 +993,7 @@ const copyAll = (editorView) => {
     return true;
 };
 const prettify = (editorView) => {
+    // Can't prettify a read-only document
     if (isReadOnly(editorView.state)) {
         return false;
     }
@@ -900,6 +1014,7 @@ const prettify = (editorView) => {
         }
     }
     catch {
+        // failed to parse, do nothing
     }
     return false;
 };
@@ -958,6 +1073,9 @@ const MultilineEditor = react_1.default.forwardRef(function MultilineEditor({ cu
             applySnippet(template) {
                 return editorRef.current?.applySnippet(template) ?? false;
             },
+            cursorDocEnd() {
+                return editorRef.current?.cursorDocEnd() ?? false;
+            },
             startCompletion() {
                 return editorRef.current?.startCompletion() ?? false;
             },
@@ -974,7 +1092,7 @@ const MultilineEditor = react_1.default.forwardRef(function MultilineEditor({ cu
             copyable && (react_1.default.createElement(actions_1.ActionButton, { key: "Copy", label: "Copy", icon: "Copy", onClick: () => {
                     return editorRef.current?.copyAll() ?? false;
                 } })),
-            formattable && (react_1.default.createElement(actions_1.ActionButton, { key: "Format", label: "Format", icon: react_1.default.createElement(actions_1.FormatIcon, { size: 14, role: "presentation" }), onClick: () => {
+            formattable && (react_1.default.createElement(actions_1.ActionButton, { key: "Format", label: "Format", icon: react_1.default.createElement(actions_1.FormatIcon, { size: /* leafygreen small */ 14, role: "presentation" }), onClick: () => {
                     return editorRef.current?.prettify() ?? false;
                 } })),
             ...(customActions ?? []).map((action) => {
@@ -987,7 +1105,14 @@ const MultilineEditor = react_1.default.forwardRef(function MultilineEditor({ cu
             }),
         ];
     }, [copyable, formattable, customActions]);
-    return (react_1.default.createElement("div", { ref: containerRef, className: (0, compass_components_1.cx)(multilineEditorContainerStyle, darkMode && multilineEditorContainerDarkModeStyle, !!actions.length && multilineEditorContainerWithActionsStyle, className), onClick: (evt) => {
+    return (
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions
+    react_1.default.createElement("div", { ref: containerRef, className: (0, compass_components_1.cx)(multilineEditorContainerStyle, darkMode && multilineEditorContainerDarkModeStyle, !!actions.length && multilineEditorContainerWithActionsStyle, className), 
+        // We want folks to be able to click into the container element
+        // they're using for the editor to focus the editor.
+        onClick: (evt) => {
+            // Only do this when root container of the editor is clicked (not
+            // something inside it)
             if (evt.target === containerRef.current) {
                 editorRef.current?.focus();
             }
@@ -996,6 +1121,14 @@ const MultilineEditor = react_1.default.forwardRef(function MultilineEditor({ cu
         actions.length > 0 && (react_1.default.createElement("div", { className: (0, compass_components_1.cx)('multiline-editor-actions', actionsContainerStyle, actionsClassName) }, actions))));
 });
 exports.CodemirrorMultilineEditor = MultilineEditor;
+/**
+ * Sets the editor value, use this with RTL like this:
+ *
+ * ```
+ * render(<Editor data-testid='my-editor' />);
+ * setCodemirrorEditorValue(screen.getByTestId('editor-test-id'), 'my text');
+ * ```
+ */
 async function setCodemirrorEditorValue(element, text) {
     if (typeof element === 'string') {
         element = document.querySelector(`[data-testid="${element}"]`);
@@ -1013,6 +1146,14 @@ async function setCodemirrorEditorValue(element, text) {
     });
 }
 exports.setCodemirrorEditorValue = setCodemirrorEditorValue;
+/**
+ * Retrieves the contents of an editor, use this with RTL like this:
+ *
+ * ```
+ * render(<Editor data-testid='my-editor' />);
+ * getCodemirrorEditorValue(screen.getByTestId('editor-test-id'));
+ * ```
+ */
 function getCodemirrorEditorValue(element) {
     if (typeof element === 'string') {
         element = document.querySelector(`[data-testid="${element}"]`);