feat(expressions): support token doc (#1874)

packages/core/expressions/docs/expressions-editor.md

@@ -60,6 +60,14 @@ To control whether the editor should be inactive until its initial focus.
 
 To control whether the editor should pass validation with an empty input.
 
+#### `defaultShowDetails`
+
+- type: `boolean`
+- required: `false`
+- default: `false`
+
+To control whether the editor should show the details of the autocompletion item by default.
+
 #### `editorOptions`
 
 - type: `Monaco.editor.IEditorOptions`

packages/core/expressions/src/components/ExpressionsEditor.vue

@@ -25,6 +25,7 @@ const props = withDefaults(defineProps<{
   parseDebounce?: number,
   inactiveUntilFocused?: boolean,
   allowEmptyInput?: boolean,
+  defaultShowDetails?: boolean,
   editorOptions?: Monaco.editor.IEditorOptions
 }>(), {
   parseDebounce: 500,
@@ -80,6 +81,10 @@ onMounted(() => {
     ...props.editorOptions,
   })
 
+  if (props.defaultShowDetails) {
+    editor.getContribution<Record<string, any> & Monaco.editor.IEditorContribution>('editor.contrib.suggestController')
+      ?.widget?.value._setDetailsVisible(true)
+  }
   editor.onDidChangeModelContent(() => {
     const value = editor!.getValue()
     expression.value = value

packages/core/expressions/src/monaco.ts

@@ -1,5 +1,5 @@
 import * as monaco from 'monaco-editor'
-import { type Schema, type SchemaDefinition } from './schema'
+import { type Schema } from './schema'
 
 interface MonarchLanguage extends monaco.languages.IMonarchLanguage {
   keywords: string[];
@@ -8,12 +8,14 @@ interface MonarchLanguage extends monaco.languages.IMonarchLanguage {
 interface Token {
   detail?: string;
   children?: Record<string, Token>;
+  documentation?: string;
 }
 
-const buildTokenTree = (schemaDefinition: SchemaDefinition) => {
+const buildTokenTree = (schema: Schema) => {
+  const { definition, documentation } = schema
   const root: Token = {}
 
-  for (const [kind, fields] of Object.entries(schemaDefinition)) {
+  for (const [kind, fields] of Object.entries(definition)) {
     for (const field of fields) {
       let token = root
       for (const t of field.split('.')) {
@@ -26,6 +28,7 @@ const buildTokenTree = (schemaDefinition: SchemaDefinition) => {
         token = token.children[t]
       }
       token.detail = kind
+      token.documentation = documentation?.[field]
     }
   }
 
@@ -61,7 +64,7 @@ export const registerLanguage = (schema: Schema) => {
     return { languageId }
   }
 
-  const tokenTree = buildTokenTree(schema.definition)
+  const tokenTree = buildTokenTree(schema)
 
   const keywords = ['not', 'in', 'contains']
 
@@ -154,6 +157,7 @@ export const registerLanguage = (schema: Schema) => {
           label: token === '*' ? '...' : token,
           kind: monaco.languages.CompletionItemKind.Property,
           detail: props.detail,
+          documentation: props.documentation,
           insertText: token === '*' ? '' : token,
           range,
         })),

packages/core/expressions/src/schema.ts

@@ -1,12 +1,13 @@
 import { Schema as AtcSchema, type AstType } from '@kong/atc-router'
 
 export type SchemaDefinition = {
-  [K in AstType]?: string[];
+  [K in AstType]?: string[]
 }
 
 export interface Schema {
-  name: string;
-  definition: SchemaDefinition;
+  name: string
+  definition: SchemaDefinition
+  documentation?: Record<string, string>
 }
 
 export const createSchema = (definition: SchemaDefinition) => {