@api-client/ui 0.5.12 → 0.5.13

package/src/elements/code-editor/internals/CodeEditor.ts

@@ -1,8 +1,15 @@
 import { html, LitElement, PropertyValues, TemplateResult, nothing } from 'lit'
 import { property, query, state } from 'lit/decorators.js'
 import { classMap } from 'lit/directives/class-map.js'
+import { linter } from '@codemirror/lint'
 import { EditorState, Extension } from '@codemirror/state'
-import { autocompletion, CompletionContext, CompletionResult, CompletionSource } from '@codemirror/autocomplete'
+import {
+  autocompletion,
+  CompletionContext,
+  type CompletionResult,
+  type CompletionSource,
+  type Completion,
+} from '@codemirror/autocomplete'
 import { javascript } from '@codemirror/lang-javascript'
 import { syntaxHighlighting, defaultHighlightStyle } from '@codemirror/language'
 import { oneDark } from '@codemirror/theme-one-dark'
@@ -10,120 +17,16 @@ import { keymap } from '@codemirror/view'
 import { defaultKeymap } from '@codemirror/commands'
 import {
   EditorView,
-  MatchDecorator,
   Decoration,
   DecorationSet,
   ViewPlugin,
   ViewUpdate,
-  WidgetType,
+  hoverTooltip,
+  type Tooltip,
 } from '@codemirror/view'
-
-export interface FunctionSchema {
-  /** Unique identifier for the function */
-  id: string
-  /** Function name */
-  name: string
-  /** Function description */
-  description?: string
-  /** Function parameters */
-  parameters?: FunctionParameter[]
-  /** Return type description */
-  returns?: string
-  /** Additional metadata */
-  metadata?: Record<string, unknown>
-}
-
-export interface FunctionParameter {
-  /** Parameter name */
-  name: string
-  /** Parameter type */
-  type: string
-  /** Parameter description */
-  description?: string
-  /** Whether parameter is required */
-  required?: boolean
-  /** Default value */
-  defaultValue?: unknown
-}
-
-export interface Suggestion {
-  /** Unique identifier for the suggestion */
-  id: string
-  /** Main label displayed */
-  label: string
-  /** Supporting description text */
-  description?: string
-  /** Suffix text (e.g., type, category) */
-  suffix?: string
-  /** Additional data associated with the suggestion */
-  data?: Record<string, unknown>
-}
-
-export interface FunctionInsertEvent {
-  /** The inserted function schema */
-  functionSchema: FunctionSchema
-  /** The position where the function was inserted */
-  position: number
-}
-
-export interface SuggestionInsertEvent {
-  /** The inserted suggestion */
-  suggestion: Suggestion
-  /** The position where the suggestion was inserted */
-  position: number
-}
-
-class PlaceholderWidget extends WidgetType {
-  constructor(public placeholderText: string) {
-    super()
-  }
-
-  override eq(other: WidgetType): boolean {
-    return this.placeholderText == (other as PlaceholderWidget).placeholderText
-  }
-
-  toDOM(): HTMLElement {
-    const placeholder = document.createElement('span')
-    placeholder.className = 'cm-pill'
-    placeholder.textContent = this.placeholderText
-    return placeholder
-  }
-
-  override ignoreEvent(): boolean {
-    return false
-  }
-}
-
-// We do variables Salesforce style, with double curly braces.
-// This decorator replaces {{variable}} with a placeholder widget.
-const placeholderMatcher = new MatchDecorator({
-  regexp: /\{\{(\w+)\}\}/g,
-  decoration: (match) =>
-    Decoration.replace({
-      widget: new PlaceholderWidget(match[1]),
-    }),
-})
-
-/**
- * @see https://codemirror.net/examples/decoration/
- */
-class AtomicDecorationRange {
-  placeholders: DecorationSet
-  constructor(view: EditorView) {
-    this.placeholders = placeholderMatcher.createDeco(view)
-  }
-  update(update: ViewUpdate) {
-    this.placeholders = placeholderMatcher.updateDeco(update, this.placeholders)
-  }
-}
-
-const placeholders = ViewPlugin.fromClass(AtomicDecorationRange, {
-  decorations: (instance) => instance.placeholders,
-  provide: (plugin) =>
-    EditorView.atomicRanges.of((view) => {
-      return view.plugin(plugin)?.placeholders || Decoration.none
-    }),
-})
+import { functionLinter } from './Linter.js'
+import type { FunctionInsertEvent, FunctionSchema, Suggestion, SuggestionInsertEvent } from './types.js'
+import { SuggestionMatchDecorator } from './SuggestionMatchDecorator.js'
 
 /**
  * A CodeMirror 6 based editor component that supports function autocomplete and suggestion placeholders.
@@ -232,9 +135,11 @@ export default class CodeEditor extends LitElement {
   private accessor isEditorFocus = false
 
   private editorView?: EditorView
-  private suggestionMap = new Map<string, Suggestion>()
-  private functionMap = new Map<string, FunctionSchema>()
   private _previousValue = ''
+  /**
+   * Matcher for suggestion placeholders in the editor.
+   */
+  placeholderMatcher?: SuggestionMatchDecorator
 
   /**
    * Get all suggestions (placeholders) currently in the editor
@@ -254,11 +159,6 @@ export default class CodeEditor extends LitElement {
     return suggestions
   }
 
-  override connectedCallback(): void {
-    super.connectedCallback()
-    this.setupSuggestionMaps()
-  }
-
   override disconnectedCallback(): void {
     super.disconnectedCallback()
     this.editorView?.destroy()
@@ -272,8 +172,10 @@ export default class CodeEditor extends LitElement {
   override willUpdate(changedProperties: PropertyValues): void {
     super.willUpdate(changedProperties)
 
-    if (changedProperties.has('suggestions') || changedProperties.has('functionSchemas')) {
-      this.setupSuggestionMaps()
+    if (changedProperties.has('suggestions')) {
+      if (this.placeholderMatcher) {
+        this.placeholderMatcher.suggestions = this.suggestions || []
+      }
     }
 
     if (changedProperties.has('value') && this.editorView) {
@@ -305,8 +207,9 @@ export default class CodeEditor extends LitElement {
           this.handleFocusChange(update.view.hasFocus)
         }
       }),
-      placeholders,
-      // linter((view) => functionLinter(view as unknown as EditorView, this.functionSchemas)),
+      this.createPlaceholderPlugin(),
+      hoverTooltip(this.createHoverTooltipSource),
+      linter((view) => functionLinter(view, this.functionSchemas, (e) => this.dispatchEvent(e))),
     ]
 
     // Add language support
@@ -339,6 +242,30 @@ export default class CodeEditor extends LitElement {
     })
   }
 
+  /**
+   * Creates the ViewPlugin for rendering suggestion placeholders.
+   * This is created as a method to get access to the component's `suggestions`.
+   */
+  private createPlaceholderPlugin(): Extension {
+    const placeholderMatcher = new SuggestionMatchDecorator(/\{\{(\w+)\}\}/g, this.suggestions)
+    this.placeholderMatcher = placeholderMatcher
+    // This class needs to be defined here to have access to the `placeholderMatcher`
+    class AtomicDecorationRange {
+      placeholders: DecorationSet
+      constructor(view: EditorView) {
+        this.placeholders = placeholderMatcher.createDeco(view)
+      }
+      update(update: ViewUpdate) {
+        this.placeholders = placeholderMatcher.updateDeco(update, this.placeholders)
+      }
+    }
+
+    return ViewPlugin.fromClass(AtomicDecorationRange, {
+      decorations: (instance) => instance.placeholders,
+      provide: (plugin) => EditorView.atomicRanges.of((view) => view.plugin(plugin)?.placeholders || Decoration.none),
+    })
+  }
+
   /**
    * Create completion source for functions and suggestions
    */
@@ -354,19 +281,7 @@ export default class CodeEditor extends LitElement {
         const prefix = functionMatch[1]
         const functions = this.functionSchemas
           .filter((fn) => fn.name.toLowerCase().startsWith(prefix.toLowerCase()))
-          .map((fn) => ({
-            label: fn.name,
-            detail: fn.description || '',
-            info: this.formatFunctionInfo(fn),
-            apply: (view: EditorView, completion: unknown, from: number, to: number) => {
-              const functionCall = this.formatFunctionCall(fn)
-              view.dispatch({
-                changes: { from, to, insert: functionCall },
-                selection: { anchor: from + functionCall.length },
-              })
-              this.dispatchFunctionInsert(fn, from)
-            },
-          }))
+          .map((fn) => this.createFunctionCompletion(fn))
 
         if (functions.length > 0) {
           return {
@@ -382,19 +297,7 @@ export default class CodeEditor extends LitElement {
         const prefix = suggestionMatch[1]
         const suggestions = this.suggestions
           .filter((suggestion) => suggestion.label.toLowerCase().startsWith(prefix.toLowerCase()))
-          .map((suggestion) => ({
-            label: suggestion.label,
-            detail: suggestion.description || '',
-            info: suggestion.suffix || '',
-            apply: (view: EditorView, completion: unknown, from: number, to: number) => {
-              const placeholderText = `{{${suggestion.label}}}`
-              view.dispatch({
-                changes: { from: from - 2, to, insert: placeholderText }, // -2 to include the {{
-                selection: { anchor: from - 2 + placeholderText.length },
-              })
-              this.dispatchSuggestionInsert(suggestion, from - 2)
-            },
-          }))
+          .map((suggestion) => this.createSuggestionCompletion(suggestion))
 
         if (suggestions.length > 0) {
           return {
@@ -408,25 +311,132 @@ export default class CodeEditor extends LitElement {
     }
   }
 
+  private createFunctionCompletion(schema: FunctionSchema): Completion {
+    const result: Completion = {
+      label: schema.name,
+      detail: schema.description || '',
+      info: () => this.createFunctionInfoElement(schema),
+      apply: (view: EditorView, completion: unknown, from: number, to: number) => {
+        const functionCall = this.formatFunctionCall(schema)
+        view.dispatch({
+          changes: { from, to, insert: functionCall },
+          selection: { anchor: from + functionCall.length },
+        })
+        this.dispatchFunctionInsert(schema, from)
+      },
+    }
+
+    return result
+  }
+
+  private createSuggestionCompletion(suggestion: Suggestion): Completion {
+    const result: Completion = {
+      label: suggestion.label,
+      detail: suggestion.description || '',
+      info: suggestion.suffix || '',
+      apply: (view: EditorView, completion: unknown, from: number, to: number) => {
+        const placeholderText = `{{${suggestion.label}}}`
+        view.dispatch({
+          changes: { from: from - 2, to, insert: placeholderText }, // -2 to include the {{
+          selection: { anchor: from - 2 + placeholderText.length },
+        })
+        this.dispatchSuggestionInsert(suggestion, from - 2)
+      },
+    }
+
+    return result
+  }
+
+  /**
+   * Creates the source for the hover tooltips.
+   * This is an arrow function to automatically bind `this`.
+   */
+  private createHoverTooltipSource = (view: EditorView, pos: number): Tooltip | null => {
+    const word = view.state.wordAt(pos)
+    if (!word) {
+      return null
+    }
+
+    const functionName = view.state.doc.sliceString(word.from, word.to)
+    const fnSchema = this.functionSchemas.find((schema) => schema.name === functionName)
+
+    if (!fnSchema) {
+      return null
+    }
+
+    return {
+      pos: word.from,
+      end: word.to,
+      above: true,
+      create: () => ({ dom: this.createFunctionInfoElement(fnSchema) }),
+    }
+  }
+
   /**
-   * Format function information for autocomplete
+   * Creates a styled HTML element to display function documentation.
+   * This is used for both hover tooltips and autocomplete info panels.
    */
-  private formatFunctionInfo(fn: FunctionSchema): string {
-    let info = fn.description || ''
+  private createFunctionInfoElement(fn: FunctionSchema): HTMLElement {
+    const container = document.createElement('div')
+    container.className = 'function-info' // for styling
+
+    if (fn.description) {
+      const description = document.createElement('p')
+      description.className = 'description'
+      description.textContent = fn.description
+      container.appendChild(description)
+    }
+
     if (fn.parameters && fn.parameters.length > 0) {
-      info += '\n\nParameters:\n'
+      const paramsContainer = document.createElement('div')
+      paramsContainer.className = 'parameters'
+
+      const paramsHeader = document.createElement('h4')
+      paramsHeader.textContent = 'Parameters'
+      paramsContainer.appendChild(paramsHeader)
+
+      const paramsList = document.createElement('ul')
       fn.parameters.forEach((param) => {
-        info += `• ${param.name}: ${param.type}`
+        const listItem = document.createElement('li')
+
+        const name = document.createElement('span')
+        name.className = 'param-name'
+        name.textContent = param.name
+
+        const type = document.createElement('span')
+        type.className = 'param-type'
+        type.textContent = `: ${param.type}`
+
+        listItem.appendChild(name)
+        listItem.appendChild(type)
+
         if (param.description) {
-          info += ` - ${param.description}`
+          const paramDesc = document.createElement('p')
+          paramDesc.className = 'param-description'
+          paramDesc.textContent = param.description
+          listItem.appendChild(paramDesc)
         }
-        info += '\n'
+        paramsList.appendChild(listItem)
       })
+      paramsContainer.appendChild(paramsList)
+      container.appendChild(paramsContainer)
     }
+
     if (fn.returns) {
-      info += `\nReturns: ${fn.returns}`
+      const returnsContainer = document.createElement('div')
+      returnsContainer.className = 'returns'
+
+      const returnsHeader = document.createElement('h4')
+      returnsHeader.textContent = 'Returns'
+      returnsContainer.appendChild(returnsHeader)
+
+      const returnsDesc = document.createElement('p')
+      returnsDesc.textContent = fn.returns
+      returnsContainer.appendChild(returnsDesc)
+      container.appendChild(returnsContainer)
     }
-    return info
+
+    return container
   }
 
   /**
@@ -449,22 +459,6 @@ export default class CodeEditor extends LitElement {
     return `${fn.name}(${params})`
   }
 
-  /**
-   * Setup suggestion and function maps for quick lookup
-   */
-  private setupSuggestionMaps(): void {
-    this.suggestionMap.clear()
-    this.functionMap.clear()
-
-    this.suggestions.forEach((suggestion) => {
-      this.suggestionMap.set(suggestion.id, suggestion)
-    })
-
-    this.functionSchemas.forEach((fn) => {
-      this.functionMap.set(fn.id, fn)
-    })
-  }
-
   /**
    * Update editor content when value changes
    */

package/src/elements/code-editor/internals/Linter.ts

@@ -1,13 +1,17 @@
 import type { Diagnostic } from '@codemirror/lint'
 import type { EditorView } from '@codemirror/view'
-import Element from './CodeEditor.js'
+import type { FunctionSchema } from './types.js'
 
-export function functionLinter(view: EditorView, element: Element): readonly Diagnostic[] {
+export function functionLinter(
+  view: EditorView,
+  functionSchemas: readonly FunctionSchema[],
+  dispatchEvent: (e: CustomEvent) => void
+): readonly Diagnostic[] {
   const diagnostics: Diagnostic[] = []
   const doc = view.state.doc
   const text = doc.toString()
 
-  const functions = element.functionSchemas
+  const functions = functionSchemas
   if (!functions || functions.length === 0) {
     return diagnostics
   }
@@ -22,22 +26,21 @@ export function functionLinter(view: EditorView, element: Element): readonly Dia
     const endPos = startPos + functionName.length
 
     // Check if this function exists in our schemas
-    const functionExists = functions.some((schema) => schema.name === functionName)
+    const fn = functions.find((schema) => schema.name === functionName)
 
-    if (!functionExists) {
+    if (!fn) {
       diagnostics.push({
         from: startPos,
         to: endPos,
         severity: 'error',
-        message: `Unknown function "${functionName}". Only functions defined in the schema are allowed.`,
+        message: `Unknown function "${functionName}". Make sure you have the correct syntax for the function call.`,
         actions: [
           {
             name: 'View available functions',
             apply: () => {
-              // This could trigger showing a help dialog or documentation
-              element.dispatchEvent(
+              dispatchEvent(
                 new CustomEvent('show-available-functions', {
-                  detail: { availableFunctions: functions.map((s) => s.name) },
+                  detail: { availableFunctions: [...functions] },
                   bubbles: true,
                 })
               )
@@ -46,38 +49,33 @@ export function functionLinter(view: EditorView, element: Element): readonly Dia
         ],
       })
     } else {
-      // Optional: Validate function usage (parameters, etc.)
-      const fn = functions.find((schema) => schema.name === functionName)
+      // Extract the function call content to validate parameters
+      const functionCallMatch = text.substring(startPos).match(/(\w+)\s*\(([^)]*)\)/)
+      if (functionCallMatch && fn.parameters && fn.parameters.length > 0) {
+        const argsString = functionCallMatch[2].trim()
+        const args = argsString ? argsString.split(',').map((arg) => arg.trim()) : []
 
-      if (fn) {
-        // Extract the function call content to validate parameters
-        const functionCallMatch = text.substring(startPos).match(/(\w+)\s*\(([^)]*)\)/)
-        if (functionCallMatch && fn.parameters) {
-          const argsString = functionCallMatch[2].trim()
-          const args = argsString ? argsString.split(',').map((arg) => arg.trim()) : []
-
-          // Check required parameters
-          const requiredParams = fn.parameters.filter((p) => p.required)
-          if (args.length < requiredParams.length) {
-            const functionEndPos = startPos + functionCallMatch[0].length
-            diagnostics.push({
-              from: startPos,
-              to: functionEndPos,
-              severity: 'error',
-              message: `Function "${functionName}" requires ${requiredParams.length} parameters but got ${args.length}. Required: ${requiredParams.map((p) => p.name).join(', ')}`,
-            })
-          }
+        // Check required parameters
+        const requiredParams = fn.parameters.filter((p) => p.required)
+        if (args.length < requiredParams.length) {
+          const functionEndPos = startPos + functionCallMatch[0].length
+          diagnostics.push({
+            from: startPos,
+            to: functionEndPos,
+            severity: 'error',
+            message: `Function "${functionName}" requires ${requiredParams.length} parameters but got ${args.length}. Required: ${requiredParams.map((p) => p.name).join(', ')}`,
+          })
+        }
 
-          // Check if too many parameters
-          if (fn.parameters && args.length > fn.parameters.length) {
-            const functionEndPos = startPos + functionCallMatch[0].length
-            diagnostics.push({
-              from: startPos,
-              to: functionEndPos,
-              severity: 'warning',
-              message: `Function "${functionName}" expects at most ${fn.parameters.length} parameters but got ${args.length}`,
-            })
-          }
+        // Check if too many parameters
+        if (fn.parameters && args.length > fn.parameters.length) {
+          const functionEndPos = startPos + functionCallMatch[0].length
+          diagnostics.push({
+            from: startPos,
+            to: functionEndPos,
+            severity: 'warning',
+            message: `Function "${functionName}" expects at most ${fn.parameters.length} parameters but got ${args.length}`,
+          })
         }
       }
     }

package/src/elements/code-editor/internals/PlaceholderWidget.ts

@@ -0,0 +1,50 @@
+import { EditorView, WidgetType } from '@codemirror/view'
+import type { Suggestion } from './types.js'
+import '../../../md/chip/ui-chip.js'
+
+/**
+ * A widget that represents a placeholder in the code editor,
+ * specifically for suggestions that are replaced with chips.
+ *
+ * This widget is used to create a visual representation of a suggestion
+ * in the code editor, allowing users to see and interact with suggestions
+ * as chips. When a chip is removed, the corresponding text in the editor
+ * is also removed.
+ */
+export class ChipWidget extends WidgetType {
+  constructor(public suggestion: Suggestion) {
+    super()
+  }
+
+  override eq(other: WidgetType): boolean {
+    return this.suggestion.id == (other as ChipWidget).suggestion.id
+  }
+
+  toDOM(view: EditorView): HTMLElement {
+    const wrapper = document.createElement('span')
+    wrapper.className = 'mention-chip'
+    wrapper.setAttribute('data-mention-id', this.suggestion.id)
+
+    const chip = document.createElement('ui-chip')
+    chip.setAttribute('type', 'input')
+    chip.setAttribute('removable', 'true')
+    chip.textContent = this.suggestion.label
+    chip.addEventListener('remove', () => {
+      const pos = view.posAtDOM(wrapper)
+      if (pos === null) return
+
+      const originalText = `{{${this.suggestion.label}}}`
+      view.dispatch({
+        changes: { from: pos, to: pos + originalText.length, insert: '' },
+      })
+      view.focus()
+    })
+
+    wrapper.appendChild(chip)
+    return wrapper
+  }
+
+  override ignoreEvent(): boolean {
+    return false
+  }
+}

package/src/elements/code-editor/internals/SuggestionMatchDecorator.ts

@@ -0,0 +1,36 @@
+import { MatchDecorator, Decoration } from '@codemirror/view'
+import type { Suggestion } from './types.js'
+import { ChipWidget } from './PlaceholderWidget.js'
+
+/**
+ * A class that specializes in creating and managing decorations for suggestion matches in a code editor.
+ */
+export class SuggestionMatchDecorator extends MatchDecorator {
+  /**
+   * Creates a new instance of SuggestionMatchDecorator.
+   * @param regexp - The regular expression used to match suggestions in the code.
+   * @param suggestions - An array of suggestions that will be used to create decorations.
+   * Each suggestion should have a unique `id` and a `label` that will be displayed in the editor.
+   */
+  constructor(
+    regexp: RegExp,
+    public suggestions: Suggestion[]
+  ) {
+    super({
+      regexp,
+      decoration: (match) => this.#decoration(match),
+    })
+  }
+
+  #decoration(match: RegExpExecArray): Decoration {
+    const label = match[1]
+    const suggestion = this.suggestions.find((s) => s.label === label)
+
+    // If no suggestion is found, create a default one
+    const suggestionData: Suggestion = suggestion || { id: label, label }
+
+    return Decoration.replace({
+      widget: new ChipWidget(suggestionData),
+    })
+  }
+}

package/src/elements/code-editor/internals/types.ts

@@ -0,0 +1,54 @@
+export interface FunctionSchema {
+  /** Unique identifier for the function */
+  id: string
+  /** Function name */
+  name: string
+  /** Function description */
+  description?: string
+  /** Function parameters */
+  parameters?: FunctionParameter[]
+  /** Return type description */
+  returns?: string
+  /** Additional metadata */
+  metadata?: Record<string, unknown>
+}
+
+export interface FunctionParameter {
+  /** Parameter name */
+  name: string
+  /** Parameter type */
+  type: string
+  /** Parameter description */
+  description?: string
+  /** Whether parameter is required */
+  required?: boolean
+  /** Default value */
+  defaultValue?: unknown
+}
+
+export interface Suggestion {
+  /** Unique identifier for the suggestion */
+  id: string
+  /** Main label displayed */
+  label: string
+  /** Supporting description text */
+  description?: string
+  /** Suffix text (e.g., type, category) */
+  suffix?: string
+  /** Additional data associated with the suggestion */
+  data?: Record<string, unknown>
+}
+
+export interface FunctionInsertEvent {
+  /** The inserted function schema */
+  functionSchema: FunctionSchema
+  /** The position where the function was inserted */
+  position: number
+}
+
+export interface SuggestionInsertEvent {
+  /** The inserted suggestion */
+  suggestion: Suggestion
+  /** The position where the suggestion was inserted */
+  position: number
+}