# Dialog


## Examples

### Default

```html
<m-button id="default-button">Open Modal</m-button>
    <m-dialog
      .open=${args.open}
      .closable=${args.closable}
      .hideTitle=${args.hideTitle}
      size=${args.size}
      variant=${args.variant}
      .modal=${args.modal}
      @close=${args.onclose}
      id="default-dialog"
    >
      <span slot="header">Modal Header</span>
      <p>Default content of the modal</p>
      <p>Default content of the modal</p>
      <p>Default content of the modal</p>
      <p><button>Focusable element</button></p>
      <m-button-group slot="footer" alignment="right">
        <m-button id="default-cancel">Cancel</m-button>
        <m-button id="default-confirm" variant="primary">Confirm</m-button>
      </m-button-group>
    </m-dialog>
    <script>
      const openModalButton = document.querySelector("#default-button");
      const modal = document.querySelector("#default-dialog");
      const cancelButton = document.querySelector("#default-cancel");
      const confirmButton = document.querySelector("#default-confirm");

      openModalButton.addEventListener("click", () => {
        modal.openModal();
      });

      cancelButton.addEventListener("click", () => {
        console.log("cancel");
        modal.closeModal();
      });

      confirmButton.addEventListener("click", () => {
        modal.closeModal();
      });
    </script>
```

### WithoutFooter

```html
<m-button id="without-button">Open Modal</m-button>
    <m-dialog
      .open=${args.open}
      .closable=${args.closable}
      size=${args.size}
      .hideTitle=${args.hideTitle}
      .modal=${args.modal}
      id="without-dialog"
    >
      <span slot="header">Modal Header</span>
      <p>Default content of the modal</p>
    </m-dialog>
    <script>
      const withoutButton = document.querySelector("#without-button");
      const withoutDialog = document.querySelector("#without-dialog");

      withoutButton.addEventListener("click", () => {
        withoutDialog.openModal();
      });
    </script>
```

## Usage

Use the Dialog component for:

- Modal Dialogs: When you need to interrupt workflow for critical actions or confirmations (e.g., “Are you sure you want to delete this?”).
- Menu Pop-ups: For non-disruptive options or actions related to a selected item or section, such as context menus or dropdowns.
- Information Panels: When additional information or user input is required, but not critical, such as quick forms or read-only details.

## Focus Management

The dialog implements a focus management system that follows these rules:

1. When opened, the dialog will try to find and focus elements in this order:
   - First element with `autofocus` and `tabindex="-1"` attributes in the content
   - If no autofocus element is found, falls back to the dialog title

### Example with autofocus

```html
<m-dialog>
  <span slot="header">Dialog Title</span>
  <h1 autofocus tabindex="-1">This heading will receive focus</h1>
  <p>Other content...</p>
</m-dialog>
```

### Example without autofocus

```html
<m-dialog>
  <span slot="header">Dialog Title</span>
  <p>The dialog title will receive focus</p>
</m-dialog>
```

This focus management system ensures proper accessibility by:

- Providing immediate context to screen reader users
- Preventing unwanted page scrolling
- Following WCAG 2.2 guidelines for modal dialogs

## Other Considerations

- Clear and Concise Content: Use clear titles and concise content to ensure users understand the dialog’s purpose immediately.
- Descriptive Button Labels: Use clear, action-oriented labels like “Save” or “Delete.”
- Minimal Disruption: Use non-modal dialogs for light interactions or additional options to avoid workflow interruptions.

## Design rationale

**Top-of-Viewport Positioning:**
The modal dialog is anchored at the top of the viewport to improve accessibility and predictability, especially for content that changes in size (dynamic content). This stable positioning prevents content "jumping" and minimizes the need for repositioning, helping users easily locate, read, and focus on the dialog content.

**2-Button rule for modal actions:**
The modal dialog footer should contain no more than two primary actions to keep the user experience clear and focused. If more than two actions are required, consider these alternatives:

1. Place Additional Actions in the Dialog Body: Add secondary actions within the content area if they provide context-specific options (e.g., “View Details” or “Learn More”).
2. Use Advanced Button Components: For related actions, consider an advanced button, like a split button, which combines a main action with a dropdown for additional subactions.

This approach ensures simplicity and helps users quickly identify key actions in the modal.