@neo4j-cypher/react-codemirror 2.0.0-alpha.0 → 2.0.0-canary-e8a1279

package/src/CypherEditor.tsx

@@ -0,0 +1,461 @@
+import {
+  Annotation,
+  Compartment,
+  EditorState,
+  Extension,
+} from '@codemirror/state';
+import {
+  EditorView,
+  KeyBinding,
+  keymap,
+  lineNumbers,
+  placeholder,
+  ViewUpdate,
+} from '@codemirror/view';
+import type { DbSchema } from '@neo4j-cypher/language-support';
+import debounce from 'lodash.debounce';
+import { Component, createRef } from 'react';
+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
+   */
+  prompt?: string;
+  /**
+   * Custom keybindings to add to the editor.
+   * See https://codemirror.net/6/docs/ref/#keymap.of
+   */
+  extraKeybindings?: KeyBinding[];
+  /**
+   * Callback on query execution, triggered via ctrl/cmd + Enter.
+   * If provided, will enable "repl-mode", which turns on navigating editor history
+   *
+   * @param cmd - the editor value when ctrl/cmd + enter was pressed
+   * @returns void
+   */
+  onExecute?: (cmd: string) => void;
+  /**
+   * 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.
+   */
+  history?: string[];
+  /**
+   * When set to `true` the editor will use the background color of the parent element.
+   *
+   * @default false
+   */
+  overrideThemeBackgroundColor?: boolean;
+  /**
+   * Whether the editor should take focus on mount.
+   * Will move the cursor to the end of the query when provided with an initial value.
+   *
+   * @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.
+   *
+   * @default false
+   */
+  lineWrap?: boolean;
+  /**
+   * Whether the editor should perform syntax validation.
+   *
+   * @default true
+   */
+  lint?: boolean;
+  /**
+   * The schema to use for autocompletion and linting.
+   *
+   * @type {DbSchema}
+   */
+  schema?: DbSchema;
+  /**
+   * The current value of the editor.
+   */
+  value?: string;
+  /**
+   * Extra css classnames to add to the editor container.
+   */
+  className?: string;
+  /**
+   * Set the built in theme or provide a custom theme.
+   *
+   * `light` / `dark` / `Extension`
+   *  @default light
+   */
+  theme?: 'light' | 'dark' | Extension;
+  /**
+   * Callback when the editor value changes.
+   * @param {string} value - the current editor value
+   * @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;
+}
+
+const executeKeybinding = (onExecute?: (cmd: string) => void) =>
+  onExecute
+    ? [
+        {
+          key: 'Ctrl-Enter',
+          mac: 'Mod-Enter',
+          preventDefault: true,
+          run: (view: EditorView) => {
+            const doc = view.state.doc.toString();
+            if (doc.trim() !== '') {
+              onExecute(doc);
+            }
+
+            return true;
+          },
+        },
+      ]
+    : [];
+
+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,
+  CypherEditorState
+> {
+  /**
+   * The codemirror editor container.
+   */
+  editorContainer: React.RefObject<HTMLDivElement> = createRef();
+  /**
+   * The codemirror editor state.
+   */
+  editorState: React.MutableRefObject<EditorState> = createRef();
+  /**
+   * The codemirror editor view.
+   */
+  editorView: React.MutableRefObject<EditorView> = createRef();
+  private schemaRef: React.MutableRefObject<CypherConfig> = createRef();
+
+  /**
+   * Focus the editor
+   */
+  focus() {
+    this.editorView.current?.focus();
+  }
+
+  /**
+   * Move the cursor to the supplied position.
+   * For example, to move the cursor to the end of the editor, use `value.length`
+   */
+  updateCursorPosition(position: number) {
+    this.editorView.current?.dispatch({
+      selection: { anchor: position, head: position },
+    });
+  }
+
+  /**
+   * Externally set the editor value and focus the editor.
+   */
+  setValueAndFocus(value = '') {
+    const currentCmValue = this.editorView.current.state?.doc.toString() ?? '';
+    this.editorView.current.dispatch({
+      changes: {
+        from: 0,
+        to: currentCmValue.length,
+        insert: value,
+      },
+      selection: { anchor: value.length, head: value.length },
+    });
+    this.editorView.current?.focus();
+  }
+
+  static defaultProps: CypherEditorProps = {
+    lint: true,
+    schema: {},
+    overrideThemeBackgroundColor: false,
+    lineWrap: false,
+    extraKeybindings: [],
+    history: [],
+    theme: 'light',
+    lineNumbers: true,
+  };
+
+  private debouncedOnChange = this.props.onChange
+    ? debounce(this.props.onChange, 200)
+    : undefined;
+
+  componentDidMount(): void {
+    const {
+      theme,
+      extraKeybindings,
+      lineWrap,
+      overrideThemeBackgroundColor,
+      schema,
+      lint,
+      onExecute,
+    } = this.props;
+
+    this.schemaRef.current = {
+      schema,
+      lint,
+      useLightVersion: false,
+      setUseLightVersion: (newVal) => {
+        if (this.schemaRef.current !== undefined) {
+          this.schemaRef.current.useLightVersion = newVal;
+        }
+      },
+    };
+
+    const themeExtension = getThemeExtension(
+      theme,
+      overrideThemeBackgroundColor,
+    );
+
+    const changeListener = this.debouncedOnChange
+      ? [
+          EditorView.updateListener.of((upt: ViewUpdate) => {
+            const wasUserEdit = !upt.transactions.some((tr) =>
+              tr.annotation(ExternalEdit),
+            );
+
+            if (upt.docChanged && wasUserEdit) {
+              const doc = upt.state.doc;
+              const value = doc.toString();
+              this.debouncedOnChange(value, upt);
+            }
+          }),
+        ]
+      : [];
+
+    this.editorState.current = EditorState.create({
+      extensions: [
+        keyBindingCompartment.of(
+          keymap.of([...executeKeybinding(onExecute), ...extraKeybindings]),
+        ),
+        historyNavigation(this.props),
+        basicNeo4jSetup(),
+        themeCompartment.of(themeExtension),
+        changeListener,
+        cypher(this.schemaRef.current),
+        lineWrap ? EditorView.lineWrapping : [],
+
+        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)
+            : [],
+        ),
+      ],
+      doc: this.props.value,
+    });
+
+    this.editorView.current = new EditorView({
+      state: this.editorState.current,
+      parent: this.editorContainer.current,
+    });
+
+    if (this.props.autofocus) {
+      this.focus();
+      if (this.props.value) {
+        this.updateCursorPosition(this.props.value.length);
+      }
+    } else if (this.props.offset) {
+      this.updateCursorPosition(this.props.offset);
+    }
+  }
+
+  componentDidUpdate(prevProps: CypherEditorProps): void {
+    if (!this.editorView.current) {
+      return;
+    }
+
+    // Handle externally set value
+    const currentCmValue = this.editorView.current.state?.doc.toString() ?? '';
+
+    if (this.props.value !== undefined && currentCmValue !== this.props.value) {
+      this.editorView.current.dispatch({
+        changes: {
+          from: 0,
+          to: currentCmValue.length,
+          insert: this.props.value ?? '',
+        },
+        annotations: [ExternalEdit.of(true)],
+      });
+    }
+
+    // Handle theme change
+    const didChangeTheme =
+      prevProps.theme !== this.props.theme ||
+      prevProps.overrideThemeBackgroundColor !==
+        this.props.overrideThemeBackgroundColor;
+
+    if (didChangeTheme) {
+      this.editorView.current.dispatch({
+        effects: themeCompartment.reconfigure(
+          getThemeExtension(
+            this.props.theme,
+            this.props.overrideThemeBackgroundColor,
+          ),
+        ),
+      });
+    }
+
+    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([
+            ...executeKeybinding(this.props.onExecute),
+            ...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.
+    https://github.com/codemirror/lang-sql/blob/4b7b2564dff7cdb1a15f8ccd08142f2cc8a0006f/src/sql.ts#L178C17-L178C18
+    */
+    this.schemaRef.current.schema = this.props.schema;
+    this.schemaRef.current.lint = this.props.lint;
+  }
+
+  componentWillUnmount(): void {
+    this.editorView.current?.destroy();
+    cleanupWorkers();
+  }
+
+  render(): React.ReactNode {
+    const { className, theme } = this.props;
+
+    const themeClass =
+      typeof theme === 'string' ? `cm-theme-${theme}` : 'cm-theme';
+
+    return (
+      <div
+        ref={this.editorContainer}
+        className={`${themeClass}${className ? ` ${className}` : ''}`}
+      />
+    );
+  }
+}

package/src/e2e_tests/autoCompletion.spec.tsx

@@ -0,0 +1,236 @@
+import { testData } from '@neo4j-cypher/language-support';
+import { expect, test } from '@playwright/experimental-ct-react';
+import { CypherEditor } from '../CypherEditor';
+
+test.use({ viewport: { width: 500, height: 500 } });
+
+test('hello world end 2 end test', async ({ mount }) => {
+  const component = await mount(<CypherEditor value="hello world" />);
+  await expect(component).toContainText('hello world');
+  await component.update(<CypherEditor value="RETURN 123" />);
+  await expect(component).toContainText('RETURN 123');
+});
+
+test('can complete in the middle of statement', async ({ mount, page }) => {
+  const component = await mount(
+    <CypherEditor
+      value={`MATCH ()
+WHER true
+RETURN n;`}
+    />,
+  );
+
+  // Move into the statement and trigger autocompletion
+  const textField = page.getByRole('textbox');
+
+  await textField.focus();
+  await textField.press('ArrowDown');
+  await textField.press('ArrowRight');
+  await textField.press('ArrowRight');
+  await textField.press('ArrowRight');
+  await textField.press('ArrowRight');
+
+  await textField.press('Control+ ');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+  await page.locator('.cm-tooltip-autocomplete').getByText('WHERE').click();
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('WHERE true');
+});
+
+test('get completions when typing and can accept completions with tab', async ({
+  mount,
+  page,
+}) => {
+  const component = await mount(<CypherEditor />);
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('RETU');
+
+  await expect(
+    page.locator('.cm-tooltip-autocomplete').getByText('RETURN'),
+  ).toBeVisible();
+
+  // We need to wait for the editor to realise there is a completion open
+  // so that it does not just indent with tab key
+  await page.waitForTimeout(500);
+  await textField.press('Tab');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('RETURN');
+});
+
+test('can complete labels', async ({ mount, page }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        labels: ['Pokemon'],
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('MATCH (n :P');
+
+  await page.locator('.cm-tooltip-autocomplete').getByText('Pokemon').click();
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('MATCH (n :Pokemon');
+});
+
+test('can update dbschema', async ({ mount, page }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        labels: ['Pokemon'],
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('MATCH (n :');
+
+  await expect(
+    page.locator('.cm-tooltip-autocomplete').getByText('Pokemon'),
+  ).toBeVisible();
+
+  await textField.press('Escape');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await component.update(
+    <CypherEditor
+      schema={{
+        labels: ['Pokemon', 'Digimon'],
+      }}
+    />,
+  );
+
+  await textField.press('Control+ ');
+
+  await expect(
+    page.locator('.cm-tooltip-autocomplete').getByText('Pokemon'),
+  ).toBeVisible();
+
+  await expect(
+    page.locator('.cm-tooltip-autocomplete').getByText('Digimon'),
+  ).toBeVisible();
+});
+
+test('can complete rel types', async ({ page, mount }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        relationshipTypes: ['KNOWS'],
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('MATCH (n)-[:');
+
+  await page.locator('.cm-tooltip-autocomplete').getByText('KNOWS').click();
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('MATCH (n)-[:KNOWS');
+});
+
+test('can complete functions', async ({ page, mount }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        functions: {
+          function123: {
+            ...testData.emptyFunction,
+            name: 'function123',
+          },
+        },
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('RETURN func');
+
+  await page
+    .locator('.cm-tooltip-autocomplete')
+    .getByText('function123')
+    .click();
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('RETURN function123');
+});
+
+test('can complete procedures', async ({ page, mount }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        procedures: {
+          'db.ping': { ...testData.emptyProcedure, name: 'db.ping' },
+        },
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('CALL d');
+
+  await page.locator('.cm-tooltip-autocomplete').getByText('db.ping').click();
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('CALL db.ping');
+});
+
+test('can complete parameters', async ({ page, mount }) => {
+  const component = await mount(
+    <CypherEditor
+      schema={{
+        parameters: { parameter: { type: 'string' } },
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  await textField.fill('RETURN $p');
+
+  await page.locator('.cm-tooltip-autocomplete').getByText('parameter').click();
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  await expect(component).toContainText('RETURN $parameter');
+});
+
+test('completes allShortestPaths correctly', async ({ page, mount }) => {
+  await mount(
+    <CypherEditor
+      schema={{
+        parameters: { parameter: { type: 'string' } },
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+
+  // The first query contains errors on purpose so the
+  // syntax errors get triggered before the auto-completion
+  await textField.fill('MATCH (n) REURN n; MATCH a');
+
+  await page
+    .locator('.cm-tooltip-autocomplete')
+    .getByText('allShortestPaths')
+    .click();
+  await expect(page.locator('.cm-tooltip-autocomplete')).not.toBeVisible();
+
+  expect(await textField.textContent()).toEqual(
+    'MATCH (n) REURN n; MATCH allShortestPaths',
+  );
+});