@neo4j-cypher/react-codemirror 2.0.0-next.0 → 2.0.0-next.10

package/src/CypherEditor.test.tsx

@@ -0,0 +1,200 @@
+// @vitest-environment jsdom
+
+import { EditorView } from '@codemirror/view';
+import { createRef } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { DEBOUNCE_TIME } from './constants';
+import { CypherEditor } from './CypherEditor';
+
+const container = document.createElement('div');
+let root: ReturnType<typeof createRoot>;
+
+const ref = createRef<CypherEditor>();
+let value = '';
+const onChange = vi.fn((v: string) => {
+  value = v;
+  rerender();
+});
+
+global.IS_REACT_ACT_ENVIRONMENT = true;
+const DEBOUNCE_TIME_WITH_MARGIN = DEBOUNCE_TIME + 100;
+
+/** Avoids crash in test environment */
+function mockEditorView(editorView: EditorView) {
+  editorView.coordsAtPos = vi.fn().mockReturnValue({
+    left: 0,
+    top: 0,
+    right: 0,
+    bottom: 0,
+  });
+}
+
+async function debounce() {
+  await new Promise((resolve) =>
+    setTimeout(resolve, DEBOUNCE_TIME_WITH_MARGIN),
+  );
+}
+
+function getEditorValue() {
+  return ref.current.editorView.current.state.doc.toString();
+}
+
+function rerender() {
+  act(() => {
+    root.render(<CypherEditor value={value} onChange={onChange} ref={ref} />);
+  });
+}
+
+beforeEach(() => {
+  root = createRoot(container);
+  act(() => {
+    root.render(<CypherEditor value={value} onChange={onChange} ref={ref} />);
+  });
+  mockEditorView(ref.current.editorView.current);
+});
+
+afterEach(() => {
+  act(() => {
+    root.unmount();
+  });
+  value = '';
+  vi.clearAllMocks();
+});
+
+test('editorValue updates props.value after debounce', async () => {
+  ref.current.setValueAndFocus('new value');
+  expect(onChange).not.toHaveBeenCalled();
+  expect(getEditorValue()).toBe('new value');
+  expect(value).toBe('');
+  await debounce();
+
+  expect(onChange).toHaveBeenCalledOnce();
+  expect(getEditorValue()).toBe('new value');
+  expect(value).toBe('new value');
+});
+
+test('editorValue updates should not be applied twice', async () => {
+  const dispatch = vi.spyOn(ref.current.editorView.current, 'dispatch');
+
+  ref.current.setValueAndFocus('new value');
+  await debounce();
+
+  expect(onChange).toHaveBeenCalledOnce();
+  expect(dispatch).toHaveBeenCalledOnce(); // it gets called once for the initial setValueAndFocus
+});
+
+test('props.value updates editorValue', () => {
+  value = 'external value';
+  rerender();
+
+  expect(getEditorValue()).toBe('external value');
+  expect(value).toBe('external value');
+});
+
+test('props.value set to undefined preserves editorValue', () => {
+  // 1. value is set initially
+  value = 'initial';
+  rerender();
+
+  // 2. value is set to undefined
+  value = undefined;
+  rerender();
+
+  expect(onChange).not.toHaveBeenCalled();
+  expect(value).toBeUndefined();
+  expect(getEditorValue()).toBe('initial');
+});
+
+// value updates from outside onExecute are overwritten by pending updates
+test.fails('new props.value should cancel onChange', async () => {
+  // 1. value is updated internally
+  ref.current.setValueAndFocus('update');
+
+  // 2. editor is rerendered with a new value while a value update is still pending
+  value = 'new external value';
+  rerender();
+
+  await debounce();
+
+  // expect(onChange).not.toHaveBeenCalled();
+  expect(getEditorValue()).toBe('new external value');
+  expect(value).toBe('new external value');
+});
+
+// value updates from outside onExecute are overwritten by pending updates
+test.fails(
+  'new props.value set to same value should cancel onChange',
+  async () => {
+    // 1. value is set initially
+    value = 'same value';
+    rerender();
+
+    // 2. value is updated internally
+    ref.current.setValueAndFocus('update');
+
+    // 3. editor is rerendered with a new value while a value update is still pending
+    value = 'same value';
+    rerender();
+
+    await debounce();
+
+    // expect(onChange).not.toHaveBeenCalled();
+    expect(getEditorValue()).toBe('same value');
+    expect(value).toBe('same value');
+  },
+);
+
+test('rerender should not cancel onChange', async () => {
+  // 1. value is updated internally
+  ref.current.setValueAndFocus('changed');
+
+  // 2. editor is rerendered while a value update is still pending
+  rerender();
+
+  await debounce();
+
+  expect(onChange).toHaveBeenCalledOnce();
+  expect(getEditorValue()).toBe('changed');
+  expect(value).toBe('changed');
+});
+
+test('rerender with a previous update should not cancel onChange', async () => {
+  // 1. value is updated internally
+  ref.current.setValueAndFocus('changed');
+  await debounce();
+
+  // 2. value is updated internally again
+  ref.current.setValueAndFocus('new change');
+
+  // 3. editor is rerendered while a value update is still pending
+  rerender();
+
+  await debounce();
+
+  expect(onChange).toHaveBeenCalledTimes(2);
+  expect(getEditorValue()).toBe('new change');
+  expect(value).toBe('new change');
+});
+
+test('rerender with prior external update should not cancel onChange', async () => {
+  // 1. value is set initially
+  ref.current.setValueAndFocus('initial');
+  await debounce();
+
+  // 2. value is updated externally
+  value = 'external update';
+  rerender();
+
+  // 3. value is updated internally
+  ref.current.setValueAndFocus('internal update');
+
+  // 4. editor is rerendered while a value update is still pending
+  rerender();
+
+  await debounce();
+
+  expect(getEditorValue()).toBe('internal update');
+  expect(value).toBe('internal update');
+});

package/src/CypherEditor.tsx

@@ -1,3 +1,4 @@
+import { insertNewline } from '@codemirror/commands';
 import {
   Annotation,
   Compartment,
@@ -9,15 +10,23 @@ import {
   KeyBinding,
   keymap,
   lineNumbers,
+  placeholder,
   ViewUpdate,
 } from '@codemirror/view';
-import type { DbSchema } from '@neo4j-cypher/language-support';
+import { type DbSchema } from '@neo4j-cypher/language-support';
+import debounce from 'lodash.debounce';
 import { Component, createRef } from 'react';
-import { cypher, CypherConfig } from './lang-cypher/lang-cypher';
-import { basicNeo4jSetup } from './neo4j-setup';
-import { replMode } from './repl-mode';
+import { DEBOUNCE_TIME } from './constants';
+import {
+  replaceHistory,
+  replMode as historyNavigation,
+} from './historyNavigation';
+import { cypher, CypherConfig } from './lang-cypher/langCypher';
+import { cleanupWorkers } from './lang-cypher/syntaxValidation';
+import { basicNeo4jSetup } from './neo4jSetup';
 import { getThemeExtension } from './themes';
 
+type DomEventHandlers = Parameters<typeof EditorView.domEventHandlers>[0];
 export interface CypherEditorProps {
   /**
    * The prompt to show on single line editors
@@ -37,15 +46,17 @@ export interface CypherEditorProps {
    */
   onExecute?: (cmd: string) => void;
   /**
-   * Seed the editor history with some initial history entries
-   * Navigateable via up/down arrow keys
+   * If true, pressing enter will add a new line to the editor and cmd/ctrl + enter will execute the query.
+   * Otherwise pressing enter on a single line will execute the query.
+   *
+   * @default false
    */
-  initialHistory?: string[];
+  newLineOnEnter?: boolean;
   /**
-   * Callback when a new history entry is added, useful for keeping track of history
-   * outside of the editor.
+   * The editor history navigable via up/down arrow keys. Order newest to oldest.
+   * Add to this list with the `onExecute` callback for REPL style history.
    */
-  onNewHistoryEntry?: (historyEntry: string) => void;
+  history?: string[];
   /**
    * When set to `true` the editor will use the background color of the parent element.
    *
@@ -59,6 +70,10 @@ export interface CypherEditorProps {
    * @default false
    */
   autofocus?: boolean;
+  /**
+   * Where to place the cursor in the query. Cannot be enabled at the same time than autofocus
+   */
+  offset?: number;
   /**
    * Whether the editor should wrap lines.
    *
@@ -71,6 +86,21 @@ export interface CypherEditorProps {
    * @default true
    */
   lint?: boolean;
+  /**
+   * Whether the signature help tooltip should be shown below the text.
+   * If false, it will be shown above.
+   *
+   * @default true
+   */
+  showSignatureTooltipBelow?: boolean;
+  /**
+   * Internal feature flags for the editor. Don't use in production
+   *
+   */
+  featureFlags?: {
+    consoleCommands?: boolean;
+    signatureInfoOnAutoCompletions?: boolean;
+  };
   /**
    * The schema to use for autocompletion and linting.
    *
@@ -98,13 +128,130 @@ export interface CypherEditorProps {
    * @param {ViewUpdate} viewUpdate - the view update from codemirror
    */
   onChange?(value: string, viewUpdate: ViewUpdate): void;
+
+  /**
+   * Map of event handlers to add to the editor.
+   *
+   * Note that the props are compared by reference, meaning object defined inline
+   * will cause the editor to re-render (much like the style prop does in this example:
+   * <div style={{}} />
+   *
+   * Memoize the object if you want/need to avoid this.
+   *
+   * @example
+   * // listen to blur events
+   * <CypherEditor domEventHandlers={{blur: () => console.log("blur event fired")}} />
+   */
+  domEventHandlers?: DomEventHandlers;
+  /**
+   * Placeholder text to display when the editor is empty.
+   */
+  placeholder?: string;
+  /**
+   * Whether the editor should show line numbers.
+   *
+   * @default true
+   */
+  lineNumbers?: boolean;
+  /**
+   * Whether the editor is read-only.
+   *
+   * @default false
+   */
+  readonly?: boolean;
+
+  /**
+   * String value to assign to the aria-label attribute of the editor
+   */
+  ariaLabel?: string;
 }
 
+const executeKeybinding = (
+  onExecute?: (cmd: string) => void,
+  newLineOnEnter?: boolean,
+  flush?: () => void,
+) => {
+  const keybindings: Record<string, KeyBinding> = {
+    'Shift-Enter': {
+      key: 'Shift-Enter',
+      run: insertNewline,
+    },
+    'Ctrl-Enter': {
+      key: 'Ctrl-Enter',
+      run: () => true,
+    },
+    Enter: {
+      key: 'Enter',
+      run: insertNewline,
+    },
+  };
+
+  if (onExecute) {
+    keybindings['Ctrl-Enter'] = {
+      key: 'Ctrl-Enter',
+      mac: 'Mod-Enter',
+      preventDefault: true,
+      run: (view: EditorView) => {
+        const doc = view.state.doc.toString();
+        if (doc.trim() !== '') {
+          flush?.();
+          onExecute(doc);
+        }
+
+        return true;
+      },
+    };
+
+    if (!newLineOnEnter) {
+      keybindings['Enter'] = {
+        key: 'Enter',
+        preventDefault: true,
+        run: (view: EditorView) => {
+          const doc = view.state.doc.toString();
+          if (doc.includes('\n')) {
+            // Returning false means the event will mark the event
+            // as not handled and the default behavior will be executed
+            return false;
+          }
+
+          if (doc.trim() !== '') {
+            flush?.();
+            onExecute(doc);
+          }
+
+          return true;
+        },
+      };
+    }
+  }
+
+  return Object.values(keybindings);
+};
+
 const themeCompartment = new Compartment();
 const keyBindingCompartment = new Compartment();
+const lineNumbersCompartment = new Compartment();
+const readOnlyCompartment = new Compartment();
+const placeholderCompartment = new Compartment();
+const domEventHandlerCompartment = new Compartment();
+
+const formatLineNumber =
+  (prompt?: string) => (a: number, state: EditorState) => {
+    if (state.doc.lines === 1 && prompt !== undefined) {
+      return prompt;
+    }
+
+    return a.toString();
+  };
+
+type CypherEditorState = { cypherSupportEnabled: boolean };
 
 const ExternalEdit = Annotation.define<boolean>();
-export class CypherEditor extends Component<CypherEditorProps> {
+
+export class CypherEditor extends Component<
+  CypherEditorProps,
+  CypherEditorState
+> {
   /**
    * The codemirror editor container.
    */
@@ -157,41 +304,59 @@ export class CypherEditor extends Component<CypherEditorProps> {
     schema: {},
     overrideThemeBackgroundColor: false,
     lineWrap: false,
+    showSignatureTooltipBelow: true,
     extraKeybindings: [],
-    initialHistory: [],
+    history: [],
     theme: 'light',
+    lineNumbers: true,
+    newLineOnEnter: false,
   };
 
+  private debouncedOnChange = this.props.onChange
+    ? debounce(
+        ((value, viewUpdate) => {
+          this.props.onChange(value, viewUpdate);
+        }) satisfies CypherEditorProps['onChange'],
+        DEBOUNCE_TIME,
+      )
+    : undefined;
+
   componentDidMount(): void {
     const {
       theme,
-      onExecute,
-      initialHistory,
-      onNewHistoryEntry,
       extraKeybindings,
       lineWrap,
       overrideThemeBackgroundColor,
       schema,
       lint,
-      onChange,
+      showSignatureTooltipBelow,
+      featureFlags,
+      onExecute,
+      newLineOnEnter,
     } = this.props;
 
-    this.schemaRef.current = { schema, lint };
-
-    const maybeReplMode = onExecute
-      ? replMode({
-          onExecute,
-          initialHistory,
-          onNewHistoryEntry,
-        })
-      : [];
+    this.schemaRef.current = {
+      schema,
+      lint,
+      showSignatureTooltipBelow,
+      featureFlags: {
+        consoleCommands: true,
+        ...featureFlags,
+      },
+      useLightVersion: false,
+      setUseLightVersion: (newVal) => {
+        if (this.schemaRef.current !== undefined) {
+          this.schemaRef.current.useLightVersion = newVal;
+        }
+      },
+    };
 
     const themeExtension = getThemeExtension(
       theme,
       overrideThemeBackgroundColor,
     );
 
-    const changeListener = onChange
+    const changeListener = this.debouncedOnChange
       ? [
           EditorView.updateListener.of((upt: ViewUpdate) => {
             const wasUserEdit = !upt.transactions.some((tr) =>
@@ -201,7 +366,7 @@ export class CypherEditor extends Component<CypherEditorProps> {
             if (upt.docChanged && wasUserEdit) {
               const doc = upt.state.doc;
               const value = doc.toString();
-              onChange(value, upt);
+              this.debouncedOnChange(value, upt);
             }
           }),
         ]
@@ -209,23 +374,40 @@ export class CypherEditor extends Component<CypherEditorProps> {
 
     this.editorState.current = EditorState.create({
       extensions: [
-        maybeReplMode,
+        keyBindingCompartment.of(
+          keymap.of([
+            ...executeKeybinding(onExecute, newLineOnEnter, () =>
+              this.debouncedOnChange?.flush(),
+            ),
+            ...extraKeybindings,
+          ]),
+        ),
+        historyNavigation(this.props),
         basicNeo4jSetup(),
         themeCompartment.of(themeExtension),
         changeListener,
         cypher(this.schemaRef.current),
-        keyBindingCompartment.of(keymap.of(extraKeybindings)),
         lineWrap ? EditorView.lineWrapping : [],
 
-        lineNumbers({
-          formatNumber: (a, state) => {
-            if (state.doc.lines === 1 && this.props.prompt !== undefined) {
-              return this.props.prompt;
-            }
-
-            return a.toString();
-          },
-        }),
+        lineNumbersCompartment.of(
+          this.props.lineNumbers
+            ? lineNumbers({ formatNumber: formatLineNumber(this.props.prompt) })
+            : [],
+        ),
+        readOnlyCompartment.of(EditorState.readOnly.of(this.props.readonly)),
+        placeholderCompartment.of(
+          this.props.placeholder ? placeholder(this.props.placeholder) : [],
+        ),
+        domEventHandlerCompartment.of(
+          this.props.domEventHandlers
+            ? EditorView.domEventHandlers(this.props.domEventHandlers)
+            : [],
+        ),
+        this.props.ariaLabel
+          ? EditorView.contentAttributes.of({
+              'aria-label': this.props.ariaLabel,
+            })
+          : [],
       ],
       doc: this.props.value,
     });
@@ -240,6 +422,8 @@ export class CypherEditor extends Component<CypherEditorProps> {
       if (this.props.value) {
         this.updateCursorPosition(this.props.value.length);
       }
+    } else if (this.props.offset) {
+      this.updateCursorPosition(this.props.offset);
     }
   }
 
@@ -251,7 +435,11 @@ export class CypherEditor extends Component<CypherEditorProps> {
     // Handle externally set value
     const currentCmValue = this.editorView.current.state?.doc.toString() ?? '';
 
-    if (this.props.value !== undefined && currentCmValue !== this.props.value) {
+    if (
+      this.props.value !== undefined && // If the component becomes uncontolled, we just leave the value as is
+      this.props.value !== prevProps.value && // The value prop has changed, we need to update the editor
+      this.props.value !== currentCmValue // No need to dispatch an update if the value is the same
+    ) {
       this.editorView.current.dispatch({
         changes: {
           from: 0,
@@ -279,14 +467,75 @@ export class CypherEditor extends Component<CypherEditorProps> {
       });
     }
 
-    if (prevProps.extraKeybindings !== this.props.extraKeybindings) {
+    if (
+      prevProps.lineNumbers !== this.props.lineNumbers ||
+      prevProps.prompt !== this.props.prompt
+    ) {
+      this.editorView.current.dispatch({
+        effects: lineNumbersCompartment.reconfigure(
+          this.props.lineNumbers
+            ? lineNumbers({ formatNumber: formatLineNumber(this.props.prompt) })
+            : [],
+        ),
+      });
+    }
+
+    if (prevProps.readonly !== this.props.readonly) {
+      this.editorView.current.dispatch({
+        effects: readOnlyCompartment.reconfigure(
+          EditorState.readOnly.of(this.props.readonly),
+        ),
+      });
+    }
+
+    if (prevProps.placeholder !== this.props.placeholder) {
+      this.editorView.current.dispatch({
+        effects: placeholderCompartment.reconfigure(
+          this.props.placeholder ? placeholder(this.props.placeholder) : [],
+        ),
+      });
+    }
+
+    if (
+      prevProps.extraKeybindings !== this.props.extraKeybindings ||
+      prevProps.onExecute !== this.props.onExecute
+    ) {
       this.editorView.current.dispatch({
         effects: keyBindingCompartment.reconfigure(
-          keymap.of(this.props.extraKeybindings),
+          keymap.of([
+            ...executeKeybinding(
+              this.props.onExecute,
+              this.props.newLineOnEnter,
+              () => this.debouncedOnChange?.flush(),
+            ),
+            ...this.props.extraKeybindings,
+          ]),
+        ),
+      });
+    }
+
+    if (prevProps.domEventHandlers !== this.props.domEventHandlers) {
+      this.editorView.current.dispatch({
+        effects: domEventHandlerCompartment.reconfigure(
+          this.props.domEventHandlers
+            ? EditorView.domEventHandlers(this.props.domEventHandlers)
+            : [],
         ),
       });
     }
 
+    // This component rerenders on every keystroke and comparing the
+    // full lists of editor strings on every render could be expensive.
+    const didChangeHistoryEstimate =
+      prevProps.history?.length !== this.props.history?.length ||
+      prevProps.history?.[0] !== this.props.history?.[0];
+
+    if (didChangeHistoryEstimate) {
+      this.editorView.current.dispatch({
+        effects: replaceHistory.of(this.props.history ?? []),
+      });
+    }
+
     /*
     The cypher configuration is a mutable object that is passed to the cypher language extension.
     Much like how the schema based completions work in the official sql language extension.
@@ -294,10 +543,12 @@ export class CypherEditor extends Component<CypherEditorProps> {
     */
     this.schemaRef.current.schema = this.props.schema;
     this.schemaRef.current.lint = this.props.lint;
+    this.schemaRef.current.featureFlags = this.props.featureFlags;
   }
 
   componentWillUnmount(): void {
     this.editorView.current?.destroy();
+    cleanupWorkers();
   }
 
   render(): React.ReactNode {

package/src/constants.ts

@@ -0,0 +1 @@
+export const DEBOUNCE_TIME = 200;