@api-client/ui 0.5.0 → 0.5.1

package/demo/md/dialog/dialog.ts

@@ -18,6 +18,8 @@ class ComponentDemoPage extends DemoPage {
 
   @reactive() accessor overflowOpened = false
 
+  @reactive() accessor formOpened = false
+
   protected openSimple(): void {
     this.simpleOpened = true
   }
@@ -45,6 +47,15 @@ class ComponentDemoPage extends DemoPage {
     this.reportClosingReason(e.detail)
   }
 
+  protected openForm(): void {
+    this.formOpened = true
+  }
+
+  protected formClosed(e: CustomEvent<UiDialogClosingReason>): void {
+    this.formOpened = false
+    this.reportClosingReason(e.detail)
+  }
+
   imperativeDialog: UiDialog | null = null
 
   protected openImperative(): void {
@@ -81,7 +92,8 @@ class ComponentDemoPage extends DemoPage {
   contentTemplate(): TemplateResult {
     return html`
       <a href="../">Back</a>
-      ${this.simpleDialog()} ${this.fullDialog()} ${this.overflowDialog()} ${this.renderImperativeDialog()}
+      ${this.simpleDialog()} ${this.fullDialog()} ${this.overflowDialog()} ${this.formDialog()}
+      ${this.renderImperativeDialog()}
     `
   }
 
@@ -244,6 +256,128 @@ class ComponentDemoPage extends DemoPage {
     `
   }
 
+  formDialog(): TemplateResult {
+    return html`
+      <section class="demo-section">
+        <h2 class="title-large">Form dialog</h2>
+        <p>This dialog contains a form with validation and submit handling.</p>
+        <ui-button color="filled" @click="${this.openForm}">Open Form Dialog</ui-button>
+        <form @submit="${this.handleFormSubmit}" style="display: contents;">
+          <ui-dialog
+            ?open="${this.formOpened}"
+            @close="${this.formClosed}"
+            modal
+            style="--ui-dialog-max-width: 500px;"
+            submitClose
+          >
+            <ui-icon slot="icon" icon="info"></ui-icon>
+            <span slot="title">User Registration</span>
+
+            <div style="display: flex; flex-direction: column; gap: 16px;">
+              <label style="display: flex; flex-direction: column; gap: 4px;">
+                <span style="font-weight: 500; color: var(--md-sys-color-on-surface);">Full Name *</span>
+                <input
+                  type="text"
+                  name="fullName"
+                  required
+                  style="padding: 12px; border: 1px solid var(--md-sys-color-outline); border-radius: 4px; font-size: 14px;"
+                  placeholder="Enter your full name"
+                />
+              </label>
+
+              <label style="display: flex; flex-direction: column; gap: 4px;">
+                <span style="font-weight: 500; color: var(--md-sys-color-on-surface);">Email *</span>
+                <input
+                  type="email"
+                  name="email"
+                  required
+                  style="padding: 12px; border: 1px solid var(--md-sys-color-outline); border-radius: 4px; font-size: 14px;"
+                  placeholder="Enter your email address"
+                />
+              </label>
+
+              <label style="display: flex; flex-direction: column; gap: 4px;">
+                <span style="font-weight: 500; color: var(--md-sys-color-on-surface);">Phone Number</span>
+                <input
+                  type="tel"
+                  name="phone"
+                  style="padding: 12px; border: 1px solid var(--md-sys-color-outline); border-radius: 4px; font-size: 14px;"
+                  placeholder="Enter your phone number (optional)"
+                />
+              </label>
+
+              <label style="display: flex; flex-direction: column; gap: 4px;">
+                <span style="font-weight: 500; color: var(--md-sys-color-on-surface);">Department</span>
+                <select
+                  name="department"
+                  style="padding: 12px; border: 1px solid var(--md-sys-color-outline); border-radius: 4px; font-size: 14px; background: white;"
+                >
+                  <option value="">Select a department</option>
+                  <option value="engineering">Engineering</option>
+                  <option value="design">Design</option>
+                  <option value="marketing">Marketing</option>
+                  <option value="sales">Sales</option>
+                  <option value="support">Support</option>
+                </select>
+              </label>
+
+              <label style="display: flex; align-items: center; gap: 8px; margin-top: 8px;">
+                <input type="checkbox" name="newsletter" style="margin: 0;" />
+                <span style="font-size: 14px; color: var(--md-sys-color-on-surface);">
+                  Subscribe to our newsletter
+                </span>
+              </label>
+
+              <label style="display: flex; align-items: center; gap: 8px;">
+                <input type="checkbox" name="terms" required style="margin: 0;" />
+                <span style="font-size: 14px; color: var(--md-sys-color-on-surface);">
+                  I agree to the <a href="#" style="color: var(--md-sys-color-primary);">Terms and Conditions</a> *
+                </span>
+              </label>
+            </div>
+
+            <ui-button color="text" slot="button" value="dismiss">Cancel</ui-button>
+            <ui-button color="filled" slot="button" value="confirm" type="submit">Register</ui-button>
+          </ui-dialog>
+        </form>
+      </section>
+    `
+  }
+
+  protected handleFormSubmit(e: CustomEvent): void {
+    e.preventDefault()
+
+    // Get form data from the event
+    const form = e.target as HTMLFormElement
+    const formData = new FormData(form)
+
+    // Convert to regular object for easier handling
+    const data: Record<string, string | boolean> = {}
+    for (const [key, value] of formData.entries()) {
+      if (key === 'newsletter' || key === 'terms') {
+        data[key] = value === 'on'
+      } else {
+        data[key] = value as string
+      }
+    }
+
+    console.log('Form submitted with data:', data)
+
+    // Simulate form validation
+    if (!data.fullName || !data.email) {
+      console.error('Required fields are missing')
+      return
+    }
+
+    if (!data.terms) {
+      console.error('Terms and conditions must be accepted')
+      return
+    }
+
+    // If validation passes, the dialog will close automatically
+    console.log('Registration successful!', data)
+  }
+
   renderImperativeDialog(): TemplateResult {
     return html`
       <section class="demo-section">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@api-client/ui",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Internal UI component library for the API Client ecosystem.",
   "license": "UNLICENSED",
   "main": "build/src/index.js",
@@ -182,7 +182,7 @@
     "dompurify": "^3.2.5",
     "idb-keyval": "^6.1.0",
     "lit": "^3.2.1",
-    "marked": "^15.0.7",
+    "marked": "^16.0.0",
     "monaco-editor": "^0.52.2",
     "nanoid": "^5.1.5",
     "prismjs": "^1.28.0",

package/src/elements/highlight/MarkedHighlight.ts

@@ -247,7 +247,8 @@ export default class MarkedHighlight extends LitElement {
       pedantic: this.pedantic,
       gfm: true,
     }
-    let out = marked(data, opts) as string
+    // eslint-disable-next-line no-misleading-character-class
+    let out = marked(data.replace(/^[\u200B\u200C\u200D\u200E\u200F\uFEFF]/, ''), opts) as string
     if (this.sanitize) {
       if (this.sanitizer) {
         out = this.sanitizer(out)

package/src/md/button/internals/base.ts

@@ -240,7 +240,7 @@ export default class BaseButton extends UiElement {
   }
 
   override handleClick(e: MouseEvent): void {
-    super.handleClick(e)
+    // Do not call super.handleClick() here, as it would call `endPress` again.
     if (this.disabled) {
       e.preventDefault()
       e.stopPropagation()

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/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.