Dialog 1.2.2

<velin-dialog> wraps the native <dialog> element with a promise-based alert() / confirm() / prompt() API. In 1.2.0 it dispatches canonical velin-close (and keeps deprecated velin-dialog-close as an alias). Deutsch: Dialog De

Maturity: Documented as stable in VelinStyle 1.2.0. Design Intelligence (plan / review / agent meta) is separate and beta / foundation where noted.

When to use

Imperative confirmations, alerts, and short text prompts from JavaScript.
Flows where you await a boolean / string result instead of building custom modal markup.

When not

Custom layouts, forms, or footer actions — use <velin-modal>.
Non-modal feedback — use Toasts or Alerts.
Do not expect focus-manager inert stacking here; native showModal() owns modality.

Basic example

<velin-dialog id="myDialog" aria-label="App dialog"></velin-dialog>

<script>
  const dlg = document.getElementById('myDialog');

  // Alert — resolves to true
  await dlg.alert('Hello!');

  // Confirm — resolves to boolean
  const ok = await dlg.confirm('Delete this item?', {
    title: 'Confirm delete',
    danger: true
  });

  // Prompt — resolves to string or null if cancelled
  const name = await dlg.prompt('What is your name?', {
    placeholder: 'Enter name…',
    defaultValue: 'World'
  });

  dlg.addEventListener('velin-close', (e) => {
    console.log('closed with', e.detail.value);
  });
</script>

Accessibility

Uses native <dialog>.showModal() — browser focus trap and ::backdrop.
While open: aria-modal="true" and aria-labelledby pointing at the generated title.
Host may set an initial aria-label; it is replaced by aria-labelledby when a dialog is shown.
Close control has aria-label="Close". Escape is handled via the dialog cancel event (preventDefault + dismiss).
Prompt focuses the input; Enter confirms. Non-prompt types focus the first action button.
Previous focus is restored after dismiss. Message and labels are HTML-escaped before render.

Dark, responsive, motion, RTL

Dark / themes: dialog chrome uses surface, border, primary, danger, and focus tokens.
Responsive: max-inline-size: min(28rem, 90vw).
Motion: no enter/exit animation beyond the browser dialog behavior.
RTL: footer and header use logical flex alignment.

API

Methods

Method	Returns	Description
`alert(message, options?)`	`Promise<true>`	Alert dialog
`confirm(message, options?)`	`Promise<boolean>`	Confirm dialog
`prompt(message, options?)`	`Promise<string\|null>`	Prompt (null if cancelled)

Options

Option	Default	Description
`title`	varies by method	Title text
`confirmText`	`"OK"` / `"Confirm"` / `"Submit"`	Confirm label
`cancelText`	`"Cancel"`	Cancel label (confirm/prompt)
`danger`	`false`	Danger-styled confirm (confirm)
`placeholder`	`""`	Prompt placeholder
`defaultValue`	`""`	Prompt default value

Events

Event	Detail	Description
`velin-close`	`{ value }`	Canonical close event (ADR 0012) — prefer this
`velin-dialog-close`	`{ value }`	Deprecated alias; still dispatched for one deprecation window

CSS parts & variables

Name	Description
`part="dialog"`	Native dialog element
`part="input"`	Prompt input
`--velin-radius-lg`, `--velin-shadow-xl`, `--velin-color-surface-bright`, `--velin-color-border`, `--velin-color-primary`, `--velin-color-danger`, `--velin-color-focus`	Theming tokens used in shadow styles

Best practices & pitfalls

Keep one <velin-dialog> on the page and reuse it; concurrent alert/confirm/prompt calls share a single resolve slot.
Listen for velin-close; migrate off velin-dialog-close.
Unlike modal/drawer/sheet/lightbox, this component does not call setBackgroundInert — rely on native modal dialog behavior.
Do not put arbitrary HTML in message/title; content is escaped as text.

Modal — custom dialog UI with focus-manager lifecycle
Toasts — non-blocking notifications
Sheet — bottom sheet overlay