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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-cypher/react-codemirror",
-  "version": "2.0.0-next.37",
+  "version": "2.0.0-next.38",
   "keywords": [
     "codemirror",
     "codemirror 6",
@@ -48,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.34",
-    "@neo4j-cypher/lint-worker": "1.10.1-next.11"
+    "@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",
@@ -68,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

@@ -19,13 +19,19 @@ import {
   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,
@@ -196,6 +202,12 @@ export interface CypherEditorProps {
    * 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 = {
@@ -308,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)
@@ -393,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
@@ -505,6 +530,7 @@ export class CypherEditor extends Component<
     );
 
     this.inlinePanelController = createInlinePanelController();
+    this.editorActionsController = createEditorActionsController();
 
     const changeListener = this.debouncedOnChange
       ? [
@@ -575,6 +601,7 @@ export class CypherEditor extends Component<
         diffCompartment.of(
           this.props.diff ? createDiffExtension(this.props.diff) : [],
         ),
+        this.editorActionsController.extension,
       ],
       doc: this.props.value,
     });
@@ -596,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(
@@ -752,6 +795,12 @@ export class CypherEditor extends Component<
       });
     }
 
+    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(
@@ -796,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/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/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. */