npm package: @outbook/webcomponents-modal-dialog
Description: Web components modal-dialog
Author: Antonio Rodríguez
Latest version: 1.1.0

# @outbook/webcomponents-modal-dialog

This package provides a modal dialog component with two built-in layouts:

- `content`: full-screen content dialog
- `message`: centered message dialog with veil

The package is intended to be used through the `ModalDialog()` wrapper, which creates, renders, and removes the dialog for you.

## Installation

```bash
npm install @outbook/webcomponents-modal-dialog
```

## Usage

### Content Dialog

```javascript
import { html } from 'lit';
import { ModalDialog } from '@outbook/webcomponents-modal-dialog';

function openExampleModal(ev) {
  ModalDialog({
    origin: ev.currentTarget.id,
    title: 'Example modal',
    type: 'content',
    view: ({ closeDialog }) => html`
      <p>This is the content of the modal dialog.</p>
      <button @click="${closeDialog}">Close</button>
    `
  });
}

function render() {
  return html`
    <button id="open-modal" @click="${openExampleModal}">
      Open modal
    </button>
  `;
}
```

### Message Dialog With Actions

```javascript
import { html } from 'lit';
import { ModalDialog } from '@outbook/webcomponents-modal-dialog';

const saveAction = ({ detail }) => {
  console.log('button interaction:', detail.originalEvent.type);
};

function openMessageModal(ev) {
  ModalDialog({
    origin: ev.currentTarget.id,
    title: 'Confirm action',
    type: 'message',
    view: () => html`
      <p>Do you want to save your changes?</p>
    `,
    actions: [
      {
        text: 'Save',
        type: 'positive',
        eventFn: saveAction
      },
      {
        text: 'Cancel',
        type: 'neutral',
        handler: 'close'
      }
    ]
  });
}
```

## API

### `ModalDialog(props)`

Creates and renders an `outbook-modal-dialog`.

| Property | Type | Default | Description |
|---|---|---|---|
| `origin` | `String` | `undefined` | Id of the element that opened the dialog. Focus is returned to this element when the dialog closes. |
| `title` | `String` | `undefined` | Dialog title shown in the header. |
| `type` | `String` | `'content'` | Dialog layout. Supported values are `'content'` and `'message'`. |
| `view` | `Function` | `null` | Function that returns the dialog body. Receives `{ closeDialog }`. |
| `tabs` | `Array` | `[]` | Tab configuration passed to `@outbook/webcomponents-tabs`. If present, it is rendered instead of `view`. |
| `hasScroll` | `Boolean` | `true` | Enables scrolling for `content` dialogs. Ignored for `message` dialogs and for dialogs with tabs. |
| `actions` | `Array` | `[]` | Footer button configuration. |
| `portalWrapperId` | `String` | `null` | Optional container element id for rendering the dialog portal. Defaults to `document.body`. |
| `content` | `Function` | `undefined` | Optional fallback slot content renderer used internally by the component. |

### `actions`

Each action item supports the following properties:

| Property | Type | Default | Description |
|---|---|---|---|
| `text` | `String` | `undefined` | Button label. |
| `type` | `String` | `'neutral'` | Visual variant. Supported values are `'neutral'`, `'positive'`, and `'negative'`. |
| `handler` | `String` | `undefined` | Name of an internal dialog handler. Currently `close` is supported. |
| `eventFn` | `Function` | `() => {}` | Handler for the button `button-interaction` event when no `handler` is defined. |

Action handler resolution order:

1. `handlers[handler]`
2. `eventFn`
3. empty function

When `handler: 'close'` is used, the dialog closes and focus returns to `origin`.

## Component

### `outbook-modal-dialog`

This is the underlying custom element used by `ModalDialog()`. It is not usually instantiated directly, because the wrapper manages portal rendering, lifecycle, keyboard handling, and focus return.

## Styling

The component uses Shadow DOM and exposes styling hooks through CSS custom properties.

### Custom Properties

| Custom Property | Description |
|---|---|
| `--outbook-modal-dialog--veil-color` | Veil color behind the dialog. Used by `message` dialogs. |
| `--outbook-modal-dialog--neutral-background` | Background color for neutral action buttons. |
| `--outbook-modal-dialog--neutral-background-hover` | Hover background color for neutral action buttons. |
| `--outbook-modal-dialog--positive-background` | Background color for positive action buttons. |
| `--outbook-modal-dialog--positive-background-hover` | Hover background color for positive action buttons. |
| `--outbook-modal-dialog--negative-background` | Background color for negative action buttons. |
| `--outbook-modal-dialog--negative-background-hover` | Hover background color for negative action buttons. |

The dialog also forwards `--outbook-scrollable--indicator-max-width` internally for the scrollable content area.

## Notes

- `type: 'content'` renders a full-screen dialog layout.
- `type: 'message'` renders a centered dialog with a veil overlay.
- The close button responds to mouse click, `Enter`, and `Space`.
- `Escape` closes the dialog.

## License

This component is licensed under the Apache-2.0 License.