# `<btu-dialog>` Web Component

This is a web component that adds functionality to the native `<dialog>` element.

In Java, you can use this as a custom Dari HTML component like:

```
import static com.psddev.cms.ui.Components.*;

.add(DIALOG.with(DIV.with("this is the content of the dialog...")));
```

or in HTML:

```
<btu-dialog><div>This is the content</div></btu-dialog>
```

or Typescript/JS:

```
import Dialog from 'dialog/index'

const dialog = new Dialog()
dialog.append(document.createElement('div'))
document.appendChild(dialog)
```

## Properties

| Name            | Attribute       | Type (default)                           | Description                                                                                                                                                                                                                                              |
| --------------- | --------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoOpen`      | auto-open       | boolean (true)                           | Opens the dialog immediately after it is attached to the DOM.                                                                                                                                                                                            |
| `enterFrom`     | enter-from      | 'left' \| 'right' \| 'center' ('center') | Indicates the direction from which the popup enters. Automatically detected from Popup classes (`is-fromLeft`, `is-fromRight`). This property is reflected to the DOM as an attribute for CSS targeting.                                                 |
| `id`            | id              | uuid (automatic)                         | A unique UUID is generated for each dialog when it is attached to the DOM.                                                                                                                                                                               |
| `loaded`        | loaded          | boolean (false)                          | Indicates whether the Popup is fully loaded and ready. Automatically set to `true` when the Popup has the classes `loaded`, `is-ready`, and `is-visible`. This property is reflected to the DOM as an attribute and is used to hide the loading spinner. |
| `removeOnClose` | remove-on-close | boolean (true)                           | Removes the dialog from the DOM after it closes.                                                                                                                                                                                                         |

## Methods

| Name      | Params          | Description                                                                                                                                |
| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `close()` | Event(optional) | Closes the dialog after checking for unsaved changes and prompting for confirmation if needed. Emits `btu-dialog-closed` event on success. |
| `show()`  | none            | Shows the dialog.                                                                                                                          |

## Events

| Name                | Description                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| `btu-dialog-closed` | Indicates that the request to close the dialog was successful and it is now closed. |
| `btu-dialog-ready`  | Indicates that the dialog is connected to the DOM.                                  |

## Dialog Popup sizes

Dialog modals have a default size that can be overridden via CSS by the `data-popup-size` attribute with the following values:

- `sm`: For popups smaller than default size
  - 100cqw x 45cqh for mobile devices
  - 65cqw x 45cqh for tablet devices
  - 55cqw x 45cqh for desktop
- `lg`: For popups larger than default size
  - 100cqw x 100cqh for mobile devices
  - 90cqw x 100cqh for tablet devices
  - 80cqw x 100cqh for desktop
- `auto-height`: For popups with content less than `sm` size, the height will be determined by the content, but the width will be default values.

## Performance Optimizations

To avoid expensive CSS `:has()` selectors, the dialog component automatically annotates its DOM with context classes. These classes are added via JavaScript when relevant elements are detected, allowing CSS to use simple class selectors instead of complex `:has()` queries.

### Context Classes

The following classes are automatically added to elements within modal dialogs:

| Class                  | Applied To                                           | Condition                                                                                                                                       |
| ---------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `has-ActionBar`        | `.Popup-content`                                     | Contains an `.ActionBar` element (and not in editing mode or Admin nav context)                                                                 |
| `has-AdminNav`         | `.Popup-content`                                     | Contains `.Admin .Admin-nav` elements                                                                                                           |
| `has-ActionBarContent` | Ancestor elements                                    | Contains an `.ActionBar` with substantive content (not just `ImageEditor-closeButton`)                                                          |
| `has-StatusMessage`    | Ancestor elements                                    | Contains success, error, or info messages (`.Message.is-success`, `.Widget-title + .Message.is-error`, `.Widget-title + .Message.message-info`) |
| `before-ActionBar`     | `form`, `.TC`, `.AIChat-wrapper`, `.fixedScrollable` | Element immediately precedes an `.ActionBar`                                                                                                    |

These classes are managed automatically through a `MutationObserver` that watches for dynamically added content and updates annotations accordingly. The observer is properly cleaned up when the dialog is removed from the DOM to prevent memory leaks.
