@api-client/ui 0.5.10 → 0.5.12

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

@@ -0,0 +1,595 @@
+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 { EditorState, Extension } from '@codemirror/state'
+import { autocompletion, CompletionContext, CompletionResult, CompletionSource } from '@codemirror/autocomplete'
+import { javascript } from '@codemirror/lang-javascript'
+import { syntaxHighlighting, defaultHighlightStyle } from '@codemirror/language'
+import { oneDark } from '@codemirror/theme-one-dark'
+import { keymap } from '@codemirror/view'
+import { defaultKeymap } from '@codemirror/commands'
+import {
+  EditorView,
+  MatchDecorator,
+  Decoration,
+  DecorationSet,
+  ViewPlugin,
+  ViewUpdate,
+  WidgetType,
+} 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
+    }),
+})
+
+/**
+ * A CodeMirror 6 based editor component that supports function autocomplete and suggestion placeholders.
+ *
+ * Features:
+ * - Dynamic function schema loading
+ * - Autocomplete for functions and suggestions
+ * - Suggestion placeholders with double curly braces ({{suggestion}})
+ * - Keyboard navigation
+ * - Accessibility support
+ *
+ * @fires function-insert - When a function is inserted
+ * @fires suggestion-insert - When a suggestion is inserted
+ * @fires input - When the editor content changes
+ * @fires change - When the editor loses focus and content has changed
+ */
+export default class CodeEditor extends LitElement {
+  /**
+   * Shadow root configuration for the component.
+   * Uses 'open' mode for accessibility and delegates focus to enable proper focus management.
+   */
+  static override shadowRootOptions: ShadowRootInit = {
+    mode: 'open',
+    delegatesFocus: true,
+  }
+
+  /**
+   * The label text displayed as placeholder/floating label
+   */
+  @property({ type: String })
+  accessor label = ''
+
+  /**
+   * Supporting text displayed below the editor
+   */
+  @property({ type: String, attribute: 'supporting-text' })
+  accessor supportingText = ''
+
+  /**
+   * Whether the component is disabled
+   */
+  @property({ type: Boolean, reflect: true })
+  accessor disabled = false
+
+  /**
+   * Whether the component is in an invalid state
+   */
+  @property({ type: Boolean, reflect: true })
+  accessor invalid = false
+
+  /**
+   * The name attribute for form integration
+   */
+  @property({ type: String })
+  accessor name = ''
+
+  /**
+   * Whether the input is required
+   */
+  @property({ type: Boolean })
+  accessor required = false
+
+  /**
+   * Placeholder text shown when editor is empty
+   */
+  @property({ type: String })
+  accessor placeholder = ''
+
+  /**
+   * The editor content value
+   */
+  @property({ type: String })
+  accessor value = ''
+
+  /**
+   * Available function schemas for autocomplete
+   */
+  @property({ type: Array, attribute: false })
+  accessor functionSchemas: FunctionSchema[] = []
+
+  /**
+   * Available suggestions for autocomplete
+   */
+  @property({ type: Array, attribute: false })
+  accessor suggestions: Suggestion[] = []
+
+  /**
+   * Whether to use dark theme
+   */
+  @property({ type: Boolean, attribute: 'dark-theme' })
+  accessor darkTheme = false
+
+  /**
+   * Programming language for syntax highlighting
+   */
+  @property({ type: String })
+  accessor language = 'javascript'
+
+  @query('.editor-container')
+  private accessor editorContainer!: HTMLDivElement
+
+  @state()
+  private accessor hasContent = false
+
+  @state()
+  private accessor isEditorFocus = false
+
+  private editorView?: EditorView
+  private suggestionMap = new Map<string, Suggestion>()
+  private functionMap = new Map<string, FunctionSchema>()
+  private _previousValue = ''
+
+  /**
+   * Get all suggestions (placeholders) currently in the editor
+   */
+  get activeSuggestions(): Suggestion[] {
+    const suggestions: Suggestion[] = []
+    const placeholderPattern = /\{\{(\w+)\}\}/g
+    let match: RegExpExecArray | null
+    while ((match = placeholderPattern.exec(this.value)) !== null) {
+      const placeholderText = match[1]
+      // Find suggestion by label
+      const suggestion = this.suggestions.find((s) => s.label.toLowerCase() === placeholderText.toLowerCase())
+      if (suggestion) {
+        suggestions.push(suggestion)
+      }
+    }
+    return suggestions
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.setupSuggestionMaps()
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback()
+    this.editorView?.destroy()
+  }
+
+  override firstUpdated(): void {
+    this.initializeCodeMirror()
+    this.updateEditorContent()
+  }
+
+  override willUpdate(changedProperties: PropertyValues): void {
+    super.willUpdate(changedProperties)
+
+    if (changedProperties.has('suggestions') || changedProperties.has('functionSchemas')) {
+      this.setupSuggestionMaps()
+    }
+
+    if (changedProperties.has('value') && this.editorView) {
+      this.updateEditorContent()
+    }
+
+    if (changedProperties.has('disabled')) {
+      this.updateEditorState()
+    }
+  }
+
+  /**
+   * Initialize CodeMirror editor with extensions
+   */
+  private initializeCodeMirror(): void {
+    const extensions: Extension[] = [
+      keymap.of(defaultKeymap),
+      syntaxHighlighting(defaultHighlightStyle),
+      autocompletion({
+        override: [this.createCompletionSource()],
+        activateOnTyping: true,
+        maxRenderedOptions: 10,
+      }),
+      EditorView.updateListener.of((update: ViewUpdate) => {
+        if (update.docChanged) {
+          this.handleEditorChange()
+        }
+        if (update.focusChanged) {
+          this.handleFocusChange(update.view.hasFocus)
+        }
+      }),
+      placeholders,
+      // linter((view) => functionLinter(view as unknown as EditorView, this.functionSchemas)),
+    ]
+
+    // Add language support
+    if (this.language === 'javascript') {
+      extensions.push(javascript())
+    }
+
+    // Add theme
+    if (this.darkTheme) {
+      extensions.push(oneDark)
+    }
+
+    // Add placeholder
+    if (this.placeholder) {
+      extensions.push(
+        EditorView.contentAttributes.of({
+          'aria-placeholder': this.placeholder,
+        })
+      )
+    }
+
+    const state = EditorState.create({
+      doc: this.value,
+      extensions,
+    })
+
+    this.editorView = new EditorView({
+      state,
+      parent: this.editorContainer,
+    })
+  }
+
+  /**
+   * Create completion source for functions and suggestions
+   */
+  private createCompletionSource(): CompletionSource {
+    return (context: CompletionContext): CompletionResult | null => {
+      const { pos } = context
+      const line = context.state.doc.lineAt(pos)
+      const textBefore = line.text.slice(0, pos - line.from)
+
+      // Check if we're typing a function name
+      const functionMatch = textBefore.match(/(\w+)$/)
+      if (functionMatch) {
+        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)
+            },
+          }))
+
+        if (functions.length > 0) {
+          return {
+            from: pos - prefix.length,
+            options: functions,
+          }
+        }
+      }
+
+      // Check if we're typing a suggestion trigger (e.g., {{)
+      const suggestionMatch = textBefore.match(/\{\{(\w*)$/)
+      if (suggestionMatch) {
+        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)
+            },
+          }))
+
+        if (suggestions.length > 0) {
+          return {
+            from: pos - prefix.length,
+            options: suggestions,
+          }
+        }
+      }
+
+      return null
+    }
+  }
+
+  /**
+   * Format function information for autocomplete
+   */
+  private formatFunctionInfo(fn: FunctionSchema): string {
+    let info = fn.description || ''
+    if (fn.parameters && fn.parameters.length > 0) {
+      info += '\n\nParameters:\n'
+      fn.parameters.forEach((param) => {
+        info += `• ${param.name}: ${param.type}`
+        if (param.description) {
+          info += ` - ${param.description}`
+        }
+        info += '\n'
+      })
+    }
+    if (fn.returns) {
+      info += `\nReturns: ${fn.returns}`
+    }
+    return info
+  }
+
+  /**
+   * Format function call with parameters
+   */
+  private formatFunctionCall(fn: FunctionSchema): string {
+    if (!fn.parameters || fn.parameters.length === 0) {
+      return `${fn.name}()`
+    }
+
+    const params = fn.parameters
+      .map((param) => {
+        if (param.required) {
+          return param.name
+        }
+        return `${param.name}?`
+      })
+      .join(', ')
+
+    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
+   */
+  private updateEditorContent(): void {
+    if (!this.editorView) return
+
+    const currentValue = this.editorView.state.doc.toString()
+    if (currentValue !== this.value) {
+      this.editorView.dispatch({
+        changes: {
+          from: 0,
+          to: this.editorView.state.doc.length,
+          insert: this.value,
+        },
+      })
+    }
+  }
+
+  /**
+   * Update editor state (e.g., disabled state)
+   */
+  private updateEditorState(): void {
+    if (!this.editorView) return
+
+    // For now, we'll handle disabled state differently
+    // CodeMirror 6 doesn't use reconfigure for editable
+    if (this.disabled) {
+      this.editorView.contentDOM.setAttribute('contenteditable', 'false')
+    } else {
+      this.editorView.contentDOM.setAttribute('contenteditable', 'true')
+    }
+  }
+
+  /**
+   * Handle editor content change
+   */
+  private handleEditorChange(): void {
+    if (!this.editorView) return
+
+    const newValue = this.editorView.state.doc.toString()
+    if (newValue !== this._previousValue) {
+      this._previousValue = newValue
+      this.value = newValue
+      this.hasContent = newValue.length > 0
+
+      this.dispatchEvent(new Event('input', { bubbles: true }))
+    }
+  }
+
+  /**
+   * Handle focus change
+   */
+  private handleFocusChange(hasFocus: boolean): void {
+    this.isEditorFocus = hasFocus
+
+    if (!hasFocus && this.value !== this._previousValue) {
+      this.dispatchEvent(new Event('change', { bubbles: true }))
+    }
+  }
+
+  /**
+   * Dispatch function insert event
+   */
+  private dispatchFunctionInsert(functionSchema: FunctionSchema, position: number): void {
+    const event = new CustomEvent<FunctionInsertEvent>('function-insert', {
+      detail: { functionSchema, position },
+      bubbles: true,
+    })
+    this.dispatchEvent(event)
+  }
+
+  /**
+   * Dispatch suggestion insert event
+   */
+  private dispatchSuggestionInsert(suggestion: Suggestion, position: number): void {
+    const event = new CustomEvent<SuggestionInsertEvent>('suggestion-insert', {
+      detail: { suggestion, position },
+      bubbles: true,
+    })
+    this.dispatchEvent(event)
+  }
+
+  /**
+   * Focus the editor
+   */
+  override focus(): void {
+    this.editorView?.focus()
+  }
+
+  /**
+   * Get the editor's current selection
+   */
+  getSelection(): { from: number; to: number } | null {
+    if (!this.editorView) return null
+    const { from, to } = this.editorView.state.selection.main
+    return { from, to }
+  }
+
+  /**
+   * Insert text at the current cursor position
+   */
+  insertText(text: string): void {
+    if (!this.editorView) return
+
+    const { from, to } = this.editorView.state.selection.main
+    this.editorView.dispatch({
+      changes: { from, to, insert: text },
+      selection: { anchor: from + text.length },
+    })
+  }
+
+  override render(): TemplateResult {
+    const hasLabel = !!this.label
+    const hasSupportingText = !!this.supportingText
+
+    return html`
+      <div class="surface ${classMap({ 'has-focus': this.isEditorFocus, 'invalid': this.invalid })}">
+        <div class="content">
+          ${hasLabel ? html`<div class="label">${this.label}</div>` : nothing}
+
+          <div class="editor-container" part="editor"></div>
+        </div>
+
+        ${hasSupportingText ? html`<div class="supporting-text">${this.supportingText}</div>` : nothing}
+      </div>
+    `
+  }
+}

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

@@ -0,0 +1,87 @@
+import type { Diagnostic } from '@codemirror/lint'
+import type { EditorView } from '@codemirror/view'
+import Element from './CodeEditor.js'
+
+export function functionLinter(view: EditorView, element: Element): readonly Diagnostic[] {
+  const diagnostics: Diagnostic[] = []
+  const doc = view.state.doc
+  const text = doc.toString()
+
+  const functions = element.functionSchemas
+  if (!functions || functions.length === 0) {
+    return diagnostics
+  }
+
+  // Regular expression to match function calls like functionName(args)
+  const functionCallRegex = /(\w+)\s*\(/g
+  let match: RegExpExecArray | null
+
+  while ((match = functionCallRegex.exec(text)) !== null) {
+    const functionName = match[1]
+    const startPos = match.index
+    const endPos = startPos + functionName.length
+
+    // Check if this function exists in our schemas
+    const functionExists = functions.some((schema) => schema.name === functionName)
+
+    if (!functionExists) {
+      diagnostics.push({
+        from: startPos,
+        to: endPos,
+        severity: 'error',
+        message: `Unknown function "${functionName}". Only functions defined in the schema are allowed.`,
+        actions: [
+          {
+            name: 'View available functions',
+            apply: () => {
+              // This could trigger showing a help dialog or documentation
+              element.dispatchEvent(
+                new CustomEvent('show-available-functions', {
+                  detail: { availableFunctions: functions.map((s) => s.name) },
+                  bubbles: true,
+                })
+              )
+            },
+          },
+        ],
+      })
+    } else {
+      // Optional: Validate function usage (parameters, etc.)
+      const fn = functions.find((schema) => schema.name === functionName)
+
+      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 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}`,
+            })
+          }
+        }
+      }
+    }
+  }
+
+  return diagnostics
+}

package/src/elements/code-editor/ui-code-editor.ts

@@ -0,0 +1,24 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internals/CodeEditor.js'
+import styles from './internals/CodeEditor.styles.js'
+
+@customElement('code-editor')
+export class CodeEditorElement extends Element {
+  static override styles: CSSResultOrNative[] = [styles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'code-editor': CodeEditorElement
+  }
+}
+
+export default CodeEditorElement
+export type {
+  FunctionSchema,
+  FunctionParameter,
+  Suggestion,
+  FunctionInsertEvent,
+  SuggestionInsertEvent,
+} from './internals/CodeEditor.js'