@api-client/ui 0.5.2 → 0.5.4

package/src/md/dialog/README.md

@@ -0,0 +1,212 @@
+# UI Confirm Dialog
+
+A simple Material Design 3 styled | Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `open` | `boolean` | `false` | Controls dialog visibility |
+| `modal` | `boolean` | `true` | Whether dialog is modal (set by default) |
+| `confirmLabel` | `string` | `'Confirm'` | Text for the confirm button |
+| `dismissLabel` | `string` | `'Cancel'` | Text for the dismiss button |
+| `destructive` | `boolean` | `false` | Styles confirm button with error colors for destructive actions |m dialog component for confirming user actions.
+
+## Features
+
+- **Material Design 3 Styling**: Follows MD3 design tokens and patterns
+- **Customizable Button Labels**: Configure confirm and dismiss button text
+- **Slot-based Content**: Flexible content structure with title and body slots
+- **Modal by Default**: Designed for confirmation workflows
+- **Accessible**: Supports keyboard navigation and screen readers
+- **Built-in Event Handling**: Dispatches close events with detailed reason information
+
+## Usage
+
+### Basic Usage
+
+```html
+<ui-confirm-dialog .open="${showDialog}" @close="${handleClose}">
+  <span slot="title">Confirm Action</span>
+  <p>Are you sure you want to proceed with this action?</p>
+</ui-confirm-dialog>
+```
+
+### Custom Button Labels
+
+```html
+<ui-confirm-dialog 
+  confirmLabel="Delete" 
+  dismissLabel="Keep"
+  destructive
+  .open="${showDialog}"
+  @close="${handleClose}"
+>
+  <span slot="title">Delete Item</span>
+  <p>Are you sure you want to delete this item? This action cannot be undone.</p>
+</ui-confirm-dialog>
+```
+
+### Event Handling
+
+```javascript
+function handleClose(e) {
+  const { cancelled, value } = e.detail;
+  if (!cancelled) {
+    // User confirmed the action
+    performAction();
+  } else {
+    // User dismissed the dialog
+    console.log('Action cancelled');
+  }
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `open` | `boolean` | `false` | Controls dialog visibility |
+| `modal` | `boolean` | `true` | Whether dialog is modal (set by default) |
+| `confirmLabel` | `string` | `'Confirm'` | Text for the confirm button |
+| `dismissLabel` | `string` | `'Cancel'` | Text for the dismiss button |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `title` | Dialog title content |
+| (default) | Main body content |
+
+## Events
+
+| Event | Detail Type | Description |
+|-------|-------------|-------------|
+| `close` | `UiDialogClosingReason` | Fired when dialog is closed |
+
+### UiDialogClosingReason
+
+```typescript
+interface UiDialogClosingReason {
+  cancelled: boolean;  // true if dismissed, false if confirmed
+  value?: unknown;     // optional value associated with the action
+}
+```
+
+## Styling
+
+The component uses Material Design 3 design tokens and can be styled using CSS custom properties:
+
+```css
+ui-confirm-dialog {
+  --ui-dialog-max-width: 400px;
+  --ui-dialog-max-height: 300px;
+}
+```
+
+## Design Patterns
+
+### Confirmation Workflows
+
+Use this dialog when you need users to explicitly confirm an action:
+
+- Deleting items
+- Saving changes
+- Leaving unsaved work
+- Performing destructive actions
+
+### Button Styling
+
+The component follows Material Design patterns:
+
+- **Dismiss button**: Text style (lower emphasis)
+- **Confirm button**: Filled style (higher emphasis)
+
+### Content Guidelines
+
+- **Title**: Keep concise, use action-oriented language
+- **Body**: Explain the consequence of the action
+- **Button Labels**: Use specific, clear language
+
+## Examples
+
+### Delete Confirmation
+
+```html
+<ui-confirm-dialog 
+  confirmLabel="Delete" 
+  dismissLabel="Keep"
+  destructive
+  .open="${showDelete}"
+>
+  <span slot="title">Delete Item</span>
+  <p>Are you sure you want to delete this item?</p>
+  <p><strong>This action cannot be undone.</strong></p>
+</ui-confirm-dialog>
+```
+
+### Save Changes
+
+```html
+<ui-confirm-dialog 
+  confirmLabel="Save & Exit" 
+  dismissLabel="Continue Editing"
+  .open="${showSave}"
+>
+  <span slot="title">Save Changes</span>
+  <p>You have unsaved changes in your document.</p>
+  <p>Would you like to save your changes before exiting?</p>
+</ui-confirm-dialog>
+```
+
+### Logout Confirmation
+
+```html
+<ui-confirm-dialog 
+  confirmLabel="Logout" 
+  dismissLabel="Stay Logged In"
+  .open="${showLogout}"
+>
+  <span slot="title">Logout</span>
+  <p>Are you sure you want to logout?</p>
+</ui-confirm-dialog>
+```
+
+### Destructive Actions
+
+Use the `destructive` attribute for actions that are permanent or could cause data loss:
+
+- Deleting items
+- Removing users
+- Clearing data
+- Resetting settings
+
+The destructive styling uses Material Design error colors to provide clear visual feedback that the action is potentially harmful.
+
+```html
+<ui-confirm-dialog 
+  confirmLabel="Delete Account" 
+  dismissLabel="Cancel"
+  destructive
+  .open="${showDeleteAccount}"
+>
+  <span slot="title">Delete Account</span>
+  <p>This will permanently delete your account and all associated data.</p>
+  <p><strong>This action cannot be undone.</strong></p>
+</ui-confirm-dialog>
+```
+
+## Accessibility
+
+The component includes:
+
+- Proper ARIA attributes
+- Keyboard navigation support (ESC to dismiss)
+- Focus management
+- Screen reader compatibility
+
+## Integration
+
+To use in your project:
+
+```typescript
+import '../path/to/ui-confirm-dialog.js';
+```
+
+The component is available as `<ui-confirm-dialog>` in your HTML templates.

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

@@ -0,0 +1,79 @@
+import { TemplateResult, html } from 'lit'
+import { ClassInfo, classMap } from 'lit/directives/class-map.js'
+import UiDialog from './Dialog.js'
+
+import '../../button/ui-button.js'
+
+/**
+ * A simple Material Design 3 styled confirm dialog for confirming user actions.
+ *
+ * This dialog provides a clean way to ask users to confirm or dismiss an action.
+ * It supports customizable button labels and content through slots.
+ *
+ * **Usage Example:**
+ * ```html
+ * <ui-confirm-dialog modal .open="${this.showConfirm}" @close="${this.handleConfirmClose}">
+ *   <span slot="title">Delete Item</span>
+ *   <p>Are you sure you want to delete this item? This action cannot be undone.</p>
+ * </ui-confirm-dialog>
+ * ```
+ *
+ * **Event Handling:**
+ * Listen for the `close` event to handle user interaction:
+ * ```javascript
+ * dialog.addEventListener('close', (e) => {
+ *   const { cancelled } = e.detail;
+ *   if (!cancelled) {
+ *     // User confirmed the action
+ *     performAction();
+ *   }
+ * });
+ * ```
+ *
+ * @slot title - The dialog title content
+ * @slot - The main body content of the dialog
+ * @fires close - Dispatched when the dialog is closed with closing reason details
+ */
+export default class ConfirmDialog extends UiDialog {
+  constructor() {
+    super()
+    // Set modal by default for confirm dialogs
+    this.modal = true
+    this.confirmLabel = 'Confirm'
+    this.dismissLabel = 'Cancel'
+  }
+
+  protected override renderContent(): TemplateResult[] {
+    return [this.renderTitle(), this.renderBody(), this.renderButtons()]
+  }
+
+  protected override renderButtons(): TemplateResult {
+    const classes: ClassInfo = {
+      'buttons': true,
+      'with-buttons': true,
+    }
+
+    return html`
+      <div class="${classMap(classes)}" part="buttons">
+        <ui-button
+          color="text"
+          value="dismiss"
+          class="internal-button"
+          @click="${this.handleDismiss}"
+          part="dismiss-button"
+        >
+          ${this.dismissLabel}
+        </ui-button>
+        <ui-button
+          color="filled"
+          value="confirm"
+          class="internal-button ${this.destructive ? 'destructive' : ''}"
+          @click="${this.handleConfirm}"
+          part="confirm-button"
+        >
+          ${this.confirmLabel}
+        </ui-button>
+      </div>
+    `
+  }
+}

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

@@ -28,6 +28,20 @@ export default css`
     flex-direction: column;
   }
 
+  /* Positioning for non-modal dialogs */
+  dialog.non-modal {
+    position: fixed;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    margin: 0;
+  }
+
+  dialog.non-modal:open {
+    /* Override the animation transform for non-modal dialogs to account for centering */
+    animation: 250ms cubic-bezier(0.2, 0, 0, 1) show-non-modal-dialog;
+  }
+
   dialog:open::backdrop {
     animation: 250ms cubic-bezier(0.2, 0, 0, 1) show-backdrop;
   }
@@ -35,7 +49,6 @@ export default css`
   .container {
     display: flex;
     flex-direction: column;
-    overflow: hidden;
     flex: 1;
   }
 
@@ -57,6 +70,11 @@ export default css`
     height: 24px;
   }
 
+  .icon.destructive ::slotted(*) {
+    color: var(--md-sys-color-error);
+    fill: var(--md-sys-color-error);
+  }
+
   .title {
     display: none;
     color: var(--md-sys-color-on-surface);
@@ -114,6 +132,15 @@ export default css`
     }
   }
 
+  @keyframes show-non-modal-dialog {
+    from {
+      transform: translate(-50%, -50%) translateY(-110%) scaleY(0);
+    }
+    to {
+      transform: translate(-50%, -50%) translateY(0%) scaleY(1);
+    }
+  }
+
   @keyframes show-backdrop {
     from {
       opacity: 0;
@@ -122,4 +149,15 @@ export default css`
       opacity: 1;
     }
   }
+
+  /* Destructive button styling for dangerous actions */
+  .internal-button.destructive {
+    --_background-color: var(--md-sys-color-error);
+    --_color: var(--md-sys-color-on-error);
+
+    /* Override ripple colors for better interaction feedback */
+    --md-ripple-hover-state-layer-color: var(--md-sys-color-on-error);
+    --md-ripple-focus-state-layer-color: var(--md-sys-color-on-error);
+    --md-ripple-pressed-state-layer-color: var(--md-sys-color-on-error);
+  }
 `

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

@@ -123,6 +123,13 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
    */
   @property({ type: String }) accessor confirmLabel: string | undefined
 
+  /**
+   * When true, styles the confirm button with error colors to indicate
+   * a destructive action (e.g., delete, remove, etc.).
+   * @attribute
+   */
+  @property({ type: Boolean }) accessor destructive = false
+
   /**
    * Part of the imperative access to the element.
    * When set, it wraps the content in a `<form>` element.
@@ -300,6 +307,9 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
 
   override handleKeyDown(e: KeyboardEvent): void {
     super.handleKeyDown(e)
+    if (e.defaultPrevented) {
+      return
+    }
     if (e.key === 'Escape') {
       this.handleInteraction('dismiss')
     }
@@ -389,9 +399,10 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
   }
 
   override render(): TemplateResult {
-    const { useForm } = this
+    const { useForm, modal } = this
+    const dialogClass = modal ? 'modal' : 'non-modal'
     return html`
-      <dialog @close="${this.handleDialogClose}" part="dialog">
+      <dialog @close="${this.handleDialogClose}" part="dialog" class="${dialogClass}">
         <div class="container">${useForm ? this.#renderFormContent() : this.renderContent()}</div>
       </dialog>
     `
@@ -413,6 +424,7 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
     const classes: ClassInfo = {
       'icon': true,
       'with-icon': this.hasIcon,
+      'destructive': this.destructive,
     }
     return html`
       <div class="${classMap(classes)}" part="icon">
@@ -473,17 +485,18 @@ export default class UiDialog extends UiElement implements TypedEvents<DialogEve
   }
 
   #renderConfirmButton(): TemplateResult | typeof nothing {
-    const { confirmLabel, confirmValue = 'confirm', useForm } = this
+    const { confirmLabel, confirmValue = 'confirm', useForm, destructive } = this
     if (!confirmLabel) {
       return nothing
     }
     const type = useForm ? 'submit' : 'button'
+    const buttonClass = destructive ? 'internal-button destructive' : 'internal-button'
     return html`
       <ui-button
         color="text"
         type="${type}"
         value="${confirmValue}"
-        class="internal-button"
+        class="${buttonClass}"
         @click="${this.handleConfirm}"
         part="positive-action"
         >${confirmLabel}</ui-button

package/src/md/dialog/ui-confirm-dialog.ts

@@ -0,0 +1,52 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internals/ConfirmDialog.js'
+import dialogStyles from './internals/Dialog.styles.js'
+
+/**
+ * A simple Material Design 3 styled confirm dialog component.
+ *
+ * This dialog is designed specifically for confirmation workflows where users
+ * need to confirm or dismiss an action. It provides a clean, accessible interface
+ * with customizable button labels and content.
+ *
+ * **Features:**
+ * - Material Design 3 styling
+ * - Customizable confirm and dismiss button labels
+ * - Modal by default
+ * - Accessible keyboard navigation
+ * - Slot-based content structure
+ *
+ * **Usage:**
+ * ```html
+ * <ui-confirm-dialog .open="${showDialog}" @close="${handleClose}">
+ *   <span slot="title">Confirm Action</span>
+ *   <p>Are you sure you want to proceed with this action?</p>
+ * </ui-confirm-dialog>
+ * ```
+ *
+ * **Customizing Button Labels:**
+ * ```html
+ * <ui-confirm-dialog
+ *   confirmLabel="Delete"
+ *   dismissLabel="Keep"
+ *   .open="${showDialog}"
+ * >
+ *   <span slot="title">Delete Item</span>
+ *   <p>This action cannot be undone.</p>
+ * </ui-confirm-dialog>
+ * ```
+ *
+ * @slot title - The dialog title
+ * @slot - The main content body
+ */
+@customElement('ui-confirm-dialog')
+export class UiConfirmDialogElement extends Element {
+  static override styles: CSSResultOrNative[] = [dialogStyles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ui-confirm-dialog': UiConfirmDialogElement
+  }
+}

package/test/README.md

@@ -49,6 +49,8 @@ npm run test:watch
 npm run test:coverage
 ```
 
+> ⚠️ **Note**: This project uses Web Test Runner, not Jest. Test filtering options like `--testPathPattern` from Jest are not available. To run specific tests, you can temporarily modify the `files` pattern in `web-test-runner.config.js` or use pattern matching if supported by your Web Test Runner version. For most cases, running all tests is recommended as the test suite is optimized for speed.
+
 ## Global Test Utilities
 
 The setup provides global utilities accessible via `window.testUtils`:

package/test/md/dialog/UiConfirmDialog.test.ts

@@ -0,0 +1,131 @@
+import { fixture, html, assert } from '@open-wc/testing'
+import '../../../src/md/dialog/ui-confirm-dialog.js'
+import type UiConfirmDialog from '../../../src/md/dialog/internals/ConfirmDialog.js'
+
+describe('UiConfirmDialog', () => {
+  async function basicFixture(): Promise<UiConfirmDialog> {
+    return fixture(html`<ui-confirm-dialog></ui-confirm-dialog>`)
+  }
+
+  async function customLabelsFixture(): Promise<UiConfirmDialog> {
+    return fixture(html`<ui-confirm-dialog confirmLabel="Delete" dismissLabel="Keep"></ui-confirm-dialog>`)
+  }
+
+  async function withContentFixture(): Promise<UiConfirmDialog> {
+    return fixture(html`
+      <ui-confirm-dialog>
+        <span slot="title">Confirm Action</span>
+        <p>Are you sure you want to proceed?</p>
+      </ui-confirm-dialog>
+    `)
+  }
+
+  async function destructiveFixture(): Promise<UiConfirmDialog> {
+    return fixture(html`<ui-confirm-dialog destructive></ui-confirm-dialog>`)
+  }
+
+  it('renders with default labels', async () => {
+    const element = await basicFixture()
+    assert.equal(element.confirmLabel, 'Confirm')
+    assert.equal(element.dismissLabel, 'Cancel')
+  })
+
+  it('renders with custom labels', async () => {
+    const element = await customLabelsFixture()
+    assert.equal(element.confirmLabel, 'Delete')
+    assert.equal(element.dismissLabel, 'Keep')
+  })
+
+  it('is modal by default', async () => {
+    const element = await basicFixture()
+    assert.isTrue(element.modal)
+  })
+
+  it('renders buttons with correct values', async () => {
+    const element = await basicFixture()
+    await element.updateComplete
+
+    const dismissButton = element.shadowRoot!.querySelector('ui-button[value="dismiss"]')
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+
+    assert.ok(dismissButton, 'has dismiss button')
+    assert.ok(confirmButton, 'has confirm button')
+    assert.equal(dismissButton!.textContent!.trim(), 'Cancel')
+    assert.equal(confirmButton!.textContent!.trim(), 'Confirm')
+  })
+
+  it('renders title slot', async () => {
+    const element = await withContentFixture()
+    await element.updateComplete
+
+    const titleSlot = element.shadowRoot!.querySelector('slot[name="title"]')
+    assert.ok(titleSlot, 'has title slot')
+  })
+
+  it('renders body slot', async () => {
+    const element = await withContentFixture()
+    await element.updateComplete
+
+    const bodySlot = element.shadowRoot!.querySelector('slot:not([name])')
+    assert.ok(bodySlot, 'has body slot')
+  })
+
+  it('uses filled button for confirm action', async () => {
+    const element = await basicFixture()
+    await element.updateComplete
+
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+    assert.equal(confirmButton!.getAttribute('color'), 'filled')
+  })
+
+  it('uses text button for dismiss action', async () => {
+    const element = await basicFixture()
+    await element.updateComplete
+
+    const dismissButton = element.shadowRoot!.querySelector('ui-button[value="dismiss"]')
+    assert.equal(dismissButton!.getAttribute('color'), 'text')
+  })
+
+  it('renders as destructive dialog', async () => {
+    const element = await destructiveFixture()
+    await element.updateComplete
+
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+    assert.ok(confirmButton?.classList.contains('destructive'), 'confirm button has destructive class')
+  })
+
+  it('renders confirm button with destructive styling', async () => {
+    const element = await destructiveFixture()
+    await element.updateComplete
+
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+    assert.equal(confirmButton!.getAttribute('color'), 'filled')
+    assert.ok(confirmButton!.classList.contains('destructive'), 'has destructive class for styling')
+  })
+
+  it('is not destructive by default', async () => {
+    const element = await basicFixture()
+    assert.isFalse(element.destructive)
+  })
+
+  it('can be set to destructive', async () => {
+    const element = await destructiveFixture()
+    assert.isTrue(element.destructive)
+  })
+
+  it('applies destructive class to confirm button when destructive is true', async () => {
+    const element = await destructiveFixture()
+    await element.updateComplete
+
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+    assert.isTrue(confirmButton!.classList.contains('destructive'))
+  })
+
+  it('does not apply destructive class when destructive is false', async () => {
+    const element = await basicFixture()
+    await element.updateComplete
+
+    const confirmButton = element.shadowRoot!.querySelector('ui-button[value="confirm"]')
+    assert.isFalse(confirmButton!.classList.contains('destructive'))
+  })
+})

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

@@ -145,6 +145,26 @@ describe('md', () => {
         await element.updateComplete
         assert.isTrue(spy.calledOnce)
       })
+
+      it('applies modal class to dialog when modal is true', async () => {
+        const element = await basicFixture()
+        element.modal = true
+        await element.updateComplete
+
+        const dialog = element.shadowRoot!.querySelector('dialog') as HTMLDialogElement
+        assert.ok(dialog, 'has the dialog element')
+        assert.isTrue(dialog.classList.contains('modal'), 'has modal class')
+      })
+
+      it('applies non-modal class to dialog when modal is false', async () => {
+        const element = await basicFixture()
+        element.modal = false
+        await element.updateComplete
+
+        const dialog = element.shadowRoot!.querySelector('dialog') as HTMLDialogElement
+        assert.ok(dialog, 'has the dialog element')
+        assert.isTrue(dialog.classList.contains('non-modal'), 'has non-modal class')
+      })
     })
 
     describe('icon', () => {
@@ -229,6 +249,28 @@ describe('md', () => {
         const container = element.shadowRoot!.querySelector('.buttons') as HTMLElement
         assert.isTrue(container.classList.contains('with-buttons'), 'has the with-buttons class')
       })
+
+      it('applies destructive class to confirm button when destructive is true', async () => {
+        const element = await basicFixture()
+        element.confirmLabel = 'Delete'
+        element.destructive = true
+        await element.updateComplete
+
+        const button = element.shadowRoot!.querySelector('.internal-button[value="confirm"]') as UiButton
+        assert.ok(button, 'has the confirm button')
+        assert.isTrue(button.classList.contains('destructive'), 'has destructive class')
+      })
+
+      it('does not apply destructive class when destructive is false', async () => {
+        const element = await basicFixture()
+        element.confirmLabel = 'Confirm'
+        element.destructive = false
+        await element.updateComplete
+
+        const button = element.shadowRoot!.querySelector('.internal-button[value="confirm"]') as UiButton
+        assert.ok(button, 'has the confirm button')
+        assert.isFalse(button.classList.contains('destructive'), 'does not have destructive class')
+      })
     })
 
     describe('form handling', () => {