type: utility

release: 0.0

status: in development

documentation: N/A

demo:  n/a

1 - Description:

The modal utility is used in situations where we want to lock the user's input into a single element on the screen. The most common example is a modal dialog or lightbox.

The modal plugin is called on the DOM element or widget that is to be placed on top of the page as an overlay.  

The modal plugin does three things:

1. Takes the element that this was called on and places it above everything else in the page stacking order (z-index) and centers it horizontally and vertically in the viewport by default (via the position utility?). What happens if this is larger than the viewport?
2. Prevents the user from interacting with the page below by mouse or keyboard. This is a complex process that has performance issues in the current code used for the dialog so work needs to be done to optimize this so the process of disabling and enabling the page below the overlay is responive on large complex pages in IE.
3. Display an overlay layer (optional) that covers the entire page to visually to dim the page below and provide an affordance that the base page is unavailable. There is a CSS framework class in place to style this overlay layer called ui-widget-overlay which sets the color, texture, and overlay opacity. This plugin should not write inline styles that will interfere with theming.

Potential additional features:

• disable the page scrollbar if the overlay is shown (false by default)
• map the Esc key to close the overlay (false by default)

2 - Visual Design:

3 - Functional Specifications/Requirements:

Options:

• overlay (boolean, default: true)
• overlays the page with a semi-transparent element (based on ui-widget-overlay class) 

Methods:

• open
• show the modal
• close
• hide the modal

Events:

• beforeopen
• before opening the modal, cancellable
• open
• after the modal is opened
• beforeclose
• before closing the modal, cancellable
• close
• after the modal is closed

4 - Markup & Style:

     4.1 Initial markup examples

     4.2 Recommended transformed HTML markup

     4.3 Accessibility recommendation

Accessibility recommendations needed.

     4.4 CSS & Theme

5 - Latest version of plugin:

TBD

6 - Open issues being discussed

This plugin is currently being planned and in early stages of development.