@neo4j-cypher/react-codemirror 2.0.0-next.41 → 2.0.0-next.42

package/dist/vitest.config.d.mts

@@ -0,0 +1,2 @@
+declare const _default: import("vitest/config").UserWorkspaceConfig;
+export default _default;

package/dist/vitest.config.mjs

@@ -0,0 +1,16 @@
+import { defineProject } from 'vitest/config';
+export default defineProject({
+    test: {
+        globals: true,
+        projects: [
+            {
+                test: {
+                    name: 'unit',
+                    include: ['src/**/*.test.{ts,tsx}'],
+                    exclude: ['src/tests/e2e/**'],
+                },
+            },
+        ],
+    },
+});
+//# sourceMappingURL=vitest.config.mjs.map

package/dist/vitest.config.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.mjs","sourceRoot":"","sources":["../vitest.config.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,eAAe,aAAa,CAAC;IAC3B,IAAI,EAAE;QACJ,OAAO,EAAE,IAAI;QAEb,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE;oBACJ,IAAI,EAAE,MAAM;oBACZ,OAAO,EAAE,CAAC,wBAAwB,CAAC;oBACnC,OAAO,EAAE,CAAC,kBAAkB,CAAC;iBAC9B;aACF;SACF;KACF;CACF,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neo4j-cypher/react-codemirror",
-  "version": "2.0.0-next.41",
+  "version": "2.0.0-next.42",
   "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.38",
-    "@neo4j-cypher/lint-worker": "1.10.1-next.15"
+    "@neo4j-cypher/language-support": "2.0.0-next.39",
+    "@neo4j-cypher/lint-worker": "1.10.1-next.16"
   },
   "devDependencies": {
     "@neo4j-ndl/base": "^3.2.10",
@@ -77,10 +77,11 @@
     "dev": "tsc --watch",
     "build": "pnpm copy-lint-worker && tsc --declaration --outDir dist/",
     "copy-lint-worker": "copyfiles -u 4 ../lint-worker/dist/esm/lintWorker.mjs dist/src/lang-cypher && copyfiles -u 4 ../lint-worker/dist/esm/lintWorker.mjs src/lang-cypher",
+    "check-api-report": "tsx checkApiReport.ts",
+    "gen-api-report": "pnpm build && pnpm check-api-report",
     "clean": "rm -rf dist tsconfig*.tsbuildinfo",
     "test": "vitest run",
     "test:e2e": "playwright test -c playwright-ct.config.ts",
-    "test:e2e-ui": "playwright test -c playwright-ct.config.ts --ui",
-    "benchmark": "BENCHMARKING=true playwright test -c playwright-ct.config.ts -g \"benchmarking & performance test session\""
+    "test:e2e-ui": "playwright test -c playwright-ct.config.ts --ui"
   }
 }

package/src/CypherEditor.test.tsx

@@ -18,6 +18,7 @@ const onChange = vi.fn<(v: string) => void>((v) => {
   rerender();
 });
 
+// oxlint-disable-next-line typescript/no-explicit-any
 (global as any).IS_REACT_ACT_ENVIRONMENT = true;
 const DEBOUNCE_TIME_WITH_MARGIN = DEBOUNCE_TIME + 100;
 

package/src/CypherEditor.tsx

@@ -36,7 +36,9 @@ import { richClipboardCopier } from './richClipboardCopier';
 import type { LintWorker } from '@neo4j-cypher/lint-worker';
 import workerpool from 'workerpool';
 
-type DomEventHandlers = Parameters<typeof EditorView.domEventHandlers>[0];
+export type DomEventHandlers = Parameters<
+  typeof EditorView.domEventHandlers
+>[0];
 
 /**
  * Normalize CRLF line endings to LF, which is what CodeMirror expects.
@@ -187,6 +189,12 @@ export interface CypherEditorProps {
    */
   ariaLabel?: string;
 
+  /**
+   * Extra attributes to set on the editable content element, e.g. `aria-invalid` and
+   * `aria-describedby` to associate the editor with an error message rendered outside of it.
+   */
+  contentAttributes?: Record<string, string>;
+
   /**
    * Whether keybindings for inserting indents with the Tab key should be disabled.
    *
@@ -314,6 +322,7 @@ const readOnlyCompartment = new Compartment();
 const placeholderCompartment = new Compartment();
 const domEventHandlerCompartment = new Compartment();
 const diffCompartment = new Compartment();
+const contentAttributesCompartment = new Compartment();
 
 const formatLineNumber =
   (prompt?: string) => (a: number, state: EditorState) => {
@@ -324,7 +333,7 @@ const formatLineNumber =
     return a.toString();
   };
 
-type CypherEditorState = {
+export type CypherEditorState = {
   editorActionsContainer: HTMLElement | null;
 };
 
@@ -332,7 +341,7 @@ const ExternalEdit = Annotation.define<boolean>();
 const WorkerURL = new URL('./lang-cypher/lintWorker.mjs', import.meta.url)
   .pathname;
 
-class CodemirrorSymbolFetcher {
+export class CodemirrorSymbolFetcher {
   constructor(languageService: CypherLanguageService) {
     this.languageService = languageService;
   }
@@ -601,6 +610,9 @@ export class CypherEditor extends Component<
               'aria-label': this.props.ariaLabel,
             })
           : [],
+        contentAttributesCompartment.of(
+          EditorView.contentAttributes.of(this.props.contentAttributes ?? {}),
+        ),
         !this.props.moveFocusOnTab
           ? EditorView.contentAttributes.of({
               'aria-description':
@@ -747,6 +759,17 @@ export class CypherEditor extends Component<
       });
     }
 
+    if (
+      JSON.stringify(prevProps.contentAttributes) !==
+      JSON.stringify(this.props.contentAttributes)
+    ) {
+      this.editorView.current.dispatch({
+        effects: contentAttributesCompartment.reconfigure(
+          EditorView.contentAttributes.of(this.props.contentAttributes ?? {}),
+        ),
+      });
+    }
+
     if (prevProps.readonly !== this.props.readonly) {
       this.editorView.current.dispatch({
         effects: readOnlyCompartment.reconfigure(

package/src/index.ts

@@ -1,6 +1,20 @@
-export * as LanguageSupport from '@neo4j-cypher/language-support';
-export { CypherEditor } from './CypherEditor';
+import * as LanguageSupport from '@neo4j-cypher/language-support';
+export { LanguageSupport };
+export {
+  CypherEditor,
+  CypherEditorProps,
+  CypherEditorState,
+  CodemirrorSymbolFetcher,
+  DomEventHandlers,
+} from './CypherEditor';
 export type { InlinePanelProps } from './CypherEditor';
+export type { InlinePanelCallbacks } from './inlinePanel.js';
 export type { DiffProps } from './diffView';
-export { cypher } from './lang-cypher/langCypher';
+export { cypher, CypherConfig } from './lang-cypher/langCypher';
 export { darkThemeConstants, lightThemeConstants } from './themes';
+export type {
+  ThemeOptions,
+  DiffColors,
+} from './lang-cypher/createCypherTheme.js';
+export type { HostPortalCallbacks } from './hostCallbacks.js';
+export type { HighlightedCypherTokenTypes } from './lang-cypher/constants.js';

package/src/lang-cypher/createCypherTheme.ts

@@ -139,6 +139,53 @@ export const createCypherTheme = ({
     '& .cm-signature-help-panel-description': {
       padding: '5px',
     },
+    // Shared between both hover tooltips and hover errors
+    '& .cm-tooltip-hover': {
+      maxWidth: '800px',
+    },
+    '& .cm-hover-tooltip': {
+      backgroundColor: settings.autoCompletionPanel.backgroundColor,
+      color: settings.foreground,
+      maxHeight: '300px',
+      overflow: 'auto',
+      padding: '2px 10px',
+    },
+    '& .cm-hover-info': {
+      fontFamily:
+        '-apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Helvetica, Arial, sans-serif',
+      fontSize: '13px',
+      lineHeight: '1.5',
+      '& p': {
+        margin: '6px 0',
+      },
+      '& ul': {
+        margin: '6px 0',
+        paddingLeft: '18px',
+      },
+      '& li': {
+        margin: '2px 0',
+      },
+      '& code': {
+        fontFamily: 'Fira Code, Menlo, Monaco, Lucida Console, monospace',
+        fontSize: '12px',
+      },
+      '& pre': {
+        margin: '6px 0',
+        padding: '6px 8px',
+        borderRadius: '3px',
+        whiteSpace: 'pre-wrap',
+        overflowWrap: 'break-word',
+        backgroundColor: dark
+          ? 'rgba(255, 255, 255, 0.08)'
+          : 'rgba(0, 0, 0, 0.05)',
+      },
+      '& > *:first-child': {
+        marginTop: '0',
+      },
+      '& > *:last-child': {
+        marginBottom: '0',
+      },
+    },
     '.cm-completionInfo-signature': {
       color: 'darkgrey',
     },

package/src/lang-cypher/hover/hover.ts

@@ -0,0 +1,32 @@
+import type { HoverTooltipSource } from '@codemirror/view';
+import type { CypherConfig } from '../langCypher';
+import { renderHoverInfo } from './hoverRender';
+import { tooltipCypherHighlighter } from '../tooltipHighlighting.js';
+
+export function getHoverSource(cfg: CypherConfig): HoverTooltipSource {
+  const hoverSource: HoverTooltipSource = (view, pos) => {
+    const doc = view.state.doc.toString();
+    const hoverInfo = cfg.languageService.hoverInfo(doc, {
+      caretPosition: pos,
+      dbSchema: cfg.schema ?? {},
+    });
+
+    if (!hoverInfo) {
+      return null;
+    }
+
+    return {
+      pos: pos,
+      above: true,
+      create() {
+        const dom = document.createElement('div');
+        dom.className = 'cm-hover-tooltip';
+        dom.appendChild(
+          renderHoverInfo(hoverInfo, tooltipCypherHighlighter(view.state, cfg)),
+        );
+        return { dom };
+      },
+    };
+  };
+  return hoverSource;
+}

package/src/lang-cypher/hover/hoverRender.test.ts

@@ -0,0 +1,176 @@
+// @vitest-environment jsdom
+
+import type { HoverInfo } from '@neo4j-cypher/language-support';
+import {
+  CypherLanguageService,
+  testData,
+} from '@neo4j-cypher/language-support';
+import { describe, expect, test } from 'vitest';
+import type { CypherFragmentKind } from '../tooltipHighlighting.js';
+import { renderHoverInfo } from './hoverRender';
+
+function methodHover(query: string): HoverInfo {
+  const languageService = new CypherLanguageService();
+  return languageService.hoverInfo(query, {
+    caretPosition: query.indexOf('(') - 1,
+    dbSchema: testData.mockSchema,
+  });
+}
+
+function renderMethodHover(query: string): HTMLElement {
+  return renderHoverInfo(methodHover(query));
+}
+
+describe('hover info html rendering', () => {
+  function highlightedFragments(
+    info: HoverInfo,
+  ): [string, CypherFragmentKind][] {
+    const seen: [string, CypherFragmentKind][] = [];
+    renderHoverInfo(info, (code, kind, target) => {
+      seen.push([code, kind]);
+      target.textContent = code;
+    });
+    return seen;
+  }
+
+  test('passes the fragment kind of each cypher block to the highlighter', () => {
+    expect(
+      highlightedFragments({
+        kind: 'variable',
+        variable: 'n',
+        types: ['Node'],
+        labelExpression: '(Person | Pet)',
+      }),
+    ).toEqual([['(Person | Pet)', 'labelExpression']]);
+
+    expect(highlightedFragments(methodHover('RETURN abs(1)'))).toEqual([
+      ['abs(input :: INTEGER | FLOAT) :: INTEGER | FLOAT', 'function'],
+    ]);
+
+    expect(highlightedFragments(methodHover('CALL db.labels()'))).toEqual([
+      ['db.labels() :: (label :: STRING)', 'procedure'],
+    ]);
+  });
+
+  test('renders a variable hover', () => {
+    expect(
+      renderHoverInfo({
+        kind: 'variable',
+        variable: 'n',
+        types: ['Node'],
+        labelExpression: '(Person | Pet)',
+      }).innerHTML,
+    ).toBe('<p><code>n: Node</code></p><pre><code>(Person | Pet)</code></pre>');
+
+    expect(
+      renderHoverInfo({ kind: 'variable', variable: 'x', types: ['Integer'] })
+        .innerHTML,
+    ).toBe('<p><code>x: Integer</code></p>');
+  });
+
+  test('renders a function hover', () => {
+    expect(renderMethodHover('RETURN toFloat(1)').innerHTML).toBe(
+      [
+        '<pre><code>toFloat(input :: STRING | INTEGER | FLOAT) :: FLOAT</code></pre>',
+        '<p>Converts a <code>STRING</code>, <code>INTEGER</code> or <code>FLOAT</code> value to a <code>FLOAT</code> value.</p>',
+        '<p><strong>Parameters</strong></p>',
+        '<ul><li><code>input</code> - A value to be converted into a float.</li></ul>',
+        '<p><strong>Returns:</strong> <code>FLOAT</code></p>',
+      ].join(''),
+    );
+  });
+
+  test('renders a procedure hover', () => {
+    expect(renderMethodHover('CALL db.labels()').innerHTML).toBe(
+      [
+        '<pre><code>db.labels() :: (label :: STRING)</code></pre>',
+        "<p>List all labels attached to nodes within a database according to the user's access rights. The procedure returns empty results if the user is not authorized to view those labels.</p>",
+        '<p><strong>Returns</strong></p>',
+        '<ul><li><code>label</code> - A label within the database.</li></ul>',
+      ].join(''),
+    );
+  });
+
+  test('italicises the deprecation marker of a deprecated method', () => {
+    expect(
+      renderMethodHover('CYPHER 5 RETURN apoc.create.uuid()').innerHTML,
+    ).toContain('<p>(<em>deprecated</em>) Returns a UUID.</p>');
+  });
+
+  // The wildcards of dbms.queryJmx' descriptions are shown as written, both
+  // in prose and inside a code span
+  test('renders the wildcards of a procedure description', () => {
+    const html = renderMethodHover('CALL dbms.queryJmx()').innerHTML;
+
+    expect(html).toContain(
+      '<p>Query JMX management data by domain and name. For instance, use <code>*:*</code> to find all JMX beans.</p>',
+    );
+    expect(html).toContain(
+      "<li><code>query</code> - A query for MBeans on this MBeanServer (e.g. '*:*,name=*neo4j*' for all metrics in neo4j database).</li>",
+    );
+  });
+
+  test('renders the paragraphs, bullet list and italics of a procedure description', () => {
+    const html = renderMethodHover(
+      'CALL db.index.fulltext.queryNodes()',
+    ).innerHTML;
+
+    expect(html).toContain('Valid <em>key: value</em> pairs');
+    expect(html).toContain(
+      [
+        '<ul>',
+        "<li>'skip' -- to skip the top N results.</li>",
+        "<li>'limit' -- to limit the number of results returned.</li>",
+        "<li>'analyzer' -- to use the specified analyzer as a search analyzer for this query.</li>",
+        '</ul>',
+        '<p>The <code>options</code> map and any of the keys are optional.',
+      ].join(''),
+    );
+  });
+
+  test('renders a parameter that carries its own layout as a code block', () => {
+    expect(renderMethodHover('CALL apoc.export.csv.all()').innerHTML).toContain(
+      [
+        '<ul><li><code>file</code> - The name of the file to which the data will be exported.</li>',
+        '<li><code>config</code> -<pre><code>{\n',
+        '        stream = false :: BOOLEAN,\n',
+      ].join(''),
+    );
+  });
+
+  // Schema descriptions list values such as 'AS_PATH_LIST', which must not
+  // turn into emphasis
+  test('leaves the underscores inside words alone', () => {
+    const description =
+      "JSON path options: ('ALWAYS_RETURN_LIST', 'AS_PATH_LIST', 'DEFAULT_PATH_LEAF_TO_NULL').";
+
+    const dom = renderHoverInfo({
+      kind: 'function',
+      signature: 'f(pathOptions :: LIST<STRING>) :: ANY',
+      description: '',
+      isDeprecated: false,
+      parameters: [{ name: 'pathOptions', description }],
+      returnType: 'ANY',
+    });
+
+    expect(dom.querySelector('em')).toBeNull();
+    expect(dom.querySelector('li').textContent).toBe(
+      `pathOptions - ${description}`,
+    );
+  });
+
+  test('never renders descriptions as html', () => {
+    const dom = renderHoverInfo({
+      kind: 'procedure',
+      signature: 'p()',
+      description: '<img src=x onerror=alert(1)>',
+      isDeprecated: false,
+      parameters: [],
+      returnValues: [{ name: 'r', description: '<b>bold</b>' }],
+    });
+
+    expect(dom.querySelector('img')).toBeNull();
+    expect(dom.querySelector('b')).toBeNull();
+    expect(dom.textContent).toContain('<img src=x onerror=alert(1)>');
+  });
+});

package/src/lang-cypher/hover/hoverRender.ts

@@ -0,0 +1,198 @@
+/**
+ * Renders language-support's HoverInfo into the hover tooltip.
+ *
+ * Everything is inserted as text nodes, so schema-provided descriptions can
+ * never inject HTML into the editor.
+ */
+
+import type {
+  HoverDescription,
+  HoverInfo,
+} from '@neo4j-cypher/language-support';
+import type {
+  CypherFragmentKind,
+  TooltipCypherHighlighter,
+} from '../tooltipHighlighting.js';
+
+// The schema writes the bullet lists of its descriptions with *
+const bullet = '* ';
+
+export function renderHoverInfo(
+  info: HoverInfo,
+  highlightHoverCode?: TooltipCypherHighlighter,
+): HTMLElement {
+  const dom = document.createElement('div');
+  dom.className = 'cm-hover-info';
+
+  if (info.kind === 'variable') {
+    const typeLine = document.createElement('p');
+    typeLine.appendChild(
+      element('code', `${info.variable}: ${info.types.join(', ')}`),
+    );
+    dom.appendChild(typeLine);
+
+    if (info.labelExpression !== undefined) {
+      dom.appendChild(
+        codeBlock(info.labelExpression, 'labelExpression', highlightHoverCode),
+      );
+    }
+    return dom;
+  }
+
+  dom.appendChild(codeBlock(info.signature, info.kind, highlightHoverCode));
+
+  const deprecatedMarker = info.isDeprecated
+    ? [
+        document.createTextNode('('),
+        element('em', 'deprecated'),
+        document.createTextNode(') '),
+      ]
+    : [];
+  renderDescription(dom, info.description, deprecatedMarker);
+
+  appendDescribedList(dom, 'Parameters', info.parameters);
+
+  if (info.kind === 'function') {
+    if (info.returnType) {
+      const returns = document.createElement('p');
+      returns.append(
+        element('strong', 'Returns:'),
+        ' ',
+        element('code', info.returnType),
+      );
+      dom.appendChild(returns);
+    }
+  } else {
+    appendDescribedList(dom, 'Returns', info.returnValues);
+  }
+
+  return dom;
+}
+
+function element(tag: string, text: string): HTMLElement {
+  const created = document.createElement(tag);
+  created.textContent = text;
+  return created;
+}
+
+function codeBlock(
+  code: string,
+  kind: CypherFragmentKind | undefined,
+  highlightHoverCode?: TooltipCypherHighlighter,
+): HTMLElement {
+  const pre = document.createElement('pre');
+  const codeElement = document.createElement('code');
+
+  if (kind && highlightHoverCode) {
+    highlightHoverCode(code, kind, codeElement);
+  } else {
+    codeElement.textContent = code;
+  }
+
+  pre.appendChild(codeElement);
+  return pre;
+}
+
+function appendDescribedList(
+  dom: HTMLElement,
+  heading: string,
+  descriptions: HoverDescription[],
+) {
+  if (descriptions.length === 0) {
+    return;
+  }
+
+  const headingParagraph = document.createElement('p');
+  headingParagraph.appendChild(element('strong', heading));
+  dom.appendChild(headingParagraph);
+
+  const list = document.createElement('ul');
+  descriptions.forEach(({ name, description }) => {
+    const item = document.createElement('li');
+    item.append(element('code', name), ' -');
+
+    // Map-style descriptions (often configs) are laid out over several lines
+    const trimmed = description.trimEnd();
+    if (trimmed.includes('\n')) {
+      item.appendChild(codeBlock(trimmed, undefined));
+    } else {
+      item.append(' ');
+      renderInline(item, description);
+    }
+    list.appendChild(item);
+  });
+  dom.appendChild(list);
+}
+
+/* A schema description is prose that can bring paragraphs and * bullet lists.
+   `lead` goes in front of its first paragraph. */
+function renderDescription(
+  dom: HTMLElement,
+  description: string,
+  lead: Node[],
+) {
+  const lines = description.split('\n');
+  let paragraph: string[] = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0 && lead.length === 0) return;
+    const p = document.createElement('p');
+    p.append(...lead.splice(0));
+    renderInline(p, paragraph.join('\n'));
+    dom.appendChild(p);
+    paragraph = [];
+  };
+
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i].startsWith(bullet)) {
+      flushParagraph();
+      const list = document.createElement('ul');
+      while (i < lines.length && lines[i].startsWith(bullet)) {
+        const item = document.createElement('li');
+        renderInline(item, lines[i].slice(bullet.length));
+        list.appendChild(item);
+        i++;
+      }
+      dom.appendChild(list);
+      continue;
+    }
+
+    if (lines[i].trim() === '') {
+      if (paragraph.length > 0) flushParagraph();
+    } else {
+      paragraph.push(lines[i]);
+    }
+    i++;
+  }
+
+  flushParagraph();
+}
+
+/* Code spans and italics, the markup descriptions write. Underscores only
+   count as emphasis outside a word, so that descriptions listing values like
+   'DEFAULT_PATH_LEAF_TO_NULL' keep them - the same rule CommonMark
+   (https://spec.commonmark.org/0.31.2/#example-374) follows. */
+const inlineMarkup = /`([^`]+)`|(?<!\w)_([^_\n]+)_(?!\w)/g;
+
+function renderInline(target: HTMLElement, text: string) {
+  let lastEnd = 0;
+
+  for (const match of text.matchAll(inlineMarkup)) {
+    const [matched, code, italic] = match;
+
+    if (match.index > lastEnd) {
+      target.append(text.slice(lastEnd, match.index));
+    }
+
+    target.appendChild(
+      code !== undefined ? element('code', code.trim()) : element('em', italic),
+    );
+
+    lastEnd = match.index + matched.length;
+  }
+
+  if (lastEnd < text.length) {
+    target.append(text.slice(lastEnd));
+  }
+}

package/src/lang-cypher/langCypher.ts

@@ -10,6 +10,8 @@ import { completionStyles, cypherAutocomplete } from './autocomplete';
 import { ParserAdapter } from './parser-adapter';
 import { signatureHelpTooltip } from './signatureHelp';
 import { cypherLinter } from './syntaxValidation';
+import { hoverTooltip } from '@codemirror/view';
+import { getHoverSource } from './hover/hover.js';
 
 const facet = defineLanguageFacet({
   commentTokens: { block: { open: '/*', close: '*/' }, line: '//' },
@@ -40,5 +42,6 @@ export function cypher(config: CypherConfig) {
     }),
     cypherLinter(config),
     signatureHelpTooltip(config),
+    hoverTooltip(getHoverSource(config)),
   ]);
 }