@neo4j-cypher/react-codemirror 2.0.0-next.36 → 2.0.0-next.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-cypher/react-codemirror",
-  "version": "2.0.0-next.36",
+  "version": "2.0.0-next.38",
   "keywords": [
     "codemirror",
     "codemirror 6",
@@ -34,6 +34,7 @@
     "@codemirror/commands": "^6.8.1",
     "@codemirror/language": "^6.11.2",
     "@codemirror/lint": "^6.8.5",
+    "@codemirror/merge": "^6.12.1",
     "@codemirror/search": "^6.5.11",
     "@codemirror/state": "^6.5.2",
     "@codemirror/view": "^6.38.1",
@@ -47,8 +48,8 @@
     "style-mod": "^4.1.2",
     "vscode-languageserver-types": "^3.17.3",
     "workerpool": "^9.3.3",
-    "@neo4j-cypher/language-support": "2.0.0-next.33",
-    "@neo4j-cypher/lint-worker": "1.10.1-next.10"
+    "@neo4j-cypher/language-support": "2.0.0-next.35",
+    "@neo4j-cypher/lint-worker": "1.10.1-next.12"
   },
   "devDependencies": {
     "@neo4j-ndl/base": "^3.2.10",
@@ -67,12 +68,12 @@
     "vite": "^4.5.10"
   },
   "peerDependencies": {
-    "react": "^16.8.0 || ^17.0.0 || ^18.0.0"
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
   },
   "engines": {
     "node": ">=24.11.1"
   },
-  "engineStrict": true,
   "scripts": {
     "dev": "tsc --watch",
     "build": "pnpm copy-lint-worker && tsc --declaration --outDir dist/",

package/src/CypherEditor.tsx

@@ -18,13 +18,20 @@ import {
   type InlinePanelCallbacks,
   type InlinePanelController,
 } from './inlinePanel';
+import { createDiffExtension, type DiffProps } from './diffView';
+import {
+  createEditorActionsController,
+  type EditorActionsCallbacks,
+  type EditorActionsController,
+} from './editorActions';
 import {
   formatQuery,
   CypherLanguageService,
   type DbSchema,
 } from '@neo4j-cypher/language-support';
 import debounce from 'lodash.debounce';
-import { Component, createRef } from 'react';
+import { Component, createRef, type ReactNode } from 'react';
+import { createPortal } from 'react-dom';
 import { DEBOUNCE_TIME } from './constants';
 import {
   replaceHistory,
@@ -190,6 +197,17 @@ export interface CypherEditorProps {
    * The widget DOM is only rebuilt when `pos` or `placement` change
    */
   inlinePanel?: InlinePanelProps | null;
+  /**
+   * Render a unified diff of the current document against `diff.original`.
+   * Deleted lines are shown as uneditable widgets.
+   */
+  diff?: DiffProps | null;
+  /**
+   * React content rendered as a cluster of action buttons (e.g. a context menu
+   * + Run) pinned to the top-right corner of the editor. Omit (or `null`) to
+   * hide it.
+   */
+  editorActions?: ReactNode;
 }
 
 export type InlinePanelProps = {
@@ -291,6 +309,7 @@ const lineNumbersCompartment = new Compartment();
 const readOnlyCompartment = new Compartment();
 const placeholderCompartment = new Compartment();
 const domEventHandlerCompartment = new Compartment();
+const diffCompartment = new Compartment();
 
 const formatLineNumber =
   (prompt?: string) => (a: number, state: EditorState) => {
@@ -301,7 +320,9 @@ const formatLineNumber =
     return a.toString();
   };
 
-type CypherEditorState = { cypherSupportEnabled: boolean };
+type CypherEditorState = {
+  editorActionsContainer: HTMLElement | null;
+};
 
 const ExternalEdit = Annotation.define<boolean>();
 const WorkerURL = new URL('./lang-cypher/lintWorker.mjs', import.meta.url)
@@ -386,6 +407,17 @@ export class CypherEditor extends Component<
   editorView: React.MutableRefObject<EditorView> = createRef();
   private schemaRef: React.MutableRefObject<CypherConfig> = createRef();
   private inlinePanelController: InlinePanelController | null = null;
+  private editorActionsController: EditorActionsController | null = null;
+
+  state: CypherEditorState = {
+    editorActionsContainer: null,
+  };
+
+  private editorActionsCallbacks: EditorActionsCallbacks = {
+    onMount: (container) =>
+      this.setState({ editorActionsContainer: container }),
+    onUnmount: () => this.setState({ editorActionsContainer: null }),
+  };
 
   /**
    * Format Cypher query
@@ -498,6 +530,7 @@ export class CypherEditor extends Component<
     );
 
     this.inlinePanelController = createInlinePanelController();
+    this.editorActionsController = createEditorActionsController();
 
     const changeListener = this.debouncedOnChange
       ? [
@@ -565,6 +598,10 @@ export class CypherEditor extends Component<
             })
           : [],
         this.inlinePanelController.extension,
+        diffCompartment.of(
+          this.props.diff ? createDiffExtension(this.props.diff) : [],
+        ),
+        this.editorActionsController.extension,
       ],
       doc: this.props.value,
     });
@@ -586,6 +623,22 @@ export class CypherEditor extends Component<
     if (this.props.inlinePanel) {
       this.openInlinePanel(this.props.inlinePanel);
     }
+
+    if (this.props.editorActions != null) {
+      this.setEditorActions(true);
+    }
+  }
+
+  private setEditorActions(active: boolean): void {
+    const view = this.editorView.current;
+    const controller = this.editorActionsController;
+    if (!view || !controller) {
+      return;
+    }
+
+    view.dispatch({
+      effects: controller.set(active ? this.editorActionsCallbacks : null),
+    });
   }
 
   private openInlinePanel(
@@ -734,6 +787,20 @@ export class CypherEditor extends Component<
       }
     }
 
+    if (prevProps.diff?.original !== this.props.diff?.original) {
+      this.editorView.current.dispatch({
+        effects: diffCompartment.reconfigure(
+          this.props.diff ? createDiffExtension(this.props.diff) : [],
+        ),
+      });
+    }
+
+    const hadActions = prevProps.editorActions != null;
+    const hasActions = this.props.editorActions != null;
+    if (hadActions !== hasActions) {
+      this.setEditorActions(hasActions);
+    }
+
     if (prevProps.domEventHandlers !== this.props.domEventHandlers) {
       this.editorView.current.dispatch({
         effects: domEventHandlerCompartment.reconfigure(
@@ -778,11 +845,16 @@ export class CypherEditor extends Component<
     const themeClass =
       typeof theme === 'string' ? `cm-theme-${theme}` : 'cm-theme';
 
+    const { editorActionsContainer } = this.state;
+
     return (
       <div
         ref={this.editorContainer}
         className={`${themeClass}${className ? ` ${className}` : ''}`}
-      />
+      >
+        {editorActionsContainer &&
+          createPortal(this.props.editorActions, editorActionsContainer)}
+      </div>
     );
   }
 }

package/src/diffView.ts

@@ -0,0 +1,24 @@
+import { unifiedMergeView } from '@codemirror/merge';
+import type { Extension } from '@codemirror/state';
+
+/**
+ * Props for rendering an inline diff in the editor.
+ *
+ * The diff is computed between {@link DiffProps.original} and the *current*
+ * editor document, so streaming/external updates to the document re-diff
+ * automatically against the same original.
+ */
+export type DiffProps = {
+  /** The baseline document the current editor content is compared against. */
+  original: string;
+};
+
+export function createDiffExtension({ original }: DiffProps): Extension {
+  return unifiedMergeView({
+    original,
+    highlightChanges: true,
+    syntaxHighlightDeletions: true,
+    mergeControls: false,
+    gutter: true,
+  });
+}

package/src/e2e_tests/syntaxValidation.spec.tsx

@@ -131,11 +131,6 @@ test('Semantic errors are correctly accumulated', async ({ page, mount }) => {
 
   await mount(<CypherEditor value={query} />);
 
-  await editorPage.checkErrorMessage(
-    'MATCH (n)',
-    'Query cannot conclude with MATCH (must be a RETURN clause, a FINISH clause, an update clause, a unit subquery call, or a procedure call with no YIELD).',
-  );
-
   await editorPage.checkErrorMessage(
     '-1',
     "Invalid input. '-1' is not a valid value. Must be a positive integer.",
@@ -151,11 +146,6 @@ test('Multiline errors are correctly placed', async ({ page, mount }) => {
 
   await mount(<CypherEditor value={query} />);
 
-  await editorPage.checkErrorMessage(
-    'MATCH (n)',
-    'Query cannot conclude with MATCH (must be a RETURN clause, a FINISH clause, an update clause, a unit subquery call, or a procedure call with no YIELD).',
-  );
-
   await editorPage.checkErrorMessage(
     '-1',
     "Invalid input. '-1' is not a valid value. Must be a positive integer.",
@@ -171,11 +161,6 @@ test('Validation errors are correctly overlapped', async ({ page, mount }) => {
 
   await mount(<CypherEditor value={query} />);
 
-  await editorPage.checkErrorMessage(
-    '-1',
-    'Query cannot conclude with CALL (must be a RETURN clause, a FINISH clause, an update clause, a unit subquery call, or a procedure call with no YIELD).',
-  );
-
   await editorPage.checkErrorMessage(
     '-1',
     "Invalid input. '-1' is not a valid value. Must be a positive integer.",

package/src/editorActions.ts

@@ -0,0 +1,250 @@
+import { StateEffect, StateField, type Extension } from '@codemirror/state';
+import {
+  Decoration,
+  EditorView,
+  ViewPlugin,
+  type ViewUpdate,
+  WidgetType,
+} from '@codemirror/view';
+import type { HostPortalCallbacks } from './hostCallbacks';
+
+/** Lifecycle callbacks for the editor action buttons. See {@link HostPortalCallbacks}. */
+export type EditorActionsCallbacks = HostPortalCallbacks;
+
+export type EditorActionsController = {
+  /** CodeMirror extension to register on the editor. */
+  extension: Extension;
+  /**
+   * Drive the action buttons from the host's state: pass callbacks to mount
+   * them, or `null` to unmount. Returns the effect for the host to dispatch.
+   *
+   * Visibility is purely a function of whether callbacks exist — there's no
+   * separate show/hide toggle.
+   */
+  set: (callbacks: EditorActionsCallbacks | null) => StateEffect<boolean>;
+};
+
+/**
+ * Renders a host-provided cluster of action buttons at the top-right corner
+ * of the editor.
+ *
+ * The cluster is split into two cooperating pieces so it can both reserve
+ * space *and* stay pinned — which a single element can't do (reserving needs
+ * to be in flow, pinning needs to be out of it):
+ *
+ *  - A **spacer**: an empty, floated inline widget at the very start of the
+ *    document. Being in flow, it makes the first line's text wrap around it —
+ *    and because it's a float, the browser handles arbitrary cluster heights.
+ *    It carries no content; it only reserves the footprint.
+ *  - An **overlay**: the real, host-rendered buttons in a container pinned
+ *    `absolute` on the editor element (which does not scroll). It never moves
+ *    when the document grows, when an inline panel opens above the first line,
+ *    or when the content scrolls — content simply scrolls behind it.
+ */
+
+const SPACER_BOTTOM_GAP = 2;
+const SPACER_LEFT_GAP = 4;
+
+export function createEditorActionsController(): EditorActionsController {
+  const setActiveEffect = StateEffect.define<boolean>();
+
+  let callbacksRef: EditorActionsCallbacks | null = null;
+
+  const activeField = StateField.define<boolean>({
+    create: () => false,
+    update(active, transaction) {
+      for (const effect of transaction.effects) {
+        if (effect.is(setActiveEffect)) {
+          active = effect.value;
+        }
+      }
+      return active;
+    },
+  });
+
+  class SpacerWidget extends WidgetType {
+    toDOM(): HTMLElement {
+      const spacer = document.createElement('div');
+      spacer.className = 'cm-editor-actions-spacer';
+      spacer.setAttribute('aria-hidden', 'true');
+      return spacer;
+    }
+
+    eq(): boolean {
+      return true;
+    }
+
+    ignoreEvent(): boolean {
+      return true;
+    }
+  }
+
+  const spacer = EditorView.decorations.compute(
+    ['doc', activeField],
+    (state) => {
+      if (!state.field(activeField) || state.doc.length === 0) {
+        return Decoration.none;
+      }
+      return Decoration.set([
+        Decoration.widget({
+          widget: new SpacerWidget(),
+          side: -1,
+        }).range(0),
+      ]);
+    },
+  );
+
+  const overlay = ViewPlugin.fromClass(
+    class {
+      private dom: HTMLElement | null = null;
+      private resizeObserver: ResizeObserver | null = null;
+      private mounted: EditorActionsCallbacks | null = null;
+
+      constructor(view: EditorView) {
+        if (view.state.field(activeField)) {
+          this.mount(view);
+        }
+      }
+
+      update(update: ViewUpdate): void {
+        const isActive = update.state.field(activeField);
+        if (isActive && !this.dom) {
+          this.mount(update.view);
+        } else if (!isActive && this.dom) {
+          this.unmount();
+        } else if (
+          this.dom &&
+          (update.geometryChanged ||
+            update.docChanged ||
+            update.viewportChanged)
+        ) {
+          this.align(update.view);
+        }
+      }
+
+      destroy(): void {
+        this.unmount();
+      }
+
+      private mount(view: EditorView): void {
+        const container = document.createElement('div');
+        container.className = 'cm-editor-actions';
+        view.dom.appendChild(container);
+        this.resizeObserver = new ResizeObserver(() => {
+          view.dom.style.setProperty(
+            '--cm-editor-actions-width',
+            `${container.offsetWidth}px`,
+          );
+          view.dom.style.setProperty(
+            '--cm-editor-actions-height',
+            `${container.offsetHeight}px`,
+          );
+          view.dom.style.setProperty(
+            '--cm-editor-actions-content-min-height',
+            `${container.offsetHeight + SPACER_BOTTOM_GAP}px`,
+          );
+          this.align(view);
+        });
+        this.resizeObserver.observe(container);
+        this.dom = container;
+        this.mounted = callbacksRef;
+        callbacksRef?.onMount(container);
+        this.align(view);
+      }
+
+      private align(view: EditorView): void {
+        view.requestMeasure<{ top: number; right: number } | null>({
+          read: () => {
+            if (!this.dom) {
+              return null;
+            }
+            const editorRect = view.dom.getBoundingClientRect();
+            const spacer = view.dom.querySelector('.cm-editor-actions-spacer');
+            let topClient: number;
+            let rightClient: number;
+            if (spacer) {
+              const rect = spacer.getBoundingClientRect();
+              topClient = rect.top;
+              rightClient = rect.right;
+            } else {
+              const rect = view.contentDOM.getBoundingClientRect();
+              const style = window.getComputedStyle(view.contentDOM);
+              topClient = rect.top + (parseFloat(style.paddingTop) || 0);
+              rightClient = rect.right - (parseFloat(style.paddingRight) || 0);
+            }
+            return {
+              top: topClient - editorRect.top + view.scrollDOM.scrollTop,
+              right: editorRect.right - rightClient - view.scrollDOM.scrollLeft,
+            };
+          },
+          write: (pos) => {
+            if (!pos || !this.dom) {
+              return;
+            }
+            view.dom.style.setProperty(
+              '--cm-editor-actions-top',
+              `${pos.top}px`,
+            );
+            view.dom.style.setProperty(
+              '--cm-editor-actions-right',
+              `${pos.right}px`,
+            );
+          },
+        });
+      }
+
+      private unmount(): void {
+        if (!this.dom) {
+          return;
+        }
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = null;
+        this.mounted?.onUnmount();
+        this.mounted = null;
+        const root = this.dom?.parentElement;
+        if (root) {
+          root.style.removeProperty('--cm-editor-actions-width');
+          root.style.removeProperty('--cm-editor-actions-height');
+          root.style.removeProperty('--cm-editor-actions-content-min-height');
+          root.style.removeProperty('--cm-editor-actions-top');
+          root.style.removeProperty('--cm-editor-actions-right');
+        }
+        this.dom?.remove();
+        this.dom = null;
+      }
+    },
+  );
+
+  const theme = EditorView.theme({
+    '.cm-content': {
+      minHeight: 'var(--cm-editor-actions-content-min-height, 0px)',
+    },
+    '.cm-editor-actions-spacer': {
+      float: 'right',
+      boxSizing: 'content-box',
+      width: 'var(--cm-editor-actions-width, 0px)',
+      height: 'var(--cm-editor-actions-height, 0px)',
+      paddingLeft: `${SPACER_LEFT_GAP}px`,
+      paddingBottom: `${SPACER_BOTTOM_GAP}px`,
+      userSelect: 'none',
+      WebkitUserSelect: 'none',
+      pointerEvents: 'none',
+    },
+    '.cm-editor-actions': {
+      position: 'absolute',
+      top: 'var(--cm-editor-actions-top, 0px)',
+      right: 'var(--cm-editor-actions-right, 0px)',
+      zIndex: '2',
+      userSelect: 'none',
+      WebkitUserSelect: 'none',
+    },
+  });
+
+  return {
+    extension: [activeField, spacer, overlay, theme],
+    set: (callbacks) => {
+      callbacksRef = callbacks;
+      return setActiveEffect.of(callbacks !== null);
+    },
+  };
+}

package/src/hostCallbacks.ts

@@ -0,0 +1,9 @@
+/**
+ * Lifecycle callbacks for host-rendered overlay content (inline panels, editor
+ * action buttons, …). The host renders into the provided DOM container (e.g.
+ * via React `createPortal`) and is expected to clean up on unmount.
+ */
+export type HostPortalCallbacks = {
+  onMount: (container: HTMLElement) => void;
+  onUnmount: () => void;
+};

package/src/index.ts

@@ -1,5 +1,6 @@
 export * as LanguageSupport from '@neo4j-cypher/language-support';
 export { CypherEditor } from './CypherEditor';
 export type { InlinePanelProps } from './CypherEditor';
+export type { DiffProps } from './diffView';
 export { cypher } from './lang-cypher/langCypher';
 export { darkThemeConstants, lightThemeConstants } from './themes';

package/src/inlinePanel.ts

@@ -6,15 +6,10 @@ import {
   WidgetType,
 } from '@codemirror/view';
 
-/**
- * Lifecycle callbacks for an inline panel. The host renders into the
- * provided DOM container (e.g. via React `createPortal`) and is expected
- * to clean up on unmount.
- */
-export type InlinePanelCallbacks = {
-  onMount: (container: HTMLElement) => void;
-  onUnmount: () => void;
-};
+import type { HostPortalCallbacks } from './hostCallbacks';
+
+/** Lifecycle callbacks for an inline panel. See {@link HostPortalCallbacks}. */
+export type InlinePanelCallbacks = HostPortalCallbacks;
 
 export type InlinePanelShowOptions = {
   /** Document position the panel anchors to. */
@@ -79,32 +74,57 @@ export function createInlinePanelController(): InlinePanelController {
     }
   }
 
+  const buildDecoration = (options: InlinePanelShowOptions): DecorationSet =>
+    Decoration.set([
+      Decoration.widget({
+        widget: new InlinePanelWidget(options),
+        block: true,
+        side: options.placement === 'below' ? 1 : -1,
+      }).range(options.pos),
+    ]);
+
+  const readOptions = (
+    decorations: DecorationSet,
+  ): InlinePanelShowOptions | null => {
+    const widget = decorations.iter().value?.spec?.widget;
+    return widget instanceof InlinePanelWidget ? widget.options : null;
+  };
+
   const field = StateField.define<DecorationSet>({
     create() {
       return Decoration.none;
     },
     update(decorations, transaction) {
-      let next: DecorationSet | null = null;
       for (const effect of transaction.effects) {
         if (effect.is(showEffect)) {
-          if (effect.value === null) {
-            next = Decoration.none;
-          } else {
-            const side = effect.value.placement === 'below' ? 1 : -1;
-            next = Decoration.set([
-              Decoration.widget({
-                widget: new InlinePanelWidget(effect.value),
-                block: true,
-                side,
-              }).range(effect.value.pos),
-            ]);
-          }
+          return effect.value === null
+            ? Decoration.none
+            : buildDecoration(effect.value);
         }
       }
-      if (next !== null) {
-        return next;
+
+      // Nothing to do when the panel is closed, or when the document is unchanged
+      if (decorations.size === 0 || !transaction.docChanged) {
+        return decorations.map(transaction.changes);
+      }
+
+      // Re-anchor manually because CodeMirror's default mapping silently drops
+      // block-widget decorations when their anchor line is deleted
+      const options = readOptions(decorations);
+      if (options === null) {
+        return decorations.map(transaction.changes);
       }
-      return decorations.map(transaction.changes);
+      const side = options.placement === 'below' ? 1 : -1;
+      const lineNumber = Math.min(
+        transaction.startState.doc.lineAt(options.pos).number,
+        transaction.newDoc.lines,
+      );
+      const line = transaction.newDoc.line(lineNumber);
+
+      return buildDecoration({
+        ...options,
+        pos: side === 1 ? line.to : line.from,
+      });
     },
     provide: (f) => EditorView.decorations.from(f),
   });

package/src/lang-cypher/createCypherTheme.ts

@@ -18,6 +18,17 @@ import {
   upArrowSvg,
 } from './themeIcons';
 
+export interface DiffColors {
+  /** Background fill for the whole inserted/changed line. */
+  insertedLine: string;
+  /** Highlight for the exact inserted text within a changed line. */
+  insertedText: string;
+  /** Background fill for the whole deleted line widget. */
+  deletedLine: string;
+  /** Highlight for the exact deleted text within a deleted chunk. */
+  deletedText: string;
+}
+
 export interface ThemeOptions {
   dark: boolean;
   editorSettings: {
@@ -40,6 +51,7 @@ export interface ThemeOptions {
   };
   highlightStyles: Partial<Record<HighlightedCypherTokenTypes, string>>;
   inheritBgColor?: boolean;
+  diffColors?: DiffColors;
 }
 
 export const createCypherTheme = ({
@@ -47,6 +59,7 @@ export const createCypherTheme = ({
   editorSettings: settings,
   highlightStyles,
   inheritBgColor,
+  diffColors,
 }: ThemeOptions): Extension => {
   const themeOptions: Record<string, StyleSpec> = {
     '&': {
@@ -218,6 +231,26 @@ export const createCypherTheme = ({
         },
       },
     },
+    ...(diffColors && {
+      '&.cm-merge-b .cm-changedLine': {
+        backgroundColor: diffColors.insertedLine,
+      },
+      '&.cm-merge-b .cm-changedText': {
+        background: diffColors.insertedText,
+      },
+      '&.cm-merge-b .cm-deletedChunk': {
+        backgroundColor: diffColors.deletedLine,
+      },
+      '&.cm-merge-b .cm-deletedChunk .cm-deletedText': {
+        background: diffColors.deletedText,
+      },
+      // Hide the empty deletion widget that unifiedMergeView renders
+      // when the original document is empty (its only line is an empty <del>).
+      '&.cm-merge-b .cm-deletedChunk:has(> .cm-deletedLine:only-child > del > br:only-child)':
+        {
+          display: 'none',
+        },
+    }),
   };
 
   const themeExtension = EditorView.theme(themeOptions, { dark });