Add CodeEditor actions and improve Escape-Tab handling

Author: fiorsaoirse

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/) and this p
 ### Added
 
 - `<CodeEditor />`
+    - adds the `actions` property for rendering custom actions to the right of the content inside the scrollable editor area
     - documents the built-in Escape then Tab sequence for moving focus out of the editor when Tab is configured to indent
     - shows a compact keyboard navigation hint in a bottom CodeMirror panel while the editor is focused and Tab is configured to indent
     - adds visually hidden navigation instructions for screen reader users

src/components/AutoSuggestion/AutoSuggestion.scss

@@ -31,8 +31,9 @@
     background-color: $eccgui-color-textfield-background;
 }
 
-.#{$eccgui}-singlelinecodeeditor {
-    padding: 0;
+.#{$eccgui}-codeeditor.#{$eccgui}-singlelinecodeeditor {
+    height: auto;
+    padding: 2px;
 
     [class^="cm-theme"] {
         width: 100%;
@@ -45,8 +46,7 @@
     }
 
     .cm-editor {
-        top: 1px;
-        height: calc(#{$eccgui-size-textfield-height-regular} - 2px);
+        height: auto;
         padding: 0;
         margin: 0;
         overflow: hidden;
@@ -61,11 +61,18 @@
 
         .cm-scroller {
             height: 100%;
+            min-height: calc(#{$eccgui-size-textfield-height-regular} - 2px);
             padding: 0;
             margin: 0;
             overflow: auto hidden !important;
         }
 
+        .#{$eccgui}-codeeditor__actions {
+            align-items: center;
+            padding: 0;
+            border-left: 0;
+        }
+
         .cm-content {
             display: flex;
             flex-direction: column;

src/components/AutoSuggestion/AutoSuggestion.tsx

@@ -198,9 +198,10 @@ export const CodeAutocompleteField = ({
     intent,
 }: CodeAutocompleteFieldProps) => {
     const value = React.useRef<string>(initialValue);
+    const [hasValue, setHasValue] = React.useState(!!initialValue);
     const cursorPosition = React.useRef(0);
     const dropdownXYoffset = React.useRef<{ x: number; y: number }>({ x: 0, y: 0 });
-    const [shouldShowDropdown, setShouldShowDropdown] = React.useState(false);
+    const [shouldShowDropdown, setShouldShowDropdownState] = React.useState(false);
     const [suggestions, setSuggestions] = React.useState<CodeAutocompleteFieldSuggestionWithReplacementInfo[]>([]);
     const [suggestionsPending, setSuggestionsPending] = React.useState(false);
     const suggestionRequestData = React.useRef<RequestMetaData>({ requestId: undefined });
@@ -221,6 +222,7 @@ export const CodeAutocompleteField = ({
     const currentCm = React.useRef<EditorView>(undefined);
     currentCm.current = cm;
     const isFocused = React.useRef(false);
+    const suggestionsDismissed = React.useRef(false);
     const autoSuggestionDivRef = React.useRef<HTMLDivElement>(null);
     /** Mutable editor state, since this needs to be current in scope of the SingleLineEditorComponent. */
     const [editorState] = React.useState<{
@@ -229,6 +231,15 @@ export const CodeAutocompleteField = ({
         cm?: EditorView;
         dropdownShown: boolean;
     }>({ index: 0, suggestions: [], dropdownShown: false });
+
+    const setDropdownShown = React.useCallback(
+        (shown: boolean) => {
+            editorState.dropdownShown = shown;
+            setShouldShowDropdownState(shown);
+        },
+        [editorState],
+    );
+
     /** This is for the AutoSuggestionList component in order to re-render. */
     const [focusedIndex, setFocusedIndex] = React.useState(0);
     const selectedTextRanges = React.useRef<IRange[]>([]);
@@ -266,10 +277,6 @@ export const CodeAutocompleteField = ({
         typeof editorState?.cm?.dispatch === "function" ? editorState?.cm?.dispatch : () => {}
     ) as EditorView["dispatch"];
 
-    React.useEffect(() => {
-        editorState.dropdownShown = shouldShowDropdown;
-    }, [shouldShowDropdown, editorState]);
-
     // Handle replacement highlighting
     useEffect(() => {
         if (highlightedElement && cm) {
@@ -331,7 +338,7 @@ export const CodeAutocompleteField = ({
             suggestionResponse?.replacementResults?.length === 1 &&
             !suggestionResponse?.replacementResults[0]?.replacements?.length
         ) {
-            setShouldShowDropdown(false);
+            setDropdownShown(false);
         }
         if (suggestionResponse?.replacementResults?.length) {
             suggestionResponse.replacementResults.forEach(
@@ -352,7 +359,7 @@ export const CodeAutocompleteField = ({
             setSuggestions([]);
         }
         setCurrentIndex(0);
-    }, [suggestionResponse, editorState]);
+    }, [suggestionResponse, editorState, setDropdownShown]);
 
     const getOffsetRange = (cm: EditorView, from: number, to: number) => {
         if (!cm) return { fromOffset: 0, toOffset: 0 };
@@ -365,15 +372,6 @@ export const CodeAutocompleteField = ({
         return { fromOffset, toOffset };
     };
 
-    const inputActionsDisplayed = React.useCallback((node: any) => {
-        if (!node) return;
-        const width = node.offsetWidth;
-        const slCodeEditor = node.parentElement.getElementsByClassName(`${eccgui}-singlelinecodeeditor`);
-        if (slCodeEditor.length > 0) {
-            slCodeEditor[0].style.paddingRight = `${width}px`;
-        }
-    }, []);
-
     const asyncCheckInput = useMemo(
         () => async (inputString: string) => {
             if (
@@ -448,6 +446,7 @@ export const CodeAutocompleteField = ({
     const handleChange = React.useMemo(() => {
         return (val: string) => {
             value.current = val;
+            setHasValue(!!val);
             checkValuePathValidity.cancel();
             checkValuePathValidity(value.current);
             onChange(val);
@@ -462,8 +461,8 @@ export const CodeAutocompleteField = ({
         cursorPosition.current = cursor - offsetFromFirstLine;
         // cursor change is fired after onChange, so we put the auto-complete logic here
         //get value at line
-        if (isFocused.current) {
-            setShouldShowDropdown(true);
+        if (isFocused.current && !suggestionsDismissed.current) {
+            setDropdownShown(true);
             handleEditorInputChange.cancel();
             handleEditorInputChange(value.current, cursorPosition.current);
         }
@@ -480,6 +479,20 @@ export const CodeAutocompleteField = ({
     };
 
     const handleInputEditorKeyPress = (event: KeyboardEvent) => {
+        if (event.key === OVERWRITTEN_KEYS.Escape) {
+            if (editorState.dropdownShown) {
+                suggestionsDismissed.current = true;
+
+                event.preventDefault();
+                handleEscapePressed();
+            }
+            // A closed dropdown lets CodeMirror handle Escape so the next Tab can leave the editor.
+            return true;
+        }
+        if (event.key === OVERWRITTEN_KEYS.Tab && !editorState.dropdownShown) {
+            return true;
+        }
+        suggestionsDismissed.current = false;
         const overWrittenKeys: Array<string> = Object.values(OVERWRITTEN_KEYS);
         if (overWrittenKeys.includes(event.key) && (useTabForCompletions || event.key !== OVERWRITTEN_KEYS.Tab)) {
             //don't prevent when enter should create new line (multiline config) and dropdown isn't shown
@@ -498,7 +511,7 @@ export const CodeAutocompleteField = ({
 
     const closeDropDown = () => {
         setHighlightedElement(undefined);
-        setShouldShowDropdown(false);
+        setDropdownShown(false);
     };
 
     const handleDropdownChange = (selectedSuggestion: CodeAutocompleteFieldSuggestionWithReplacementInfo) => {
@@ -525,19 +538,20 @@ export const CodeAutocompleteField = ({
         }
     };
 
-    const handleInputEditorClear = () => {
-        dispatch({
-            changes: { from: 0, to: cm?.state.doc.length, insert: "" },
+    const handleInputEditorClear = React.useCallback(() => {
+        currentCm.current?.dispatch({
+            changes: { from: 0, to: currentCm.current.state.doc.length, insert: "" },
         });
         cursorPosition.current = 0;
         handleChange("");
-        cm?.focus();
-    };
+        currentCm.current?.focus();
+    }, [handleChange]);
 
     const handleInputFocus = (focusState: boolean) => {
         onFocusChange?.(focusState);
         if (focusState) {
-            setShouldShowDropdown(true);
+            suggestionsDismissed.current = false;
+            setDropdownShown(true);
         } else {
             closeDropDown();
         }
@@ -556,6 +570,7 @@ export const CodeAutocompleteField = ({
     };
 
     const handleInputMouseDown = React.useCallback((editor: EditorView) => {
+        suggestionsDismissed.current = false;
         const cursor = editorState.cm?.state.selection.main.head;
         const currentLine = editorState.cm?.state.doc.lineAt(cursor ?? 0).number;
         const clickedLine = editor?.state.doc.lineAt(cursor ?? 0).number;
@@ -658,6 +673,17 @@ export const CodeAutocompleteField = ({
                 onMouseDown={handleInputMouseDown}
                 height={height}
                 readOnly={readOnly}
+                codeEditorProps={{
+                    actions: hasValue ? (
+                        <IconButton
+                            data-test-id="value-path-clear-btn"
+                            name="operation-clear"
+                            text={clearIconText}
+                            disabled={readOnly}
+                            onClick={handleInputEditorClear}
+                        />
+                    ) : undefined,
+                }}
             />
         );
     }, [
@@ -670,7 +696,11 @@ export const CodeAutocompleteField = ({
         showScrollBar,
         multiline,
         handleInputMouseDown,
+        height,
         readOnly,
+        hasValue,
+        clearIconText,
+        handleInputEditorClear,
         effectiveIntent,
     ]);
     const autoSuggestionInput = (
@@ -708,17 +738,6 @@ export const CodeAutocompleteField = ({
                 >
                     {codeEditor}
                 </ContextOverlay>
-                {!!value.current && (
-                    <span className={BlueprintClassNames.INPUT_ACTION} ref={inputActionsDisplayed}>
-                        <IconButton
-                            data-test-id={"value-path-clear-btn"}
-                            name="operation-clear"
-                            text={clearIconText}
-                            disabled={readOnly}
-                            onClick={handleInputEditorClear}
-                        />
-                    </span>
-                )}
             </div>
         </div>
     );

src/components/AutoSuggestion/tests/AutoSuggestion.test.tsx

@@ -1,5 +1,6 @@
 import React from "react";
-import { render } from "@testing-library/react";
+import { EditorView } from "@codemirror/view";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
 
 import "@testing-library/jest-dom";
 
@@ -49,4 +50,84 @@ describe("AutoSuggestion", () => {
         const { getByText } = render(<AutoSuggestion {...props} />);
         expect(getByText(props.label!)).toBeTruthy();
     });
+
+    it("renders and updates the clear action inside the editor scroller", async () => {
+        const { container } = render(<AutoSuggestion {...props} initialValue="value" clearIconText="Clear value" />);
+        const clearButton = container.querySelector<HTMLElement>("[data-test-id='value-path-clear-btn']");
+        const actions = container.querySelector(".eccgui-codeeditor__actions");
+
+        expect(actions).toContainElement(clearButton);
+        expect(actions?.parentElement).toHaveClass("cm-scroller");
+
+        fireEvent.click(clearButton!);
+
+        expect(props.onChange).toHaveBeenCalledWith("");
+        await waitFor(() => expect(container.querySelector(".eccgui-codeeditor__actions")).toBeNull());
+    });
+
+    it.each([false, true])("updates the container height (multiline: %s)", (multiline) => {
+        const { container, rerender } = render(<AutoSuggestion {...props} multiline={multiline} height={120} />);
+        const editorContainer = container.querySelector<HTMLElement>(".eccgui-codeeditor");
+        expect(editorContainer).toHaveStyle({ height: "120px" });
+
+        rerender(<AutoSuggestion {...props} multiline={multiline} height="10rem" />);
+        expect(editorContainer).toHaveStyle({ height: "10rem" });
+
+        rerender(<AutoSuggestion {...props} multiline={multiline} />);
+        expect(editorContainer?.style.height).toBe("");
+    });
+
+    it.each([
+        { multiline: false, useTabForCompletions: false },
+        { multiline: false, useTabForCompletions: true },
+        { multiline: true, useTabForCompletions: false },
+        { multiline: true, useTabForCompletions: true },
+    ])(
+        "separates closing suggestions from Escape then Tab navigation ($multiline, $useTabForCompletions)",
+        async ({ multiline, useTabForCompletions }) => {
+            render(
+                <AutoSuggestion
+                    {...props}
+                    initialValue="value"
+                    mode="json"
+                    multiline={multiline}
+                    useTabForCompletions={useTabForCompletions}
+                    autoCompletionRequestDelay={0}
+                    fetchSuggestions={(inputString, cursorPosition) => ({
+                        inputString,
+                        cursorPosition,
+                        replacementResults: [
+                            {
+                                replacementInterval: { from: 0, length: 5 },
+                                extractedQuery: "",
+                                replacements: [{ value: "completion" }],
+                            },
+                        ],
+                    })}
+                />,
+            );
+            const editor = screen.getByRole("textbox");
+            act(() => editor.focus());
+            expect(await screen.findByText("completion")).toBeVisible();
+            const view = EditorView.findFromDOM(editor);
+            act(() => view?.dispatch({ selection: { anchor: 0, head: 5 } }));
+            const initialContent = editor.textContent;
+
+            // With suggestions open, Escape only closes the dropdown.
+            expect(fireEvent.keyDown(editor, { key: "Escape", code: "Escape", keyCode: 27 })).toBe(false);
+
+            await waitFor(() => expect(screen.queryByText("completion")).not.toBeInTheDocument());
+            expect(editor).toHaveFocus();
+            expect(editor.textContent).toBe(initialContent);
+
+            expect(fireEvent.keyDown(editor, { key: "Tab", code: "Tab", keyCode: 9 })).toBe(false);
+            const contentAfterIndent = editor.textContent;
+            expect(contentAfterIndent).not.toBe(initialContent);
+
+            // Once the dropdown is closed, Escape enables CodeMirror's temporary tab-focus mode.
+            expect(fireEvent.keyDown(editor, { key: "Escape", code: "Escape", keyCode: 27 })).toBe(true);
+            expect(fireEvent.keyDown(editor, { key: "Tab", code: "Tab", keyCode: 9 })).toBe(true);
+            expect(editor.textContent).toBe(contentAfterIndent);
+        },
+    );
 });

src/extensions/codemirror/CodeMirror.stories.tsx

@@ -2,9 +2,10 @@ import React from "react";
 import { Meta, StoryFn } from "@storybook/react";
 
 import { helpersArgTypes } from "../../../.storybook/helpers";
+import { Button } from "../../components/Button/Button";
+import { FieldItem } from "../../components/Form/FieldItem";
 
 import { CodeEditor } from "./CodeMirror";
-import { FieldItem } from "../../components/Form/FieldItem";
 
 export default {
     title: "Extensions/CodeEditor",
@@ -58,6 +59,13 @@ LongContent.args = {
     ),
 };
 
+export const WithActions = TemplateFull.bind({});
+WithActions.args = {
+    ...BasicExample.args,
+    name: "editor-with-actions",
+    actions: <Button>Run</Button>,
+};
+
 export const MarkdownWithToolbar = TemplateFull.bind({});
 MarkdownWithToolbar.args = {
     name: "mdinput",