import { Meta } from '@storybook/addon-docs';

<Meta title="API/Modals/Intro" parameters={{ previewTabs: { canvas: { hidden: true } } }} />

# Modals

A modal is a popup that darkens the background and has focus lock. There are two types of modals: "dialog" and "sidebar".

**Dialog modals** appears in the middle of the screen.
| option | values |
|:------:|:--------------------------:|
| No options yet | |

**Sidebar modals** slides in from the right.
| option | values |
|:------:|:--------------------------:|
| size | small, medium, large, full |

## Basic Usage

### Consume UmbModalService from an element

The UmbModal service can be used to open modals.

```ts
import { html, LitElement } from 'lit';
import { UmbLitElement } from '@umbraco-cms/element';
import { UmbModalService, UMB_MODAL_SERVICE_CONTEXT_ALIAS } from './core/services/modal';
class MyElement extends UmbLitElement {
	private _modalService_?: UmbModalService;
	constructor() {
		super();
		this.consumeContext(UMB_MODAL_SERVICE_CONTEXT_ALIAS, (modalService) => {
			this._modalService = modalService;
			// modalService is now ready to be used.
		});
	}
}
```

### Open a modal

A modal is opened by calling one of the helper methods on the UmbModalService. The methods will accept an element template and modal options and return an instance of UmbModalHandler.

```ts
import { html, LitElement } from 'lit';
import { UmbLitElement } from '@umbraco-cms/element';
import { UmbModalService, UMB_MODAL_SERVICE_CONTEXT_ALIAS } from './core/services/modal';
class MyElement extends UmbLitElement {
	private _modalService?: UmbModalService;
	constructor() {
		super();
		this.consumeContext(UMB_MODAL_SERVICE_CONTEXT_ALIAS, (modalService) => {
			this._modalService = modalService;
			// modalService is now ready to be used
		});
	}
	private _handleClick() {
		const options = {'options goes here'}
		const modalHandler = this._modalService?.openDialog('my-dialog'), options);
		modalHandler.onClose().then((data) => {
			// if any data is supplied on close, it will be available here.
		});
	}
	render() {
		return html`<button @click=${this._handleClick}>Open modal</button>`;
	}
}
```

The dialog template to open:

```ts
import { html, LitElement } from 'lit';
import type { UmbModalHandler } from './core/services/modal';
class MyDialog extends LitElement {
	// the modal handler will be injected into the element when the modal is opened.
	@property({ attribute: false })
	modalHandler?: UmbModalHandler;

	private _handleClose() {
		/* Optional data of any type can be applied to the close method to pass it
		   to the modal parent through the onClose promise. */
		this._modalHandler?.close('optional data');
	}

	render() {
		return html`
			<div>
				<h1>My Dialog</h1>
				<button @click=${this._handleClose}>Close</button>
			</div>
		`;
	}
}
```
