@api-client/ui 0.5.16 → 0.5.17

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
 
@@ -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(),
@@ -405,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
 
@@ -466,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
   }
 
@@ -554,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/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
+}

package/test/elements/autocomplete/autocomplete-input.spec.ts

@@ -1,5 +1,4 @@
-/* eslint-disable @typescript-eslint/no-unused-expressions */
-import { fixture, expect, html, oneEvent, nextFrame, aTimeout, assert } from '@open-wc/testing'
+import { fixture, assert, html, oneEvent, nextFrame, aTimeout } from '@open-wc/testing'
 import sinon from 'sinon'
 
 import { AutocompleteInput } from '../../../src/elements/autocomplete/autocomplete-input.js'
@@ -67,10 +66,10 @@ describe('AutocompleteInput', () => {
       const input = getSlottedInput(el)
       const suggestions = getSlottedSuggestions(el)
 
-      expect(input).to.exist
-      expect(input?.id).to.equal('test-input')
-      expect(suggestions).to.exist
-      expect(suggestions?.popover).to.equal('manual')
+      assert.ok(input)
+      assert.equal(input?.id, 'test-input')
+      assert.ok(suggestions)
+      assert.equal(suggestions?.popover, 'manual')
     })
 
     it('generates an ID for the input if not provided and sets up anchor names', async () => {
@@ -86,20 +85,20 @@ describe('AutocompleteInput', () => {
       const input = getSlottedInput(el)!
       const suggestions = getSlottedSuggestions(el)!
 
-      expect(input.id).to.match(/^autocomplete-input-/)
+      assert.match(input.id, /^autocomplete-input-/)
       // @ts-expect-error _inputId is a protected member
       const internalInputId = el.inputId
-      expect(input.style.getPropertyValue('anchor-name')).to.equal(`--${internalInputId}`, 'input has anchor name')
+      assert.equal(input.style.getPropertyValue('anchor-name'), `--${internalInputId}`, 'input has anchor name')
       const anchorValue = getComputedStyle(suggestions).getPropertyValue('position-anchor')
-      expect(anchorValue).to.equal(`--${internalInputId}`, 'suggestions element has position-anchor')
+      assert.equal(anchorValue, `--${internalInputId}`, 'suggestions element has position-anchor')
     })
 
     it('popover is initially closed', async () => {
       const el = await basicFixture()
       await el.updateComplete
       const suggestions = getSlottedSuggestions(el)
-      expect(suggestions?.matches(':popover-open')).to.be.false
-      expect(el.opened).to.be.false
+      assert.isFalse(suggestions?.matches(':popover-open'))
+      assert.isFalse(el.opened)
     })
   })
 
@@ -113,8 +112,8 @@ describe('AutocompleteInput', () => {
       input.focus()
       await nextFrame() // Allow focus event to propagate and popover to open
 
-      expect(suggestions.matches(':popover-open')).to.be.true
-      expect(el.opened).to.be.true
+      assert.isTrue(suggestions.matches(':popover-open'))
+      assert.isTrue(el.opened)
     })
 
     it('does not open on input focus without suggestions', async () => {
@@ -126,7 +125,7 @@ describe('AutocompleteInput', () => {
       input.focus()
       await nextFrame()
 
-      expect(suggestions.matches(':popover-open')).to.be.false
+      assert.isFalse(suggestions.matches(':popover-open'))
     })
 
     it('does not open on input focus if suggestions element is missing', async () => {
@@ -137,7 +136,7 @@ describe('AutocompleteInput', () => {
       input.focus()
       await nextFrame()
       // No suggestions ref, so opened should be false
-      expect(el.opened).to.be.false
+      assert.isFalse(el.opened)
     })
 
     it('closes on input blur', async () => {
@@ -148,15 +147,15 @@ describe('AutocompleteInput', () => {
 
       input.focus()
       await nextFrame()
-      expect(suggestions.matches(':popover-open')).to.be.true
+      assert.isTrue(suggestions.matches(':popover-open'))
 
       input.blur()
       // Blur handler uses requestAnimationFrame
       await aTimeout(0) // Wait for rAF
       await nextFrame() // Wait for potential re-render
 
-      expect(suggestions.matches(':popover-open')).to.be.false
-      expect(el.opened).to.be.false
+      assert.isFalse(suggestions.matches(':popover-open'))
+      assert.isFalse(el.opened)
     })
 
     it('closes on Escape key', async () => {
@@ -167,12 +166,12 @@ describe('AutocompleteInput', () => {
 
       input.focus()
       await nextFrame()
-      expect(suggestions.matches(':popover-open')).to.be.true
+      assert.isTrue(suggestions.matches(':popover-open'))
 
       input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(suggestions.matches(':popover-open')).to.be.false
+      assert.isFalse(suggestions.matches(':popover-open'))
     })
   })
 
@@ -195,7 +194,7 @@ describe('AutocompleteInput', () => {
     it('shows all items for empty query', () => {
       input.value = ''
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
-      items.forEach((item) => expect(item.hidden).to.be.false)
+      items.forEach((item) => assert.isFalse(item.hidden))
     })
 
     it('filters items based on data-value', async () => {
@@ -203,9 +202,9 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(items[0].hidden).to.be.false // Apple
-      expect(items[1].hidden).to.be.true // Banana
-      expect(items[2].hidden).to.be.true // Cherry
+      assert.isFalse(items[0].hidden) // Apple
+      assert.isTrue(items[1].hidden) // Banana
+      assert.isTrue(items[2].hidden) // Cherry
     })
 
     it('filters items based on textContent if data-value is not present or does not match', async () => {
@@ -218,9 +217,9 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(items[0].hidden).to.be.false // Pineapple (via textContent)
-      expect(items[1].hidden).to.be.true // Banana
-      expect(items[2].hidden).to.be.true // Cherry
+      assert.isFalse(items[0].hidden) // Pineapple (via textContent)
+      assert.isTrue(items[1].hidden) // Banana
+      assert.isTrue(items[2].hidden) // Cherry
     })
 
     it('filters items based on data-index fields', async () => {
@@ -228,9 +227,9 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(items[0].hidden).to.be.true // Apple
-      expect(items[1].hidden).to.be.true // Banana
-      expect(items[2].hidden).to.be.false // Cherry
+      assert.isTrue(items[0].hidden) // Apple
+      assert.isTrue(items[1].hidden) // Banana
+      assert.isFalse(items[2].hidden) // Cherry
     })
 
     it('is case-insensitive', async () => {
@@ -238,9 +237,9 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(items[0].hidden).to.be.true // Apple
-      expect(items[1].hidden).to.be.false // Banana
-      expect(items[2].hidden).to.be.true // Cherry
+      assert.isTrue(items[0].hidden) // Apple
+      assert.isFalse(items[1].hidden) // Banana
+      assert.isTrue(items[2].hidden) // Cherry
     })
 
     it('closes popover if no items match', async () => {
@@ -249,8 +248,8 @@ describe('AutocompleteInput', () => {
       await nextFrame()
       await aTimeout(0) // filterSuggestions might call closeSuggestions, which might be async
 
-      items.forEach((item) => expect(item.hidden).to.be.true)
-      expect(suggestionsBox.matches(':popover-open')).to.be.false
+      items.forEach((item) => assert.isTrue(item.hidden))
+      assert.isFalse(suggestionsBox.matches(':popover-open'))
     })
   })
 
@@ -258,6 +257,7 @@ describe('AutocompleteInput', () => {
     let el: AutocompleteInput
     let input: HTMLInputElement
     let suggestionsBox: MdListbox
+    let notifySelectSpy: sinon.SinonSpy
 
     beforeEach(async () => {
       el = await basicFixture()
@@ -268,7 +268,7 @@ describe('AutocompleteInput', () => {
       // We spy on its methods.
       sinon.spy(suggestionsBox, 'highlightNext')
       sinon.spy(suggestionsBox, 'highlightPrevious')
-      sinon.spy(suggestionsBox, 'notifySelect')
+      notifySelectSpy = sinon.spy(suggestionsBox, 'notifySelect')
     })
 
     afterEach(() => {
@@ -276,14 +276,14 @@ describe('AutocompleteInput', () => {
     })
 
     it('ArrowDown highlights next item and opens popover if closed', async () => {
-      expect(suggestionsBox.matches(':popover-open')).to.be.false
+      assert.isFalse(suggestionsBox.matches(':popover-open'))
       input.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true, composed: true }))
       // handleKeydown uses rAF if popover was closed
       await aTimeout(0) // for rAF
       await nextFrame() // for popover to open and highlight
 
-      expect(suggestionsBox.matches(':popover-open')).to.be.true
-      expect(suggestionsBox.highlightNext).to.have.been.calledOnce
+      assert.isTrue(suggestionsBox.matches(':popover-open'))
+      assert.isTrue((suggestionsBox.highlightNext as sinon.SinonSpy).calledOnce)
     })
 
     it('ArrowUp highlights previous item', async () => {
@@ -291,7 +291,7 @@ describe('AutocompleteInput', () => {
       await nextFrame()
       input.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true, composed: true }))
       await nextFrame()
-      expect(suggestionsBox.highlightPrevious).to.have.been.calledOnce
+      assert.isTrue((suggestionsBox.highlightPrevious as sinon.SinonSpy).calledOnce)
     })
 
     it('Enter selects highlighted item and dispatches event', async () => {
@@ -307,13 +307,14 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, composed: true }))
 
       const event = await eventPromise
-      expect(suggestionsBox.notifySelect).to.have.been.calledWith(items[0])
-      expect(event.detail.item).to.equal(items[0])
-      expect(suggestionsBox.matches(':popover-open')).to.be.false // Popover should close
+
+      assert.isTrue((suggestionsBox.notifySelect as sinon.SinonSpy).calledWith(items[0]))
+      assert.equal(event.detail.item, items[0])
+      assert.isFalse(suggestionsBox.matches(':popover-open')) // Popover should close
     })
 
     it('Enter does nothing if popover closed or no item highlighted', async () => {
-      expect(suggestionsBox.matches(':popover-open')).to.be.false
+      assert.isFalse(suggestionsBox.matches(':popover-open'))
       suggestionsBox.highlightListItem = null // Ensure no item is highlighted
 
       const spy = sinon.spy()
@@ -322,8 +323,8 @@ describe('AutocompleteInput', () => {
       input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, composed: true }))
       await nextFrame()
 
-      expect(spy).not.to.have.been.called
-      expect(suggestionsBox.notifySelect).not.to.have.been.called
+      assert.isFalse(spy.called)
+      assert.isFalse(notifySelectSpy.called)
     })
   })
 
@@ -351,8 +352,8 @@ describe('AutocompleteInput', () => {
       )
 
       const event = await eventPromise
-      expect(event.detail.item).to.equal(items[1])
-      expect(suggestionsBox.matches(':popover-open')).to.be.false // Popover should close
+      assert.equal(event.detail.item, items[1])
+      assert.isFalse(suggestionsBox.matches(':popover-open')) // Popover should close
     })
   })
 
@@ -369,8 +370,8 @@ describe('AutocompleteInput', () => {
       await el.updateComplete // Ensure component processes the new input
 
       const slottedInput = getSlottedInput(el)
-      expect(slottedInput).to.equal(inputEl)
-      expect(inputEl.id).to.match(/^autocomplete-input-/)
+      assert.equal(slottedInput, inputEl)
+      assert.match(inputEl.id, /^autocomplete-input-/)
     })
 
     it('handles dynamically added suggestions', async () => {
@@ -387,10 +388,10 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
 
       const slottedSuggestions = getSlottedSuggestions(el)
-      expect(slottedSuggestions).to.equal(suggestionsEl)
-      expect(suggestionsEl.popover).to.equal('manual')
+      assert.equal(slottedSuggestions, suggestionsEl)
+      assert.equal(suggestionsEl.popover, 'manual')
       const anchorValue = getComputedStyle(suggestionsEl).getPropertyValue('position-anchor')
-      expect(anchorValue).to.equal(`--${input.id}`)
+      assert.equal(anchorValue, `--${input.id}`)
     })
 
     it('re-filters when suggestion items change (via itemschange event)', async () => {
@@ -404,8 +405,8 @@ describe('AutocompleteInput', () => {
       input.value = 'ban' // Should show "Banana"
       input.dispatchEvent(new Event('input', { bubbles: true, composed: true }))
       await nextFrame()
-      expect(items[0].hidden).to.be.true // Apple
-      expect(items[1].hidden).to.be.false // Banana
+      assert.isTrue(items[0].hidden) // Apple
+      assert.isFalse(items[1].hidden) // Banana
 
       // Add a new item that matches "ban"
       const newItem = document.createElement('ui-list-item') as MdListItem
@@ -418,9 +419,9 @@ describe('AutocompleteInput', () => {
       await nextFrame() // Allow handler to run
 
       items = getSuggestionItems(suggestionsBox) // Re-fetch items
-      expect(items.find((i) => i.dataset.value === 'bandana')?.hidden).to.be.false
-      expect(items.find((i) => i.dataset.value === 'banana')?.hidden).to.be.false
-      expect(items.find((i) => i.dataset.value === 'apple')?.hidden).to.be.true
+      assert.isFalse(items.find((i) => i.dataset.value === 'bandana')?.hidden)
+      assert.isFalse(items.find((i) => i.dataset.value === 'banana')?.hidden)
+      assert.isTrue(items.find((i) => i.dataset.value === 'apple')?.hidden)
     })
   })
 
@@ -431,18 +432,18 @@ describe('AutocompleteInput', () => {
       const input = getSlottedInput(el)!
       const suggestions = getSlottedSuggestions(el)!
 
-      expect(el.opened).to.be.false
+      assert.isFalse(el.opened)
 
       input.focus()
       await nextFrame()
-      expect(el.opened).to.be.true
-      expect(suggestions.matches(':popover-open')).to.be.true
+      assert.isTrue(el.opened)
+      assert.isTrue(suggestions.matches(':popover-open'))
 
       // @ts-expect-error protected method
       el.closeSuggestions()
       await nextFrame()
-      expect(el.opened).to.be.false
-      expect(suggestions.matches(':popover-open')).to.be.false
+      assert.isFalse(el.opened)
+      assert.isFalse(suggestions.matches(':popover-open'))
     })
   })
 
@@ -503,7 +504,7 @@ describe('AutocompleteInput', () => {
       await el.updateComplete // For positionArea state change and re-render
       await nextFrame() // For DOM to reflect changes
 
-      expect(el.positionArea).to.equal('bottom')
+      assert.equal(el.positionArea, 'bottom')
     })
 
     it('positions at top when insufficient space below but sufficient space above', async () => {
@@ -516,7 +517,7 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
       await nextFrame()
 
-      expect(el.positionArea).to.equal('top')
+      assert.equal(el.positionArea, 'top')
     })
 
     it('positions at top when insufficient space below and more space above', async () => {
@@ -535,7 +536,7 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
       await nextFrame()
 
-      expect(el.positionArea).to.equal('top')
+      assert.equal(el.positionArea, 'top')
     })
 
     it('positions at bottom when insufficient space below and also insufficient (or less) space above', async () => {
@@ -552,7 +553,7 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
       await nextFrame()
 
-      expect(el.positionArea).to.equal('bottom')
+      assert.equal(el.positionArea, 'bottom')
     })
 
     it('uses fallback threshold of 150px if popover scrollHeight is 0', async () => {
@@ -574,7 +575,7 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
       await nextFrame()
 
-      expect(el.positionArea).to.equal('top')
+      assert.equal(el.positionArea, 'top')
       scrollHeightStub.restore()
     })
 
@@ -603,8 +604,8 @@ describe('AutocompleteInput', () => {
       await el.updateComplete
       await nextFrame()
 
-      expect(el.positionArea).to.equal('top')
-      expect(getBoundingClientRectStub.called).to.be.true
+      assert.equal(el.positionArea, 'top')
+      assert.isTrue(getBoundingClientRectStub.called)
     })
   })