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

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

@@ -4,14 +4,14 @@ import {
   Language,
   LanguageSupport,
 } from '@codemirror/language';
-import {
-  CypherLanguageService,
-  type DbSchema,
-} from '@neo4j-cypher/language-support';
+import type { CypherLanguageService } from '@neo4j-cypher/language-support';
+import { type DbSchema } from '@neo4j-cypher/language-support';
 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: '//' },
@@ -42,5 +42,6 @@ export function cypher(config: CypherConfig) {
     }),
     cypherLinter(config),
     signatureHelpTooltip(config),
+    hoverTooltip(getHoverSource(config)),
   ]);
 }