@api-client/ui 0.5.15 → 0.5.17

package/demo/elements/code-editor/CodeEditorDemo.ts

@@ -8,6 +8,10 @@ import type {
   SuggestionInsertEvent,
 } from '../../../src/elements/code-editor/code-editor.js'
 import '../../../src/elements/code-editor/code-editor.js'
+import { stringLibrarySchema } from '@pawel-up/jexl/schemas/string.schema.js'
+import { arrayLibrarySchema } from '@pawel-up/jexl/schemas/array.schema.js'
+import { dateLibrarySchema } from '@pawel-up/jexl/schemas/date.schema.js'
+import { mathLibrarySchema } from '@pawel-up/jexl/schemas/math.schema.js'
 
 class CodeEditorDemo extends DemoPage {
   override accessor componentName = 'Code Editor'
@@ -18,75 +22,10 @@ class CodeEditorDemo extends DemoPage {
   @reactive()
   private accessor editorValue = [
     '// Start typing function names or {{ mentions }}',
-    'console.log("Hello, world!")',
     '',
-    '// Try: getData, processData, or @John, @Jane',
-    '// Example: Ask {{John}} about the API design',
-    '// Example: {{Jane}} can review the implementation',
-    '',
-    '"Hello {{John}}! Can you help with the " + getData() + " function?"',
+    '"Hello {{John}}! Can you help with the " + upper() + " function?"',
   ].join('\n')
 
-  private functionSchemas: FunctionSchema[] = [
-    {
-      name: 'getData',
-      description: 'Fetches data from the server',
-      parameters: [
-        {
-          name: 'url',
-          schema: { type: 'string', description: 'The URL to fetch data from' },
-          required: true,
-        },
-        {
-          name: 'options',
-          schema: { type: 'object', description: 'Fetch options' },
-          required: false,
-        },
-      ],
-      returns: {
-        type: 'object',
-        description: 'The fetched data as an object',
-      },
-      category: 'network',
-    },
-    {
-      name: 'processData',
-      description: 'Processes raw data into a usable format',
-      parameters: [
-        {
-          name: 'data',
-          schema: { description: 'Raw data to process' },
-          required: true,
-        },
-        {
-          name: 'transformer',
-          schema: { description: 'Optional transformer function' },
-          required: false,
-        },
-      ],
-      returns: {},
-      category: 'data',
-    },
-    {
-      category: 'validation',
-      name: 'validateInput',
-      description: 'Validates user input against a schema',
-      parameters: [
-        {
-          name: 'input',
-          schema: { type: 'object', description: 'The input to validate' },
-          required: true,
-        },
-        {
-          name: 'schema',
-          schema: { type: 'object', description: 'Validation schema' },
-          required: true,
-        },
-      ],
-      returns: { type: 'object', description: 'Validation result' },
-    },
-  ]
-
   private suggestions: Suggestion[] = [
     {
       id: 'user-john',
@@ -111,6 +50,42 @@ class CodeEditorDemo extends DemoPage {
     },
   ]
 
+  functions: FunctionSchema[] = []
+
+  constructor() {
+    super()
+
+    // Initialize function schemas
+    this.functions = this.createFunctionSchema()
+  }
+
+  /**
+   * Creates a schema for the code-editor functions.
+   * This method is responsible for defining the functions that can be used in the formula,
+   * given the current data type.
+   */
+  createFunctionSchema(): FunctionSchema[] {
+    const result: FunctionSchema[] = []
+
+    for (const func of Object.values(stringLibrarySchema.functions)) {
+      result.push(func)
+    }
+
+    for (const func of Object.values(arrayLibrarySchema.functions)) {
+      result.push(func)
+    }
+
+    for (const func of Object.values(dateLibrarySchema.functions)) {
+      result.push(func)
+    }
+
+    for (const func of Object.values(mathLibrarySchema.functions)) {
+      result.push(func)
+    }
+
+    return result
+  }
+
   private handleFunctionInsert(event: CustomEvent<FunctionInsertEvent>): void {
     const { functionSchema, position } = event.detail
     this.output = `Function inserted: ${functionSchema.name} at position ${position}`
@@ -124,7 +99,12 @@ class CodeEditorDemo extends DemoPage {
   private handleInput(event: Event): void {
     const target = event.target as HTMLElement & { value: string }
     this.editorValue = target.value
-    console.log('Editor input:', new Error().stack)
+  }
+
+  private handleFunctionDocumentation(event: CustomEvent<{ functionSchema: FunctionSchema }>): void {
+    const { functionSchema } = event.detail
+    this.output = `Function documentation requested for: ${functionSchema.name}`
+    console.log('Function documentation:', functionSchema)
   }
 
   private handleChange(event: Event): void {
@@ -145,12 +125,14 @@ class CodeEditorDemo extends DemoPage {
           label="Code Editor"
           supporting-text="Type function names or {{fnName}} to see autocomplete"
           .value=${this.editorValue}
-          .functionSchemas=${this.functionSchemas}
+          .functionSchemas=${this.functions}
           .suggestions=${this.suggestions}
           @function-insert=${this.handleFunctionInsert}
           @suggestion-insert=${this.handleSuggestionInsert}
           @input=${this.handleInput}
           @change=${this.handleChange}
+          show-documentation
+          @function-documentation="${this.handleFunctionDocumentation}"
         ></code-editor>
 
         ${this.output ? html`<p><strong>Output:</strong> ${this.output}</p>` : ''}
@@ -164,7 +146,7 @@ class CodeEditorDemo extends DemoPage {
           label="Dark Theme Editor"
           supporting-text="Dark theme variant"
           .value=${'// Dark theme example\nconst theme = "dark"'}
-          .functionSchemas=${this.functionSchemas}
+          .functionSchemas=${this.functions}
           .suggestions=${this.suggestions}
           dark-theme
         ></code-editor>
@@ -178,7 +160,7 @@ class CodeEditorDemo extends DemoPage {
           label="Disabled Editor"
           supporting-text="This editor is disabled"
           .value=${'// This editor is disabled\nconst readOnly = true'}
-          .functionSchemas=${this.functionSchemas}
+          .functionSchemas=${this.functions}
           .suggestions=${this.suggestions}
           disabled
         ></code-editor>
@@ -192,23 +174,11 @@ class CodeEditorDemo extends DemoPage {
           label="Error Editor"
           supporting-text="This editor has an error"
           .value=${'// This editor has an error\nconst invalid = true'}
-          .functionSchemas=${this.functionSchemas}
+          .functionSchemas=${this.functions}
           .suggestions=${this.suggestions}
           invalid
         ></code-editor>
       </section>
-
-      <section class="demo-section">
-        <h2 class="display-large">Function Schemas</h2>
-        <p>Available function schemas for autocomplete:</p>
-        <pre>${JSON.stringify(this.functionSchemas, null, 2)}</pre>
-      </section>
-
-      <section class="demo-section">
-        <h2 class="display-large">Suggestions</h2>
-        <p>Available suggestions (use @mention syntax):</p>
-        <pre>${JSON.stringify(this.suggestions, null, 2)}</pre>
-      </section>
     `
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",

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

@@ -15,5 +15,10 @@ declare global {
 }
 
 export default CodeEditorElement
-export type { Suggestion, FunctionInsertEvent, SuggestionInsertEvent } from './internals/types.js'
+export type {
+  Suggestion,
+  FunctionInsertEvent,
+  SuggestionInsertEvent,
+  FunctionDocumentationEvent,
+} from './internals/types.js'
 export type { FunctionSchema, FunctionParameter } from '@pawel-up/jexl/schemas/types.js'

package/src/elements/code-editor/internals/{PlaceholderWidget.ts → ChipWidget.ts}

@@ -33,7 +33,7 @@ export class ChipWidget extends WidgetType {
       const pos = view.posAtDOM(wrapper)
       if (pos === null) return
 
-      const originalText = `{{${this.suggestion.label}}}`
+      const originalText = `{{${this.suggestion.id}}}`
       view.dispatch({
         changes: { from: pos, to: pos + originalText.length, insert: '' },
       })

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

@@ -117,8 +117,8 @@ export default css`
     border: none;
   }
 
-  .cm-focused .cm-cursor {
-    border-left-color: var(--md-sys-color-primary);
+  .cm-focused .cm-content[contenteditable='true'] {
+    caret-color: var(--md-sys-color-primary);
   }
 
   ::selection {
@@ -186,6 +186,12 @@ export default css`
     .param-description {
       color: var(--md-sys-color-on-surface-variant);
     }
+
+    .documentation {
+      margin-top: 8px;
+      padding-top: 8px;
+      border-top: 1px solid var(--md-sys-color-outline-variant);
+    }
   }
 
   /* Responsive */

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

@@ -27,9 +27,11 @@ import {
 import type { FunctionSchema } from '@pawel-up/jexl/schemas/types.js'
 import { getTypeStringFromSchema } from '@pawel-up/jexl/schemas/utils.js'
 import { functionLinter } from './Linter.js'
-import type { FunctionInsertEvent, Suggestion, SuggestionInsertEvent } from './types.js'
+import type { FunctionInsertEvent, Suggestion, SuggestionInsertEvent, FunctionDocumentationEvent } from './types.js'
 import { SuggestionMatchDecorator } from './SuggestionMatchDecorator.js'
 
+import '../../../md/button/ui-button.js'
+
 /**
  * A CodeMirror 6 based editor component that supports function autocomplete and suggestion placeholders.
  *
@@ -42,6 +44,7 @@ import { SuggestionMatchDecorator } from './SuggestionMatchDecorator.js'
  *
  * @fires function-insert - When a function is inserted
  * @fires suggestion-insert - When a suggestion is inserted
+ * @fires function-documentation - When documentation is requested for a function
  * @fires input - When the editor content changes
  * @fires change - When the editor loses focus and content has changed
  */
@@ -143,6 +146,12 @@ export default class CodeEditor extends LitElement {
   @property({ type: String })
   accessor language = 'javascript'
 
+  /**
+   * Whether to show documentation links/buttons in function tooltips and autocomplete
+   */
+  @property({ type: Boolean, attribute: 'show-documentation' })
+  accessor showDocumentation = false
+
   @query('.editor-container')
   private accessor editorContainer!: HTMLDivElement
 
@@ -168,12 +177,12 @@ export default class CodeEditor extends LitElement {
    */
   get activeSuggestions(): Suggestion[] {
     const suggestions: Suggestion[] = []
-    const placeholderPattern = /\{\{(\w+)\}\}/g
+    const placeholderPattern = /\{\{([^}]+)\}\}/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())
+      // Find suggestion by id
+      const suggestion = this.suggestions.find((s) => s.id === placeholderText)
       if (suggestion) {
         suggestions.push(suggestion)
       }
@@ -231,6 +240,9 @@ export default class CodeEditor extends LitElement {
         }
         if (update.focusChanged) {
           this.handleFocusChange(update.view.hasFocus)
+        } else if (update.view.hasFocus !== this.isEditorFocus) {
+          // If focus state changed without focusChanged event, update manually
+          this.handleFocusChange(update.view.hasFocus)
         }
       }),
       this.createPlaceholderPlugin(),
@@ -274,7 +286,7 @@ export default class CodeEditor extends LitElement {
    * 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)
+    const placeholderMatcher = new SuggestionMatchDecorator(/\{\{([^}]+)\}\}/g, this.suggestions)
     this.placeholderMatcher = placeholderMatcher
     // This class needs to be defined here to have access to the `placeholderMatcher`
     class AtomicDecorationRange {
@@ -319,7 +331,7 @@ export default class CodeEditor extends LitElement {
       }
 
       // Check if we're typing a suggestion trigger (e.g., {{)
-      const suggestionMatch = textBefore.match(/\{\{(\w*)$/)
+      const suggestionMatch = textBefore.match(/\{\{([^}]*)$/)
       if (suggestionMatch) {
         const prefix = suggestionMatch[1]
         const suggestions = this.suggestions
@@ -342,6 +354,7 @@ export default class CodeEditor extends LitElement {
     const result: Completion = {
       label: schema.name,
       detail: schema.description || '',
+      type: 'function',
       info: () => this.createFunctionInfoElement(schema),
       apply: (view: EditorView, completion: unknown, from: number, to: number) => {
         const functionCall = this.formatFunctionCall(schema)
@@ -361,8 +374,9 @@ export default class CodeEditor extends LitElement {
       label: suggestion.label,
       detail: suggestion.description || '',
       info: suggestion.suffix || '',
+      type: 'variable',
       apply: (view: EditorView, completion: unknown, from: number, to: number) => {
-        const placeholderText = `{{${suggestion.label}}}`
+        const placeholderText = `{{${suggestion.id}}}`
         view.dispatch({
           changes: { from: from - 2, to, insert: placeholderText }, // -2 to include the {{
           selection: { anchor: from - 2 + placeholderText.length },
@@ -403,7 +417,7 @@ export default class CodeEditor extends LitElement {
    * Creates a styled HTML element to display function documentation.
    * This is used for both hover tooltips and autocomplete info panels.
    */
-  private createFunctionInfoElement(fn: FunctionSchema): HTMLElement {
+  protected createFunctionInfoElement(fn: FunctionSchema): HTMLElement {
     const container = document.createElement('div')
     container.className = 'function-info' // for styling
 
@@ -464,6 +478,27 @@ export default class CodeEditor extends LitElement {
       container.appendChild(returnsContainer)
     }
 
+    // Add documentation button if showDocumentation is enabled
+    if (this.showDocumentation) {
+      const docContainer = document.createElement('div')
+      docContainer.className = 'documentation'
+
+      const docButton = document.createElement('ui-button')
+      docButton.type = 'button'
+      docButton.className = 'documentation-button'
+      docButton.textContent = 'Show documentation'
+      docButton.setAttribute('aria-label', `Show documentation for ${fn.name} function`)
+
+      docButton.addEventListener('click', (event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        this.dispatchFunctionDocumentation(fn)
+      })
+
+      docContainer.appendChild(docButton)
+      container.appendChild(docContainer)
+    }
+
     return container
   }
 
@@ -552,6 +587,17 @@ export default class CodeEditor extends LitElement {
     this.dispatchEvent(event)
   }
 
+  /**
+   * Dispatch function documentation event
+   */
+  private dispatchFunctionDocumentation(functionSchema: FunctionSchema): void {
+    const event = new CustomEvent<FunctionDocumentationEvent>('function-documentation', {
+      detail: { functionSchema },
+      bubbles: true,
+    })
+    this.dispatchEvent(event)
+  }
+
   /**
    * Focus the editor
    */

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

@@ -1,6 +1,6 @@
 import { MatchDecorator, Decoration } from '@codemirror/view'
 import type { Suggestion } from './types.js'
-import { ChipWidget } from './PlaceholderWidget.js'
+import { ChipWidget } from './ChipWidget.js'
 
 /**
  * A class that specializes in creating and managing decorations for suggestion matches in a code editor.
@@ -23,12 +23,11 @@ export class SuggestionMatchDecorator extends MatchDecorator {
   }
 
   #decoration(match: RegExpExecArray): Decoration {
-    const label = match[1]
-    const suggestion = this.suggestions.find((s) => s.label === label)
+    const id = match[1]
+    const suggestion = this.suggestions.find((s) => s.id === id)
 
     // If no suggestion is found, create a default one
-    const suggestionData: Suggestion = suggestion || { id: label, label }
-
+    const suggestionData: Suggestion = suggestion || { id, label: id }
     return Decoration.replace({
       widget: new ChipWidget(suggestionData),
     })

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

@@ -26,3 +26,8 @@ export interface SuggestionInsertEvent {
   /** The position where the suggestion was inserted */
   position: number
 }
+
+export interface FunctionDocumentationEvent {
+  /** The function schema for which documentation is requested */
+  functionSchema: FunctionSchema
+}