@api-client/ui 0.5.0 → 0.5.2

package/test/helpers/TestUtils.ts

@@ -0,0 +1,243 @@
+/**
+ * Extended test utilities for the UI component library.
+ * Provides Jest-like matchers and additional testing helpers.
+ */
+
+import { expect } from '@open-wc/testing'
+
+/**
+ * Custom matchers for better test assertions
+ */
+export const customMatchers = {
+  /**
+   * Check if an element has specific CSS classes
+   */
+  toHaveClasses(received: Element, ...classes: string[]) {
+    const classList = Array.from(received.classList)
+    const missing = classes.filter((cls) => !classList.includes(cls))
+
+    if (missing.length === 0) {
+      return {
+        message: () => `Expected element not to have classes: ${classes.join(', ')}`,
+        pass: true,
+      }
+    } else {
+      return {
+        message: () => `Expected element to have classes: ${missing.join(', ')}`,
+        pass: false,
+      }
+    }
+  },
+
+  /**
+   * Check if an element is visible (not hidden by CSS)
+   */
+  toBeVisible(received: Element) {
+    const style = window.getComputedStyle(received)
+    const isVisible = style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+
+    if (isVisible) {
+      return {
+        message: () => 'Expected element to be hidden',
+        pass: true,
+      }
+    } else {
+      return {
+        message: () => 'Expected element to be visible',
+        pass: false,
+      }
+    }
+  },
+
+  /**
+   * Check if an element has a specific attribute value
+   */
+  toHaveAttribute(received: Element, attribute: string, value?: string) {
+    const hasAttribute = received.hasAttribute(attribute)
+
+    if (!hasAttribute) {
+      return {
+        message: () => `Expected element to have attribute "${attribute}"`,
+        pass: false,
+      }
+    }
+
+    if (value !== undefined) {
+      const actualValue = received.getAttribute(attribute)
+      if (actualValue !== value) {
+        return {
+          message: () => `Expected attribute "${attribute}" to be "${value}", but got "${actualValue}"`,
+          pass: false,
+        }
+      }
+    }
+
+    return {
+      message: () => `Expected element not to have attribute "${attribute}"${value ? ` with value "${value}"` : ''}`,
+      pass: true,
+    }
+  },
+
+  /**
+   * Helper to demonstrate proper DOM element comparison
+   * Note: Always use assert.dom.equal() for DOM element comparison, not assert.equal()
+   */
+  domElementsEqual(actual: Element, expected: Element): boolean {
+    // This is just a helper - in actual tests, use assert.dom.equal(actual, expected)
+    return actual === expected && actual.isEqualNode(expected)
+  },
+}
+
+/**
+ * Test factory functions for common test scenarios
+ */
+export const testFactory = {
+  /**
+   * Create a test suite for a custom element
+   */
+  createElementTestSuite(elementName: string, importPath: string) {
+    return {
+      async setup() {
+        await import(importPath)
+      },
+
+      async createElement(attributes: Record<string, string> = {}, content = '') {
+        const attrs = Object.entries(attributes)
+          .map(([key, value]) => `${key}="${value}"`)
+          .join(' ')
+
+        const element = document.createElement('div')
+        element.innerHTML = `<${elementName} ${attrs}>${content}</${elementName}>`
+        document.body.appendChild(element)
+
+        return element.firstElementChild as HTMLElement
+      },
+
+      cleanup() {
+        document.body.innerHTML = ''
+      },
+    }
+  },
+
+  /**
+   * Create a test data factory
+   */
+  createDataFactory<T>(defaults: T) {
+    return (overrides: Partial<T> = {}): T => ({
+      ...defaults,
+      ...overrides,
+    })
+  },
+}
+
+/**
+ * Async test helpers
+ */
+export const asyncHelpers = {
+  /**
+   * Wait for multiple conditions to be true
+   */
+  async waitForAll(conditions: (() => boolean)[], timeout = 5000): Promise<void> {
+    const promises = conditions.map((condition) => window.testUtils.waitForCondition(condition, timeout))
+    await Promise.all(promises)
+  },
+
+  /**
+   * Wait for any of multiple conditions to be true
+   */
+  async waitForAny(conditions: (() => boolean)[], timeout = 5000): Promise<number> {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now()
+      let resolved = false
+
+      function checkConditions() {
+        if (resolved) return
+
+        for (let i = 0; i < conditions.length; i++) {
+          try {
+            if (conditions[i]()) {
+              resolved = true
+              resolve(i)
+              return
+            }
+          } catch {
+            // Continue checking other conditions
+          }
+        }
+
+        if (Date.now() - startTime > timeout) {
+          resolved = true
+          reject(new Error(`None of the conditions met within ${timeout}ms`))
+          return
+        }
+
+        setTimeout(checkConditions, 50)
+      }
+
+      checkConditions()
+    })
+  },
+
+  /**
+   * Retry an async operation with exponential backoff
+   */
+  async retry<T>(operation: () => Promise<T>, maxAttempts = 3, baseDelay = 100): Promise<T> {
+    let lastError: Error
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await operation()
+      } catch (error) {
+        lastError = error as Error
+
+        if (attempt === maxAttempts) {
+          throw lastError
+        }
+
+        const delay = baseDelay * Math.pow(2, attempt - 1)
+        await new Promise((resolve) => setTimeout(resolve, delay))
+      }
+    }
+
+    throw lastError!
+  },
+}
+
+/**
+ * Performance testing utilities
+ */
+export const performanceHelpers = {
+  /**
+   * Measure the execution time of a function
+   */
+  async measureTime<T>(fn: () => Promise<T> | T): Promise<{ result: T; duration: number }> {
+    const start = performance.now()
+    const result = await fn()
+    const duration = performance.now() - start
+
+    return { result, duration }
+  },
+
+  /**
+   * Assert that an operation completes within a time limit
+   */
+  async expectWithinTime<T>(operation: () => Promise<T> | T, maxDuration: number, message?: string): Promise<T> {
+    const { result, duration } = await this.measureTime(operation)
+
+    if (duration > maxDuration) {
+      const errorMessage = message || `Operation took ${duration.toFixed(2)}ms, expected < ${maxDuration}ms`
+      throw new Error(errorMessage)
+    }
+
+    return result
+  },
+}
+
+// Export all utilities
+export { expect }
+export default {
+  customMatchers,
+  testFactory,
+  asyncHelpers,
+  performanceHelpers,
+}

package/test/helpers/UiMock.ts

@@ -1,13 +1,34 @@
 import { nextFrame } from '@open-wc/testing'
 import { sendMouse } from '@web/test-runner-commands'
 
+/**
+ * Represents a 2D point with x and y coordinates.
+ */
 export interface Point {
+  /** The x-coordinate of the point. */
   x: number
+  /** The y-coordinate of the point. */
   y: number
 }
 
+/**
+ * A utility class for mocking user interface interactions in tests.
+ * It provides static methods to simulate keyboard and mouse events.
+ * This class is designed as a collection of static helpers, hence it has no constructor or instances.
+ */
 // eslint-disable-next-line @typescript-eslint/no-extraneous-class
 export class UiMock {
+  /**
+   * Dispatches a 'keydown' event on a given element.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent (e.g., 'Enter', 'KeyA').
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * UiMock.keyDown(document.body, 'Enter');
+   * UiMock.keyDown(myInputElement, 'KeyA', { ctrlKey: true });
+   */
   static keyDown(element: EventTarget, code: string, opts: KeyboardEventInit = {}): void {
     const defaults: KeyboardEventInit = {
       bubbles: true,
@@ -19,6 +40,16 @@ export class UiMock {
     element.dispatchEvent(down)
   }
 
+  /**
+   * Dispatches a 'keyup' event on a given element.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent (e.g., 'Escape', 'KeyB').
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * UiMock.keyUp(document.body, 'Escape');
+   */
   static keyUp(element: EventTarget, code: string, opts: KeyboardEventInit = {}): void {
     const defaults: KeyboardEventInit = {
       bubbles: true,
@@ -30,12 +61,35 @@ export class UiMock {
     element.dispatchEvent(down)
   }
 
+  /**
+   * Simulates a full key press by dispatching 'keydown' and 'keyup' events sequentially.
+   * It waits for the next animation frame between the two events.
+   *
+   * @param element The target element for the event.
+   * @param code The `code` value for the KeyboardEvent.
+   * @param opts Additional options to pass to the KeyboardEvent constructor.
+   *
+   * @example
+   * await UiMock.keyPress(myButton, 'Space');
+   */
   static async keyPress(element: EventTarget, code: string, opts?: KeyboardEventInit): Promise<void> {
     this.keyDown(element, code, opts)
     await nextFrame()
     this.keyUp(element, code, opts)
   }
 
+  /**
+   * Calculates the coordinates of the center of a given element.
+   *
+   * Note: This method mixes coordinate systems. `getBoundingClientRect` is viewport-relative,
+   * while `window.scrollY` is for document scrolling and `window.screenX` is for the
+   * screen position of the browser window. For use with `@web/test-runner-commands`'s `sendMouse`,
+   * which expects viewport-relative coordinates, the calculation should likely be:
+   * `x: Math.floor(x + width / 2)` and `y: Math.floor(y + height / 2)`.
+   *
+   * @param element The element to find the center of.
+   * @returns A `Point` object with the x and y coordinates of the element's center.
+   */
   static getMiddleOfElement(element: Element): Point {
     const { x, y, width, height } = element.getBoundingClientRect()
 
@@ -46,20 +100,21 @@ export class UiMock {
   }
 
   /**
-   * Moves the mouse from the `from` point to the `to` point using the Playwright API.
-   * This means the mouse will actually move in the browser.
+   * Moves the mouse from a starting point to an ending point in a series of steps.
+   * This uses the `@web/test-runner-commands` `sendMouse` API, which means
+   * the mouse will actually move in the browser running the tests.
    *
-   * @param from The {x,y} of the starting point
-   * @param to The {x,y} of the ending point
-   * @param steps The number of steps to take while moving
+   * @param from The starting {x, y} coordinates.
+   * @param to The ending {x, y} coordinates.
+   * @param steps The number of intermediate steps to take during the move. Defaults to 10.
    */
   static async moveMouse(from: Point, to: Point, steps = 10): Promise<void> {
-    const dx = to.x - to.x
-    const dy = to.y - to.y
+    const dx = to.x - from.x
+    const dy = to.y - from.y
     const ix = Math.round(dx / steps)
     const iy = Math.round(dy / steps)
-    let currentX = to.x
-    let currentY = to.y
+    let currentX = from.x
+    let currentY = from.y
 
     await sendMouse({ type: 'move', position: [from.x, from.y] })
     // await executeServerCommand('take-screenshot', { name: 'move-start' });
@@ -77,11 +132,13 @@ export class UiMock {
   }
 
   /**
-   * Performs a drag and drop in the browser using the Playwright API.
+   * Performs a drag-and-drop operation from a source element to a target element.
+   * It simulates moving to the source, pressing the mouse down, moving to the target,
+   * and releasing the mouse.
    *
-   * @param source The source element to drag
-   * @param target The target where to drop the `source`
-   * @param steps The number of mouse moves when dragging the `sources`
+   * @param source The HTMLElement to drag.
+   * @param target The HTMLElement to drop onto.
+   * @param steps The number of mouse moves to simulate during the drag. Defaults to 10.
    */
   static async dragAndDrop(source: HTMLElement, target: HTMLElement, steps = 10): Promise<void> {
     const from = UiMock.getMiddleOfElement(source)
@@ -96,6 +153,19 @@ export class UiMock {
     // await executeServerCommand('take-screenshot', { name: `after-up` });
   }
 
+  /**
+   * Creates a `DragEvent` for simulating file drags (e.g., for a file drop zone).
+   *
+   * @param type The type of the drag event (e.g., 'dragenter', 'dragover', 'drop').
+   * @param opts Options, including an optional `File` object to include in the event.
+   * If no file is provided, a default 'test.txt' file is created.
+   * @returns A new `DragEvent` instance.
+   *
+   * @example
+   * const myFile = new File(['(⌐□_□)'], 'chucknorris.png', { type: 'image/png' });
+   * const dropEvent = UiMock.getFileDragEvent('drop', { file: myFile });
+   * dropZone.dispatchEvent(dropEvent);
+   */
   static getFileDragEvent(type: string, opts: { file?: File } = {}): DragEvent {
     let file: File
     if (opts.file) {

package/test/md/dialog/UiDialog.test.ts

@@ -230,5 +230,174 @@ describe('md', () => {
         assert.isTrue(container.classList.contains('with-buttons'), 'has the with-buttons class')
       })
     })
+
+    describe('form handling', () => {
+      async function formWrappedDialogFixture(): Promise<{ form: HTMLFormElement; dialog: UiDialog }> {
+        const container = await fixture(html`
+          <form>
+            <ui-dialog submitClose>
+              <span slot="title">Form Dialog</span>
+              <input type="text" name="username" required />
+              <ui-button color="text" slot="button" value="dismiss">Cancel</ui-button>
+              <ui-button color="text" slot="button" value="confirm" type="submit">Submit</ui-button>
+            </ui-dialog>
+          </form>
+        `)
+        const form = container as HTMLFormElement
+        const dialog = form.querySelector('ui-dialog') as UiDialog
+        return { form, dialog }
+      }
+
+      async function formWithoutSubmitCloseFixture(): Promise<{ form: HTMLFormElement; dialog: UiDialog }> {
+        const container = await fixture(html`
+          <form>
+            <ui-dialog>
+              <span slot="title">Form Dialog</span>
+              <input type="text" name="username" required />
+              <ui-button color="text" slot="button" value="dismiss">Cancel</ui-button>
+              <ui-button color="text" slot="button" value="confirm" type="submit">Submit</ui-button>
+            </ui-dialog>
+          </form>
+        `)
+        const form = container as HTMLFormElement
+        const dialog = form.querySelector('ui-dialog') as UiDialog
+        return { form, dialog }
+      }
+
+      describe('dialog wrapped in form', () => {
+        it('should detect parent form when connected', async () => {
+          const { dialog } = await formWrappedDialogFixture()
+          await dialog.updateComplete
+
+          // The form should be detected during connectedCallback
+          // We can't directly access private fields, so we test the behavior instead
+          assert.ok(dialog.submitClose, 'dialog should be configured for form handling')
+        })
+
+        it('should close dialog when form is submitted and submitClose is true', async () => {
+          const { form, dialog } = await formWrappedDialogFixture()
+          dialog.open = true
+          await dialog.updateComplete
+
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          // Simulate form submission
+          const submitEvent = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+          form.dispatchEvent(submitEvent)
+
+          assert.isFalse(dialog.open, 'dialog should be closed')
+          assert.isTrue(spy.calledOnce, 'close event should be dispatched')
+          const event = spy.args[0][0] as CustomEvent
+          assert.isFalse(event.detail.cancelled, 'dialog should be confirmed, not cancelled')
+        })
+
+        it('should not close dialog when form is submitted and submitClose is false', async () => {
+          const { form, dialog } = await formWithoutSubmitCloseFixture()
+          dialog.open = true
+          await dialog.updateComplete
+
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          // Simulate form submission
+          const submitEvent = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+          form.dispatchEvent(submitEvent)
+
+          assert.isTrue(dialog.open, 'dialog should remain open')
+          assert.isFalse(spy.called, 'close event should not be dispatched')
+        })
+
+        it('should not handle form submit when submit button is clicked directly', async () => {
+          const { dialog } = await formWrappedDialogFixture()
+          dialog.open = true
+          await dialog.updateComplete
+
+          const submitButton = dialog.querySelector('ui-button[type="submit"]') as UiButton
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          // Click the submit button - this should not close the dialog immediately
+          // because we yield control to the form
+          submitButton.click()
+
+          // The dialog should still be open because the form hasn't been submitted yet
+          assert.isTrue(dialog.open, 'dialog should remain open when submit button is clicked')
+        })
+
+        it('should remove form event listener when disconnected', async () => {
+          const { form, dialog } = await formWrappedDialogFixture()
+          const removeEventListenerSpy = sinon.spy(form, 'removeEventListener')
+
+          dialog.remove()
+
+          // We can't test the private method directly, but we can verify the spy was called
+          // The actual method name is not accessible, so we test the behavior instead
+          assert.isTrue(removeEventListenerSpy.called, 'removeEventListener should be called on form')
+        })
+      })
+
+      describe('edge cases', () => {
+        it('should handle form submission when dialog is not open', async () => {
+          const { form, dialog } = await formWrappedDialogFixture()
+          // Dialog is closed by default
+          assert.isFalse(dialog.open, 'dialog should be closed initially')
+
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          // Submit form when dialog is closed
+          const submitEvent = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+          form.dispatchEvent(submitEvent)
+
+          // Should still close the dialog (set open to false even though it's already false)
+          assert.isFalse(dialog.open, 'dialog should remain closed')
+          assert.isTrue(spy.calledOnce, 'close event should still be dispatched')
+        })
+
+        it('should handle multiple form submissions', async () => {
+          const { form, dialog } = await formWrappedDialogFixture()
+          dialog.open = true
+          await dialog.updateComplete
+
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          // Submit form multiple times
+          const submitEvent1 = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+          const submitEvent2 = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+
+          form.dispatchEvent(submitEvent1)
+          form.dispatchEvent(submitEvent2)
+
+          assert.equal(spy.callCount, 2, 'close event should be dispatched for each submission')
+        })
+
+        it('should maintain form reference across re-connections', async () => {
+          const { form, dialog } = await formWrappedDialogFixture()
+
+          // Remove and re-add dialog
+          const parent = form
+          dialog.remove()
+          await dialog.updateComplete
+
+          parent.appendChild(dialog)
+          await dialog.updateComplete
+
+          // Test the behavior instead of accessing private fields
+          // If form handling is working, submitClose should still work
+          dialog.open = true
+          await dialog.updateComplete
+
+          const spy = sinon.spy()
+          dialog.addEventListener('close', spy)
+
+          const submitEvent = new SubmitEvent('submit', { bubbles: true, cancelable: true })
+          form.dispatchEvent(submitEvent)
+
+          assert.isTrue(spy.called, 'form handling should work after reconnection')
+        })
+      })
+    })
   })
 })