From 68c525aeb3f8829f2203890bbad4335e69ba04a8 Mon Sep 17 00:00:00 2001
From: Yi Yang <Leopoldthecoder@users.noreply.github.com>
Date: Thu, 26 Dec 2024 16:01:05 +0800
Subject: [PATCH] feat(expressions): support token doc (#1874)

---
 packages/core/expressions/docs/expressions-editor.md |  8 ++++++++
 .../expressions/src/components/ExpressionsEditor.vue |  5 +++++
 packages/core/expressions/src/monaco.ts              | 12 ++++++++----
 packages/core/expressions/src/schema.ts              |  7 ++++---
 4 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/packages/core/expressions/docs/expressions-editor.md b/packages/core/expressions/docs/expressions-editor.md
index 32609ad671..505b815704 100644
--- a/packages/core/expressions/docs/expressions-editor.md
+++ b/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`
diff --git a/packages/core/expressions/src/components/ExpressionsEditor.vue b/packages/core/expressions/src/components/ExpressionsEditor.vue
index 1236fcd77c..4b7faeec8d 100644
--- a/packages/core/expressions/src/components/ExpressionsEditor.vue
+++ b/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
diff --git a/packages/core/expressions/src/monaco.ts b/packages/core/expressions/src/monaco.ts
index 0d54b1aab5..d4607aeec8 100644
--- a/packages/core/expressions/src/monaco.ts
+++ b/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,
         })),
diff --git a/packages/core/expressions/src/schema.ts b/packages/core/expressions/src/schema.ts
index 45cb62e272..dc9e276bd2 100644
--- a/packages/core/expressions/src/schema.ts
+++ b/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) => {