@api-client/ui 0.4.5 → 0.5.1

package/src/md/dialog/internals/Dialog.ts

@@ -8,6 +8,7 @@ import type { TypedEvents } from '../../../core/types.js'
 import { ifDefined } from 'lit/directives/if-defined.js'
 import { SyntheticSubmitEvent } from '../../../events/SyntheticSubmitEvent.js'
 import '../../button/ui-button.js'
+import { bound } from '../../../decorators/bound.js'
 
 export interface UiDialogClosingReason {
   /**
@@ -137,6 +138,8 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
    * - When the submit event is not cancelled, then:
    *  - The default confirm action is invoked.
    *  - The dialog is closed.
+   *
+   * @deprecated Wrap the content in a `<form>` element instead.
    */
   @property({ type: Boolean }) accessor useForm: boolean | undefined
 
@@ -147,6 +150,15 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
    * @attribute
    */
   @property({ type: String }) accessor confirmValue: string | undefined
+  /**
+   * When the dialog is wrapped in a form, set this to `true` to close the dialog
+   * when the form is submitted.
+   *
+   * Note that the dialog doesn't perform any validation of the form. It only closes
+   * when the form is submitted, regardless of the application logic. The `submit` event
+   * is dispatched by the dialog when the form is valid.
+   */
+  @property({ type: Boolean }) accessor submitClose: boolean | undefined
 
   /**
    * A reference to the underlying dialog element.
@@ -173,14 +185,32 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
 
   #formId?: string
 
+  /**
+   * @deprecated Use `useForm` instead.
+   */
   get formId(): string | undefined {
     return this.#formId
   }
 
+  /**
+   * @deprecated This will be removed in the future.
+   */
   @state() accessor #inject: TemplateResult | RenderFunction | undefined
 
+  /**
+   * @deprecated This will be removed in the future.
+   */
   #pendingStyles?: CSSResultOrNative[]
 
+  /**
+   * A reference to the parent form element.
+   * When a form is found, the dialog will hook into the form's submit event
+   * and close the dialog when the form is submitted.
+   * Since the `submit` event is dispatched when the form is valid,
+   * we can use this to close the dialog and not worry about the form validation.
+   */
+  #form: HTMLFormElement | null = null
+
   constructor() {
     super()
 
@@ -192,6 +222,7 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
    * Allows to inject a template into the internals of the element.
    * This is helpful when working with imperative dialogs.
    * @param content The content to inject into the body.
+   * @deprecated This will be removed in the future. To use forms, wrap the content in a `<form>` element.
    */
   inject(content?: TemplateResult | RenderFunction, styles?: CSSResultOrNative[]): void {
     this.#inject = content
@@ -210,6 +241,22 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
     }
   }
 
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.#form = this.closest('form')
+    if (this.#form) {
+      this.#form.addEventListener('submit', this.handleFormSubmit)
+    }
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback()
+    if (this.#form) {
+      this.#form.removeEventListener('submit', this.handleFormSubmit)
+      this.#form = null
+    }
+  }
+
   protected override firstUpdated(): void {
     const styles = this.#pendingStyles
     if (styles) {
@@ -226,6 +273,13 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
     }
   }
 
+  @bound
+  protected handleFormSubmit(): void {
+    if (this.submitClose) {
+      this.handleInteraction('confirm')
+    }
+  }
+
   override handleClick(e: MouseEvent): void {
     super.handleClick(e)
     const path = e.composedPath()
@@ -238,7 +292,6 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
       // Adds support for forms.
       // When a form's submit button is clicked we yield the flow control to the form.
       // This way the form can handle the submit event.
-      e.preventDefault()
       return
     }
     const { value = '' } = button

package/src/md/menu/internal/Menu.styles.ts

@@ -9,6 +9,10 @@ export default css`
     margin: 0;
     padding: 0;
     border: none;
+    overflow: hidden;
+    /* in most cases the max-height won't matter as this assumes the whole screen to be available, which is rarely the truth. */
+    max-height: 90vh;
+    overflow: auto;
   }
 
   :host(:popover-open) {

package/src/md/menu/internal/Menu.ts

@@ -70,10 +70,12 @@ export default class Menu extends UiList {
     this.open = !this.open
     this.ariaExpanded = String(this.open)
     this.tabIndex = this.open ? 0 : -1
+    const result = super.togglePopover(force)
     if (this.open) {
+      this.positionMenu()
       this.focus()
     }
-    return super.togglePopover(force)
+    return result
   }
 
   /**
@@ -84,6 +86,7 @@ export default class Menu extends UiList {
     this.ariaExpanded = 'true'
     this.showPopover()
     this.open = true
+    this.positionMenu()
     this.focus()
     this.dispatchEvent(new CustomEvent('open', { bubbles: false, composed: true }))
   }
@@ -100,6 +103,45 @@ export default class Menu extends UiList {
     this.dispatchEvent(new CustomEvent('close', { bubbles: false, composed: true }))
   }
 
+  positionMenu(): void {
+    // when there's more space above the anchor, position the menu above it
+    const box = this.getBoundingClientRect()
+    // Now, we determine, whether to position the menu above or below the anchor
+    // in a way, that if we have enough space below the anchor, we position it below,
+    // otherwise we position it above the anchor.
+
+    // our starting point is the anchor being positioned below the anchor
+    const menuBottom = box.top + box.height
+    if (menuBottom <= innerHeight) {
+      // if the menu fits below the anchor, we leave it as is.
+      return
+    }
+    // we do not make association from the menu to the anchor, so we make an assumption
+    // that the anchor is 40px high, which is the default height of a button.
+    // it can be different, but this is a good starting point.
+    const anchorHeight = 40
+    const anchorBottom = box.top
+    const anchorTop = anchorBottom - anchorHeight
+    const menuHeight = box.height
+
+    const spaceBelow = innerHeight - anchorBottom
+    const spaceAbove = anchorTop
+
+    const diffBelow = spaceBelow - menuHeight
+    const diffAbove = spaceAbove - menuHeight
+    // The initial check ensures the menu does not fit below. Now, check if it fits above.
+    if (diffAbove >= 0) {
+      this.style.setProperty('position-area', 'top span-right')
+    } else if (diffAbove > diffBelow) {
+      // It doesn't fit in either direction. Choose the one with less overflow (larger, i.e., less negative, diff).
+      this.style.setProperty('position-area', 'top span-right')
+      this.style.maxHeight = `${spaceAbove}px`
+    } else {
+      this.style.setProperty('position-area', 'bottom span-right')
+      this.style.maxHeight = `${spaceBelow}px`
+    }
+  }
+
   /**
    * Handles beforetoggle event from popover
    */

package/test/README.md

@@ -0,0 +1,372 @@
+# Test Setup Guide
+
+This document explains how to use the test infrastructure for the UI component library.
+
+## Overview
+
+The test setup provides:
+
+- **Global test utilities** for common testing patterns
+- **Custom matchers** for better assertions
+- **UI interaction helpers** for simulating user actions
+- **Async helpers** for handling asynchronous operations
+- **Performance testing utilities**
+
+## Test Configuration
+
+### Web Test Runner
+
+Tests run using [Web Test Runner](https://modern-web.dev/docs/test-runner/overview/) with:
+
+- **Playwright** for browser automation
+- **OAuth2 mock server** for authentication testing
+- **Coverage reporting** with lcov format
+- **Custom test HTML** with Material Design 3 styles
+
+### File Structure
+
+```plain
+test/
+├── setup.ts                 # Global test setup
+├── setup.test.ts            # Example test demonstrating setup
+├── env.ts                   # Environment configuration
+├── helpers/
+│   ├── UiMock.ts            # UI interaction utilities
+│   └── TestUtils.ts         # Extended test utilities
+└── [component-tests]/       # Component-specific tests
+```
+
+## Running Tests
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+## Global Test Utilities
+
+The setup provides global utilities accessible via `window.testUtils`:
+
+### waitForElement(selector, timeout?)
+
+Wait for an element to appear in the DOM:
+
+```typescript
+const element = await window.testUtils.waitForElement('#my-element', 5000)
+```
+
+### waitForCondition(condition, timeout?)
+
+Wait for a condition to become true:
+
+```typescript
+await window.testUtils.waitForCondition(() => someVariable === true, 5000)
+```
+
+## Custom Matchers
+
+Enhanced assertion helpers in `customMatchers`:
+
+### toHaveClasses(element, ...classes)
+
+Check if element has specific CSS classes:
+
+```typescript
+const result = customMatchers.toHaveClasses(element, 'active', 'highlighted')
+assert.isTrue(result.pass)
+```
+
+### toBeVisible(element)
+
+Check if element is visible (not hidden by CSS):
+
+```typescript
+const result = customMatchers.toBeVisible(element)
+assert.isTrue(result.pass)
+```
+
+### toHaveAttribute(element, attribute, value?)
+
+Check if element has specific attribute:
+
+```typescript
+const result = customMatchers.toHaveAttribute(element, 'data-test', 'value')
+assert.isTrue(result.pass)
+```
+
+## UI Interaction (UiMock)
+
+Simulate user interactions:
+
+### Keyboard Events
+
+```typescript
+// Single key events
+UiMock.keyDown(element, 'Enter')
+UiMock.keyUp(element, 'Escape')
+
+// Full key press (down + up)
+await UiMock.keyPress(element, 'Space', { ctrlKey: true })
+```
+
+### Mouse Events
+
+```typescript
+// Get element center
+const center = UiMock.getMiddleOfElement(element)
+
+// Move mouse between points
+await UiMock.moveMouse(fromPoint, toPoint, steps)
+
+// Drag and drop
+await UiMock.dragAndDrop(sourceElement, targetElement)
+```
+
+### File Drag Events
+
+```typescript
+const file = new File(['content'], 'test.txt', { type: 'text/plain' })
+const dragEvent = UiMock.getFileDragEvent('drop', { file })
+element.dispatchEvent(dragEvent)
+```
+
+## Async Helpers
+
+Handle asynchronous operations:
+
+### waitForAll(conditions, timeout?)
+
+Wait for multiple conditions:
+
+```typescript
+await asyncHelpers.waitForAll([
+  () => condition1,
+  () => condition2,
+], 5000)
+```
+
+### waitForAny(conditions, timeout?)
+
+Wait for any condition to be true:
+
+```typescript
+const index = await asyncHelpers.waitForAny([
+  () => condition1,
+  () => condition2,
+])
+```
+
+### retry(operation, maxAttempts?, baseDelay?)
+
+Retry failed operations with exponential backoff:
+
+```typescript
+const result = await asyncHelpers.retry(async () => {
+  const response = await fetch('/api/data')
+  if (!response.ok) throw new Error('Failed')
+  return response.json()
+}, 3, 100)
+```
+
+## Test Factories
+
+Create reusable test data and element factories:
+
+### Data Factory
+
+```typescript
+const userFactory = testFactory.createDataFactory({
+  id: 1,
+  name: 'Test User',
+  email: 'test@example.com',
+})
+
+const user1 = userFactory() // Uses defaults
+const user2 = userFactory({ name: 'Custom User' }) // Override specific fields
+```
+
+### Element Test Suite
+
+```typescript
+const suite = testFactory.createElementTestSuite('my-element', '../src/my-element.js')
+
+// In tests:
+await suite.setup()
+const element = await suite.createElement({ attribute: 'value' }, 'content')
+// ... test element ...
+suite.cleanup()
+```
+
+## Performance Testing
+
+Measure and assert performance:
+
+### measureTime(fn)
+
+```typescript
+const { result, duration } = await performanceHelpers.measureTime(async () => {
+  return await someExpensiveOperation()
+})
+
+console.log(`Operation took ${duration}ms`)
+```
+
+### expectWithinTime(operation, maxDuration, message?)
+
+```typescript
+const result = await performanceHelpers.expectWithinTime(
+  () => renderLargeList(),
+  1000, // max 1 second
+  'List rendering should be fast'
+)
+```
+
+## Writing Component Tests
+
+### Basic Structure
+
+```typescript
+import { assert, fixture, html } from '@open-wc/testing'
+import { customMatchers } from '../helpers/TestUtils.js'
+import { UiMock } from '../helpers/UiMock.js'
+
+// Import test setup
+import '../setup.js'
+
+// Import component
+import '../src/my-component.js'
+
+describe('MyComponent', () => {
+  async function basicFixture() {
+    return fixture(html`<my-component></my-component>`)
+  }
+
+  it('should render correctly', async () => {
+    const element = await basicFixture()
+    
+    // Use custom matchers
+    const result = customMatchers.toBeVisible(element)
+    assert.isTrue(result.pass)
+    
+    // Test functionality
+    await UiMock.keyPress(element, 'Enter')
+    
+    // Wait for changes
+    await window.testUtils.waitForCondition(() => 
+      element.hasAttribute('data-processed')
+    )
+    
+    assert.isTrue(element.hasAttribute('data-processed'))
+  })
+})
+```
+
+### Testing Custom Elements
+
+```typescript
+describe('CustomElement', () => {
+  let element: HTMLElement
+
+  beforeEach(async () => {
+    element = await fixture(html`<custom-element 
+      .property="${'value'}"
+      @event="${(e) => console.log(e)}"
+    ></custom-element>`)
+  })
+
+  it('should handle properties', () => {
+    // Test property binding
+    assert.equal(element.property, 'value')
+  })
+
+  it('should handle events', async () => {
+    let eventFired = false
+    element.addEventListener('custom-event', () => {
+      eventFired = true
+    })
+
+    // Trigger event
+    element.dispatchEvent(new CustomEvent('trigger'))
+    
+    await window.testUtils.waitForCondition(() => eventFired)
+    assert.isTrue(eventFired)
+  })
+})
+```
+
+## Environment Variables
+
+Test environment configuration is available through the mock server:
+
+- OAuth2 server details available in test environment
+- Custom environment setup via `env.ts`
+
+## Coverage Reports
+
+Coverage reports are generated in `coverage/` directory:
+
+- `lcov.info` - Machine-readable coverage data
+- `lcov-report/` - Human-readable HTML reports
+
+Open `coverage/lcov-report/index.html` to view detailed coverage information.
+
+## Best Practices
+
+1. **Use the global setup**: Import `../setup.js` in test files
+2. **Leverage custom matchers**: Use `customMatchers` for better assertions
+3. **Simulate real interactions**: Use `UiMock` for realistic user interactions
+4. **Handle async operations**: Use `asyncHelpers` for waiting and retrying
+5. **Create reusable factories**: Use `testFactory` for common test data
+6. **Test performance**: Use `performanceHelpers` for timing-critical code
+7. **Clean up properly**: The global setup handles cleanup automatically
+8. **Use meaningful assertions**: Prefer descriptive custom matchers over generic ones
+
+## DOM Element Assertions
+
+When comparing DOM elements, always use the special DOM assertion methods from `@open-wc/testing`:
+
+### assert.dom.equal(actual, expected)
+
+Compare DOM elements for equality:
+
+```typescript
+const element1 = document.querySelector('#test')
+const element2 = await window.testUtils.waitForElement('#test')
+assert.dom.equal(element1, element2)
+```
+
+### assert.dom.notEqual(actual, expected)
+
+Assert that DOM elements are not the same:
+
+```typescript
+const element1 = document.querySelector('#test1')
+const element2 = document.querySelector('#test2')
+assert.dom.notEqual(element1, element2)
+```
+
+### assert.dom.equalSnapshot(element, snapshot)
+
+Compare element with a snapshot:
+
+```typescript
+const element = await fixture(html`<div>Content</div>`)
+assert.dom.equalSnapshot(element, '<div>Content</div>')
+```
+
+### assert.dom.notEqualSnapshot(element, snapshot)
+
+Assert element doesn't match snapshot:
+
+```typescript
+const element = await fixture(html`<div>Changed</div>`)
+assert.dom.notEqualSnapshot(element, '<div>Original</div>')
+```
+
+> ⚠️ **Important**: Never use regular `assert.equal()` for DOM elements as it won't work correctly. Always use `assert.dom.*` methods for DOM comparisons.