@neo4j-cypher/react-codemirror 2.0.0-next.35 → 2.0.0-next.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-cypher/react-codemirror",
-  "version": "2.0.0-next.35",
+  "version": "2.0.0-next.37",
   "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/lint-worker": "1.10.1-next.9",
-    "@neo4j-cypher/language-support": "2.0.0-next.32"
+    "@neo4j-cypher/language-support": "2.0.0-next.34",
+    "@neo4j-cypher/lint-worker": "1.10.1-next.11"
   },
   "devDependencies": {
     "@neo4j-ndl/base": "^3.2.10",

package/src/CypherEditor.tsx

@@ -13,6 +13,12 @@ import {
   placeholder,
   ViewUpdate,
 } from '@codemirror/view';
+import {
+  createInlinePanelController,
+  type InlinePanelCallbacks,
+  type InlinePanelController,
+} from './inlinePanel';
+import { createDiffExtension, type DiffProps } from './diffView';
 import {
   formatQuery,
   CypherLanguageService,
@@ -180,8 +186,31 @@ export interface CypherEditorProps {
    * @default false
    */
   moveFocusOnTab?: boolean;
+  /**
+   * Render a panel as a block widget inside the editor.
+   * 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;
 }
 
+export type InlinePanelProps = {
+  /**
+   * Position the panel anchors to.
+   */
+  pos: number;
+  /**
+   * Whether to render above or below the line
+   *
+   * @default 'above'
+   */
+  placement?: 'above' | 'below';
+} & InlinePanelCallbacks;
+
 const format = (view: EditorView): void => {
   try {
     const doc = view.state.doc.toString();
@@ -268,6 +297,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) => {
@@ -290,10 +320,12 @@ class CodemirrorSymbolFetcher {
   }
   private languageService: CypherLanguageService;
   private processing = false;
-  private nextJob: {
-    query: string;
-    schema: DbSchema;
-  };
+  private nextJob:
+    | {
+        query: string;
+        schema: DbSchema;
+      }
+    | undefined;
   private symbolTablePool = workerpool.pool(WorkerURL, {
     minWorkers: 1,
     workerOpts: { type: 'module' },
@@ -316,11 +348,11 @@ class CodemirrorSymbolFetcher {
     this.processing = true;
     while (this.nextJob) {
       try {
-        const proxyWorker =
-          (await this.symbolTablePool.proxy()) as unknown as LintWorker;
         const query = this.nextJob.query;
         const dbSchema = this.nextJob.schema;
         this.nextJob = undefined;
+        const proxyWorker =
+          (await this.symbolTablePool.proxy()) as unknown as LintWorker;
 
         const result = await proxyWorker.lintCypherQuery(query, dbSchema);
 
@@ -360,6 +392,7 @@ export class CypherEditor extends Component<
    */
   editorView: React.MutableRefObject<EditorView> = createRef();
   private schemaRef: React.MutableRefObject<CypherConfig> = createRef();
+  private inlinePanelController: InlinePanelController | null = null;
 
   /**
    * Format Cypher query
@@ -471,6 +504,8 @@ export class CypherEditor extends Component<
       overrideThemeBackgroundColor,
     );
 
+    this.inlinePanelController = createInlinePanelController();
+
     const changeListener = this.debouncedOnChange
       ? [
           EditorView.updateListener.of((upt: ViewUpdate) => {
@@ -536,6 +571,10 @@ export class CypherEditor extends Component<
                 'Press Escape to leave the editor and continue tabbing through the page',
             })
           : [],
+        this.inlinePanelController.extension,
+        diffCompartment.of(
+          this.props.diff ? createDiffExtension(this.props.diff) : [],
+        ),
       ],
       doc: this.props.value,
     });
@@ -553,6 +592,53 @@ export class CypherEditor extends Component<
     } else if (this.props.offset) {
       this.updateCursorPosition(this.props.offset);
     }
+
+    if (this.props.inlinePanel) {
+      this.openInlinePanel(this.props.inlinePanel);
+    }
+  }
+
+  private openInlinePanel(
+    props: NonNullable<CypherEditorProps['inlinePanel']>,
+  ): void {
+    const view = this.editorView.current;
+    const controller = this.inlinePanelController;
+    if (!view || !controller) {
+      return;
+    }
+
+    const pos = Math.max(0, Math.min(props.pos, view.state.doc.length));
+    const line = view.state.doc.lineAt(pos);
+    controller.updateCallbacks({
+      onMount: props.onMount,
+      onUnmount: props.onUnmount,
+    });
+    view.dispatch({
+      effects: controller.show({
+        pos: props.placement === 'below' ? line.to : line.from,
+        placement: props.placement,
+        onMount: props.onMount,
+        onUnmount: props.onUnmount,
+      }),
+    });
+  }
+
+  private updateInlinePanel(
+    props: NonNullable<CypherEditorProps['inlinePanel']>,
+  ): void {
+    this.inlinePanelController?.updateCallbacks({
+      onMount: props.onMount,
+      onUnmount: props.onUnmount,
+    });
+  }
+
+  private closeInlinePanel(): void {
+    const view = this.editorView.current;
+    const controller = this.inlinePanelController;
+    if (!view || !controller) {
+      return;
+    }
+    view.dispatch({ effects: controller.hide() });
   }
 
   componentDidUpdate(prevProps: CypherEditorProps): void {
@@ -642,6 +728,30 @@ export class CypherEditor extends Component<
       });
     }
 
+    const prevPanel = prevProps.inlinePanel;
+    const nextPanel = this.props.inlinePanel;
+    if (prevPanel !== nextPanel) {
+      if (!nextPanel) {
+        this.closeInlinePanel();
+      } else if (
+        !prevPanel ||
+        prevPanel.pos !== nextPanel.pos ||
+        prevPanel.placement !== nextPanel.placement
+      ) {
+        this.openInlinePanel(nextPanel);
+      } else {
+        this.updateInlinePanel(nextPanel);
+      }
+    }
+
+    if (prevProps.diff?.original !== this.props.diff?.original) {
+      this.editorView.current.dispatch({
+        effects: diffCompartment.reconfigure(
+          this.props.diff ? createDiffExtension(this.props.diff) : [],
+        ),
+      });
+    }
+
     if (prevProps.domEventHandlers !== this.props.domEventHandlers) {
       this.editorView.current.dispatch({
         effects: domEventHandlerCompartment.reconfigure(

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/index.ts

@@ -1,4 +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

@@ -0,0 +1,145 @@
+import { StateEffect, StateField, type Extension } from '@codemirror/state';
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  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;
+};
+
+export type InlinePanelShowOptions = {
+  /** Document position the panel anchors to. */
+  pos: number;
+  /**
+   * Where to render the panel relative to the line at `pos`. `'above'`
+   * places it before the line, `'below'` after it.
+   *
+   * @default 'above'
+   */
+  placement?: 'above' | 'below';
+} & InlinePanelCallbacks;
+
+type ShowPayload = InlinePanelShowOptions | null;
+
+export type InlinePanelController = {
+  /** CodeMirror extension to register on the editor. */
+  extension: Extension;
+  /** Build an effect that mounts the panel with the given options. */
+  show: (options: InlinePanelShowOptions) => StateEffect<ShowPayload>;
+  /** Build an effect that unmounts the panel. */
+  hide: () => StateEffect<ShowPayload>;
+  updateCallbacks: (callbacks: InlinePanelCallbacks) => void;
+};
+
+export function createInlinePanelController(): InlinePanelController {
+  const showEffect = StateEffect.define<ShowPayload>();
+
+  let callbacksRef: InlinePanelCallbacks | null = null;
+
+  class InlinePanelWidget extends WidgetType {
+    private resizeObserver: ResizeObserver | null = null;
+
+    constructor(readonly options: InlinePanelShowOptions) {
+      super();
+    }
+
+    toDOM(view: EditorView): HTMLElement {
+      const container = document.createElement('div');
+      container.className = 'cm-inline-panel';
+      this.resizeObserver = new ResizeObserver(() => view.requestMeasure());
+      this.resizeObserver.observe(container);
+      callbacksRef?.onMount(container);
+      return container;
+    }
+
+    destroy(): void {
+      this.resizeObserver?.disconnect();
+      this.resizeObserver = null;
+      callbacksRef?.onUnmount();
+    }
+
+    eq(other: InlinePanelWidget): boolean {
+      return (
+        other.options.pos === this.options.pos &&
+        other.options.placement === this.options.placement
+      );
+    }
+
+    ignoreEvent(): boolean {
+      return true;
+    }
+  }
+
+  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) {
+      for (const effect of transaction.effects) {
+        if (effect.is(showEffect)) {
+          return effect.value === null
+            ? Decoration.none
+            : buildDecoration(effect.value);
+        }
+      }
+
+      // 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);
+      }
+      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),
+  });
+
+  return {
+    extension: field,
+    show: (options) => showEffect.of(options),
+    hide: () => showEffect.of(null),
+    updateCallbacks: (callbacks) => {
+      callbacksRef = callbacks;
+    },
+  };
+}

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 });