@neo4j-cypher/react-codemirror 2.0.0-next.8 → 2.0.0-next.9

package/src/CypherEditor.tsx

@@ -1,3 +1,4 @@
+import { insertNewline } from '@codemirror/commands';
 import {
   Annotation,
   Compartment,
@@ -12,7 +13,7 @@ import {
   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 {
@@ -43,6 +44,13 @@ export interface CypherEditorProps {
    * @returns void
    */
   onExecute?: (cmd: string) => void;
+  /**
+   * 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
+   */
+  newLineOnEnter?: boolean;
   /**
    * 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.
@@ -77,6 +85,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.
    *
@@ -135,26 +158,74 @@ export interface CypherEditorProps {
    * @default false
    */
   readonly?: boolean;
+
+  /**
+   * String value to assign to the aria-label attribute of the editor
+   */
+  ariaLabel?: string;
 }
 
-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);
-            }
+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;
+      },
+    };
 
-            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();
@@ -194,6 +265,8 @@ export class CypherEditor extends Component<
   editorView: React.MutableRefObject<EditorView> = createRef();
   private schemaRef: React.MutableRefObject<CypherConfig> = createRef();
 
+  private latestDispatchedValue: string | undefined;
+
   /**
    * Focus the editor
    */
@@ -232,14 +305,22 @@ export class CypherEditor extends Component<
     schema: {},
     overrideThemeBackgroundColor: false,
     lineWrap: false,
+    showSignatureTooltipBelow: true,
     extraKeybindings: [],
     history: [],
     theme: 'light',
     lineNumbers: true,
+    newLineOnEnter: false,
   };
 
   private debouncedOnChange = this.props.onChange
-    ? debounce(this.props.onChange, 200)
+    ? debounce(
+        ((value, viewUpdate) => {
+          this.latestDispatchedValue = value;
+          this.props.onChange(value, viewUpdate);
+        }) satisfies CypherEditorProps['onChange'],
+        200,
+      )
     : undefined;
 
   componentDidMount(): void {
@@ -250,12 +331,20 @@ export class CypherEditor extends Component<
       overrideThemeBackgroundColor,
       schema,
       lint,
+      showSignatureTooltipBelow,
+      featureFlags,
       onExecute,
+      newLineOnEnter,
     } = this.props;
 
     this.schemaRef.current = {
       schema,
       lint,
+      showSignatureTooltipBelow,
+      featureFlags: {
+        consoleCommands: true,
+        ...featureFlags,
+      },
       useLightVersion: false,
       setUseLightVersion: (newVal) => {
         if (this.schemaRef.current !== undefined) {
@@ -285,10 +374,17 @@ export class CypherEditor extends Component<
         ]
       : [];
 
+    this.latestDispatchedValue = this.props.value;
+
     this.editorState.current = EditorState.create({
       extensions: [
         keyBindingCompartment.of(
-          keymap.of([...executeKeybinding(onExecute), ...extraKeybindings]),
+          keymap.of([
+            ...executeKeybinding(onExecute, newLineOnEnter, () =>
+              this.debouncedOnChange.flush(),
+            ),
+            ...extraKeybindings,
+          ]),
         ),
         historyNavigation(this.props),
         basicNeo4jSetup(),
@@ -311,6 +407,11 @@ export class CypherEditor extends Component<
             ? EditorView.domEventHandlers(this.props.domEventHandlers)
             : [],
         ),
+        this.props.ariaLabel
+          ? EditorView.contentAttributes.of({
+              'aria-label': this.props.ariaLabel,
+            })
+          : [],
       ],
       doc: this.props.value,
     });
@@ -338,7 +439,11 @@ export class CypherEditor extends Component<
     // 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 &&
+      this.props.value !== this.latestDispatchedValue
+    ) {
+      this.debouncedOnChange?.cancel();
       this.editorView.current.dispatch({
         changes: {
           from: 0,
@@ -402,7 +507,11 @@ export class CypherEditor extends Component<
       this.editorView.current.dispatch({
         effects: keyBindingCompartment.reconfigure(
           keymap.of([
-            ...executeKeybinding(this.props.onExecute),
+            ...executeKeybinding(
+              this.props.onExecute,
+              this.props.newLineOnEnter,
+              () => this.debouncedOnChange.flush(),
+            ),
             ...this.props.extraKeybindings,
           ]),
         ),
@@ -438,6 +547,7 @@ export class CypherEditor extends Component<
     */
     this.schemaRef.current.schema = this.props.schema;
     this.schemaRef.current.lint = this.props.lint;
+    this.schemaRef.current.featureFlags = this.props.featureFlags;
   }
 
   componentWillUnmount(): void {

package/src/e2e_tests/autoCompletion.spec.tsx

@@ -1,9 +1,8 @@
 import { testData } from '@neo4j-cypher/language-support';
 import { expect, test } from '@playwright/experimental-ct-react';
+import type { Page } from '@playwright/test';
 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');
@@ -234,3 +233,208 @@ test('completes allShortestPaths correctly', async ({ page, mount }) => {
     'MATCH (n) REURN n; MATCH allShortestPaths',
   );
 });
+
+async function getInfoTooltip(page: Page, methodName: string) {
+  const infoTooltip = page.locator('.cm-completionInfo');
+  const firstOption = page.locator('li[aria-selected="true"]');
+  let selectedOption = firstOption;
+
+  while (!(await infoTooltip.textContent()).includes(methodName)) {
+    await page.keyboard.press('ArrowDown');
+    const currentSelected = page.locator('li[aria-selected="true"]');
+    expect(currentSelected).not.toBe(selectedOption);
+    expect(currentSelected).not.toBe(firstOption);
+    selectedOption = currentSelected;
+  }
+
+  return infoTooltip;
+}
+
+test('shows signature help information on auto-completion for procedures', async ({
+  page,
+  mount,
+}) => {
+  await mount(
+    <CypherEditor
+      schema={testData.mockSchema}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+  const procName = 'apoc.periodic.iterate';
+  const procedure = testData.mockSchema.procedures[procName];
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('CALL apoc.periodic.');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+
+  const infoTooltip = await getInfoTooltip(page, procName);
+  await expect(infoTooltip).toContainText(procedure.signature);
+  await expect(infoTooltip).toContainText(procedure.description);
+});
+
+test('shows signature help information on auto-completion for functions', async ({
+  page,
+  mount,
+}) => {
+  await mount(
+    <CypherEditor
+      schema={testData.mockSchema}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+  const fnName = 'apoc.coll.combinations';
+  const fn = testData.mockSchema.functions[fnName];
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('RETURN apoc.coll.');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+
+  const infoTooltip = await getInfoTooltip(page, fnName);
+  await expect(infoTooltip).toContainText(fn.signature);
+  await expect(infoTooltip).toContainText(fn.description);
+});
+
+test('shows deprecated procedures as strikethrough on auto-completion', async ({
+  page,
+  mount,
+}) => {
+  const procName = 'apoc.trigger.resume';
+
+  await mount(
+    <CypherEditor
+      schema={{
+        procedures: { [procName]: testData.mockSchema.procedures[procName] },
+      }}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+  const textField = page.getByRole('textbox');
+  await textField.fill('CALL apoc.trigger.');
+
+  // We need to assert on the element having the right class
+  // and trusting the CSS is making this truly strikethrough
+  await expect(page.locator('.cm-deprecated-completion')).toBeVisible();
+});
+
+test('shows deprecated function as strikethrough on auto-completion', async ({
+  page,
+  mount,
+}) => {
+  const fnName = 'apoc.create.uuid';
+
+  await mount(
+    <CypherEditor
+      schema={{
+        functions: { [fnName]: testData.mockSchema.functions[fnName] },
+      }}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+  const textField = page.getByRole('textbox');
+  await textField.fill('RETURN apoc.create.');
+
+  // We need to assert on the element having the right class
+  // and trusting the CSS is making this truly strikethrough
+  await expect(page.locator('.cm-deprecated-completion')).toBeVisible();
+});
+
+test('does not signature help information on auto-completion if flag not enabled explicitly', async ({
+  page,
+  mount,
+}) => {
+  await mount(<CypherEditor schema={testData.mockSchema} />);
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('CALL apoc.periodic.');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+  await expect(page.locator('.cm-completionInfo')).not.toBeVisible();
+});
+
+test('does not signature help information on auto-completion if docs and signature are empty', async ({
+  page,
+  mount,
+}) => {
+  await mount(
+    <CypherEditor
+      schema={testData.mockSchema}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('C');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+  await expect(page.locator('.cm-completionInfo')).not.toBeVisible();
+});
+
+test('shows signature help information on auto-completion if description is not empty, signature is', async ({
+  page,
+  mount,
+}) => {
+  await mount(
+    <CypherEditor
+      schema={{
+        procedures: {
+          'db.ping': {
+            ...testData.emptyProcedure,
+            description: 'foo',
+            signature: '',
+            name: 'db.ping',
+          },
+        },
+      }}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('CALL db.');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+  await expect(page.locator('.cm-completionInfo')).toBeVisible();
+});
+
+test('shows signature help information on auto-completion if signature is not empty, description is', async ({
+  page,
+  mount,
+}) => {
+  await mount(
+    <CypherEditor
+      schema={{
+        procedures: {
+          'db.ping': {
+            ...testData.emptyProcedure,
+            description: '',
+            signature: 'foo',
+            name: 'db.ping',
+          },
+        },
+      }}
+      featureFlags={{
+        signatureInfoOnAutoCompletions: true,
+      }}
+    />,
+  );
+
+  const textField = page.getByRole('textbox');
+  await textField.fill('CALL db.');
+
+  await expect(page.locator('.cm-tooltip-autocomplete')).toBeVisible();
+  await expect(page.locator('.cm-completionInfo')).toBeVisible();
+});

package/src/e2e_tests/configuration.spec.tsx

@@ -1,8 +1,6 @@
 import { expect, test } from '@playwright/experimental-ct-react';
 import { CypherEditor } from '../CypherEditor';
 
-test.use({ viewport: { width: 500, height: 500 } });
-
 test('prompt shows up', async ({ mount, page }) => {
   const component = await mount(<CypherEditor prompt="neo4j>" />);
 
@@ -95,3 +93,19 @@ test('can set/unset onFocus/onBlur', async ({ mount, page }) => {
     expect(blurFireCount).toBe(1);
   }).toPass();
 });
+
+test('aria-label is not set by default', async ({ mount, page }) => {
+  await mount(<CypherEditor />);
+
+  const textField = page.getByRole('textbox');
+  expect(await textField.getAttribute('aria-label')).toBeNull();
+});
+
+test('can set aria-label', async ({ mount, page }) => {
+  const ariaLabel = 'Cypher Editor';
+
+  await mount(<CypherEditor ariaLabel={ariaLabel} />);
+
+  const textField = page.getByRole('textbox');
+  expect(await textField.getAttribute('aria-label')).toEqual(ariaLabel);
+});

package/src/e2e_tests/debounce.spec.tsx

@@ -0,0 +1,100 @@
+import { expect, test } from '@playwright/experimental-ct-react';
+import { CypherEditor } from '../CypherEditor';
+import { CypherEditorPage } from './e2eUtils';
+
+const DEBOUNCE_TIMER = 200;
+
+test('external updates should override debounced updates', async ({
+  mount,
+  page,
+}) => {
+  const editorPage = new CypherEditorPage(page);
+  let value = '';
+
+  const onChange = (val: string) => {
+    value = val;
+    void component.update(<CypherEditor value={val} onChange={onChange} />);
+  };
+
+  const component = await mount(
+    <CypherEditor value={value} onChange={onChange} />,
+  );
+
+  await editorPage.getEditor().pressSequentially('RETURN 1');
+  onChange('foo');
+  await page.waitForTimeout(DEBOUNCE_TIMER);
+  await expect(component).toContainText('foo');
+});
+
+test('onExecute updates should override debounce updates', async ({
+  mount,
+  page,
+}) => {
+  const editorPage = new CypherEditorPage(page);
+  let value = '';
+
+  const onExecute = () => {
+    value = '';
+    void component.update(
+      <CypherEditor value={value} onChange={onChange} onExecute={onExecute} />,
+    );
+  };
+
+  const onChange = (val: string) => {
+    value = val;
+    void component.update(
+      <CypherEditor value={val} onChange={onChange} onExecute={onExecute} />,
+    );
+  };
+
+  const component = await mount(
+    <CypherEditor value={value} onChange={onChange} onExecute={onExecute} />,
+  );
+
+  await editorPage.getEditor().pressSequentially('RETURN 1');
+  await editorPage.getEditor().press('Control+Enter');
+  await page.waitForTimeout(DEBOUNCE_TIMER);
+  await expect(component).not.toContainText('RETURN 1');
+
+  await editorPage.getEditor().pressSequentially('RETURN 1');
+  await editorPage.getEditor().pressSequentially('');
+  await editorPage.getEditor().pressSequentially('RETURN 1');
+  await editorPage.getEditor().press('Control+Enter');
+  await page.waitForTimeout(DEBOUNCE_TIMER);
+  await expect(component).not.toContainText('RETURN 1');
+});
+
+test('onExecute should fire after debounced updates', async ({
+  mount,
+  page,
+}) => {
+  const editorPage = new CypherEditorPage(page);
+  let value = '';
+  let executedCommand = '';
+
+  const onExecute = (cmd: string) => {
+    executedCommand = cmd;
+    void component.update(
+      <CypherEditor value={value} onChange={onChange} onExecute={onExecute} />,
+    );
+  };
+
+  const onChange = (val: string) => {
+    value = val;
+    void component.update(
+      <CypherEditor value={val} onChange={onChange} onExecute={onExecute} />,
+    );
+  };
+
+  const component = await mount(
+    <CypherEditor value={value} onChange={onChange} onExecute={onExecute} />,
+  );
+
+  await editorPage.getEditor().fill('RETURN 1');
+  await editorPage.getEditor().press('Control+Enter');
+  await editorPage.getEditor().fill('RETURN 2');
+  await editorPage.getEditor().press('Control+Enter');
+  await page.waitForTimeout(DEBOUNCE_TIMER);
+  await expect(component).toContainText('RETURN 2');
+  expect(executedCommand).toBe('RETURN 2');
+});

package/src/e2e_tests/extraKeybindings.spec.tsx

@@ -2,8 +2,6 @@ import { expect, test } from '@playwright/experimental-ct-react';
 import { CypherEditor } from '../CypherEditor';
 import { CypherEditorPage } from './e2eUtils';
 
-test.use({ viewport: { width: 500, height: 500 } });
-
 test('can add extra keybinding statically', async ({ mount, page }) => {
   const editorPage = new CypherEditorPage(page);
   let hasRun = false;