feat(compass-editor): add links to the documentation to the agg and stage autocompleter suggestions COMPASS-6688 (#4218)

feat(compass-editor): add links to the documentation to the agg and stage autocompleter suggestions

Author: gribnoysup

packages/compass-editor/src/codemirror/ace-compat-autocompleter.ts

@@ -21,7 +21,27 @@ export function mapMongoDBCompletionToCodemirrorCompletion(
         ? completion.value
         : wrapField(completion.value, escape === 'always'),
     detail: completion.meta?.startsWith('field') ? 'field' : completion.meta,
-    info: completion.description,
+    info() {
+      if (!completion.description) {
+        return null;
+      }
+
+      const infoNode = document.createElement('div');
+      infoNode.classList.add('completion-info');
+      infoNode.addEventListener('mousedown', (evt) => {
+        // If we are clicking a link inside the info block, we have to prevent
+        // default browser behavior that will remove the focus from the editor
+        // and cause the autocompleter to dissapear before browser handles the
+        // actual click. This is very similar to how codemirror handles clicks
+        // on the list items
+        // @see {@link https://github.com/codemirror/autocomplete/blob/82480a7d51d60ad933808e42f6189d841a5a6bc8/src/tooltip.ts#L96-L97}
+        if ((evt.target as HTMLElement).nodeName === 'A') {
+          evt.preventDefault();
+        }
+      });
+      infoNode.innerHTML = completion.description;
+      return infoNode;
+    },
   };
 
   if (completion.snippet) {

packages/compass-editor/src/codemirror/aggregation-autocompleter.ts

@@ -3,50 +3,15 @@ import { STAGE_OPERATOR_NAMES } from '@mongodb-js/mongodb-constants';
 import type { CompleteOptions } from '../autocompleter';
 import { completer } from '../autocompleter';
 import type { Token } from './utils';
+import { parents } from './utils';
+import { getPropertyNameFromPropertyToken, isTokenEqual } from './utils';
+import { aggLink, padLines } from './utils';
 import { createCompletionResultForIdPrefix } from './ace-compat-autocompleter';
 import { createAceCompatAutocompleter } from './ace-compat-autocompleter';
 import { createStageAutocompleter } from './stage-autocompleter';
 
 const StageOperatorNames = new Set(STAGE_OPERATOR_NAMES as string[]);
 
-function* parents(token: Token) {
-  let parent: Token | null = token;
-  while ((parent = parent.parent)) {
-    yield parent;
-  }
-}
-
-function removeQuotes(str: string) {
-  return str.replace(/(^('|")|('|")$)/g, '');
-}
-
-// lezer tokens are immutable, we check position in syntax tree to make sure we
-// are looking at the same token
-function isTokenEqual(a: Token, b: Token) {
-  return a.from === b.from && a.to === b.to;
-}
-
-function getPropertyNameFromPropertyToken(
-  editorState: EditorState,
-  propertyToken: Token
-): string {
-  if (!propertyToken.firstChild) {
-    return '';
-  }
-  return removeQuotes(getTokenText(editorState, propertyToken.firstChild));
-}
-
-function padLines(str: string, pad = '  ') {
-  return str
-    .split('\n')
-    .map((line) => `${pad}${line}`)
-    .join('\n');
-}
-
-function getTokenText(editorState: EditorState, token: Token) {
-  return editorState.sliceDoc(token.from, token.to);
-}
-
 function getStageNameForToken(
   editorState: EditorState,
   token: Token
@@ -93,6 +58,11 @@ export function createAggregationAutocompleter(
           const opName = completion.value;
           return {
             ...completion,
+            ...(completion.description && {
+              description:
+                `<p>${aggLink(opName)} pipeline stage</p>` +
+                `<p>${completion.description}</p>`,
+            }),
             ...(completion.snippet && {
               snippet: !isInsideBlock
                 ? `{\n${padLines(`${opName}: ${completion.snippet}`)}\n}`

packages/compass-editor/src/codemirror/stage-autocompleter.ts

@@ -5,13 +5,9 @@ import {
   createAceCompatAutocompleter,
   createCompletionResultForIdPrefix,
 } from './ace-compat-autocompleter';
-import { completeWordsInString } from './utils';
+import { aggLink, completeWordsInString } from './utils';
 import { createQueryAutocompleter } from './query-autocompleter';
 
-/**
- * Autocompleter for the document object, only autocompletes field names in the
- * appropriate format (either escaped or not) both for javascript and json modes
- */
 export const createStageAutocompleter = ({
   stageOperator,
   ...options
@@ -36,6 +32,15 @@ export const createStageAutocompleter = ({
         ? (['accumulator', 'accumulator:*'] as const)
         : []),
     ],
+  }).map((completion) => {
+    if (completion.meta?.startsWith('expr:')) {
+      return {
+        ...completion,
+        description: `<p>${aggLink(completion.value)} pipeline operator</p>`,
+      };
+    }
+
+    return completion;
   });
 
   return createAceCompatAutocompleter({

packages/compass-editor/src/codemirror/utils.ts

@@ -1,6 +1,7 @@
 import { completeAnyWord, ifIn } from '@codemirror/autocomplete';
 import type { CompletionContext } from '@codemirror/autocomplete';
 import { syntaxTree } from '@codemirror/language';
+import type { EditorState } from '@codemirror/state';
 
 export const completeWordsInString = ifIn(['String'], completeAnyWord);
 
@@ -10,6 +11,49 @@ export function resolveTokenAtCursor(context: CompletionContext) {
 
 export type Token = ReturnType<typeof resolveTokenAtCursor>;
 
+export function aggLink(op: string): string {
+  op = op.replace(/^\$/, '');
+  return `<a target="_blank" href="https://www.mongodb.com/docs/manual/reference/operator/aggregation/${op}/">$${op}</a>`;
+}
+
+export function padLines(str: string, pad = '  ') {
+  return str
+    .split('\n')
+    .map((line) => `${pad}${line}`)
+    .join('\n');
+}
+
+export function* parents(token: Token) {
+  let parent: Token | null = token;
+  while ((parent = parent.parent)) {
+    yield parent;
+  }
+}
+
+export function removeQuotes(str: string) {
+  return str.replace(/(^('|")|('|")$)/g, '');
+}
+
+// lezer tokens are immutable, we check position in syntax tree to make sure we
+// are looking at the same token
+export function isTokenEqual(a: Token, b: Token) {
+  return a.from === b.from && a.to === b.to;
+}
+
+export function getPropertyNameFromPropertyToken(
+  editorState: EditorState,
+  propertyToken: Token
+): string {
+  if (!propertyToken.firstChild) {
+    return '';
+  }
+  return removeQuotes(getTokenText(editorState, propertyToken.firstChild));
+}
+
+export function getTokenText(editorState: EditorState, token: Token) {
+  return editorState.sliceDoc(token.from, token.to);
+}
+
 /**
  * Returns the list of possible ancestors of the token.
  */

packages/compass-editor/src/json-editor.tsx

@@ -304,6 +304,17 @@ function getStylesForTheme(theme: CodemirrorThemeType) {
         fontWeight: 'bold',
         textDecoration: 'none',
       },
+      '& .cm-tooltip .completion-info p': {
+        margin: 0,
+        marginTop: `${spacing[2]}px`,
+        marginBottom: `${spacing[2]}px`,
+      },
+      '& .cm-tooltip .completion-info p:first-child': {
+        marginTop: 0,
+      },
+      '& .cm-tooltip .completion-info p:last-child': {
+        marginBottom: 0,
+      },
       '& .cm-widgetBuffer': {
         // Default is text-top which causes weird 1px added to the line height
         // when widget (in our case this is placeholder widget) is shown in the