Add <dialog> and its associated API

Summary

Web authors have created many in-page dialog boxes—both modal and non-modal—with a combination of markup, script, and styling, but often the techniques used inadvertantly create usability and accessibility problems. Adding an in-page dialog feature to the Web platform will help authors avoid these problems while simultaneously making it easier for them to acheive their goals.

This is for ISSUE-133 (modal-attribute).

Rationale

There are many examples of in-page dialog boxes on the Web today. For instance, many websites' login forms are in such dialogs. Most of these can be categorized into two kinds: modal and non-modal.

In-page modal dialogs

Typically, in-page modal dialogs are centered within the viewport, and the rest of the page is somehow shaded out or otherwise diminished via styling. In some cases, clicks in the diminished area of the page dismiss the dialog; in other cases, such clicks are ignored. In either case, clicks in the diminished area are not propagated to the underlying page content.

In-page non-modal dialogs

In-page non-modal dialogs generally differ from their modal siblings in two respects: the underlying page content is not diminished, and they are usually positioned relative to some specific location in the page (possibly an element, or perhaps the mouse position where the user invoked the dialog).

Responses to anticipated objections

This doesn't have feature parity with jQuery UI Dialog or other such libraries

• This is by design. The intent is to provide a basis for such libraries' dialog features, and not a replacement for them. For instance, this proposal doesn't describe user interface elements such as a dialog titlebar, close button, and so on.

Objections to Add a modal feature to HTML5

• Whether or not a modal is currently being displayed should not be controled from a content attribute. How to process such content attributes is entirely unclear. What if there are several elements all with this attribute present? Who wins?

Details

While the below is not "camera-ready" spec text, I believe it is sufficiently detailed for the editor to make sufficient edits.

<dialog>

In § 4.11 Interactive elements, add a new subsection defining the <dialog> element. This element is a sectioning root, and may be used wherever flow content is expected. Its content model is flow content. For attributes, it takes the Global attributes as well as a new boolean attribute modal="", described below.

By default, <dialog> elements are hidden, and are displayed to the user only if their .show() method (described below) is called.

modal=""

A boolean attribute. When present, this indicates that the dialog is modal. If not present, the dialog is non-modal.

In §3.2.7 WAI-ARIA, the language feature <dialog modal> should be specified to have the strong native semantics equivalent to role="dialog"

:open

This pseudoclass matches dialogs which are currently being shown to the user.

The Backdrop

There needs to be a way to seelct the object under the dialog used to cover the rest of the page. Exactly how such an object is selected for, how it is positioned, and other details belong in the CSS UI module and are out of scope for the HTML specification. I have proposed this feature to the CSS WG in this email.

.returnValue

A string. Set by the author by calling the dialog's .close() method, described below. Examined by authors from within close event handlers to determine the action the user has taken within the dialog.

HTMLDialogElement.show([anchor])

When called, this causes the dialog to be shown to the user. If the dialog is non-modal, .show() takes an optional Element or MouseEvent to be used as the positioning anchor. Precisely how a non-modal dialog is positioned relative to this anchoring element or event should be taken up with the CSS WG.

If the dialog is modal, page content outside of the dialog must be made unfocusable while the dialog is displayed.

If the dialog is modal, it is absolutely positioned with explicit top and left/right (depening on the prevailing directionality of the page) so that its margin box is centered in the viewport, but its margin top edge must not be placed above the top of the viewport. Script can move the dialog around by altering its top and left/right CSS properties.

By default, pressing the Escape key in a dialog fires its 'cancel' event. This can be prevented from within a 'keyup' or 'keypressed' event handler.

HTMLDialogElement.close([returnValue])

Sets the dialog's returnValue IDL attribute as specified, hides the dialog from the user, and fires a close event on the dialog. Authors may inspect the dialog's returnValue from within an event handler.

clickoutside

This event occurs in modal dialogs when a user clicks on the backdrop. Unless this event is cancelled, a 'cancel' event is fired at the dialog. Exactly how to wire this event up to the backdrop depends on how the backdrop feature gets specified in the CSS UI module.

cancel

This event indicates that the user has cancelled the dialog. Unless this event is cancelled, the dialog will be closed and a 'close' event fired.

close

This event indicates that the user has closed the dialog. Handlers for this event may inspect the dialog's returnValue IDL attribute to determine the outcome.

Impact

Specification of the :open pseudo-class, the backdrop, and the positioning of non-modal dialogs needs to be coordinated with the CSS WG.

Positive Effects

• Helps authors create accessible in-page dialogs with less markup and script.

Negative Effects

• Because of the similarity in terms used, authors may confuse this feature with showModalDialog().

Conformance Classes Changes

• <dialog> is allowed wherever flow content is allowed.

Risks

• The CSS WG may decline to specify a positioning feature for anchoring non-modal dialogs to positions on the page, the :open pseudo-class, or the concept of the backdrop.
• Authors of dialog libraries may choose not to build on top of this feature. We should endeavor to get feedback on this design from that community, so we can quickly iterate with their input.

References

Most references inline.

• Dialog research page on the WHATWG Wiki