This specification extension defines elements and attributes for constructing a panel or collection of panels based on a single interaction paradigm.
Using custom elements, a collection of functional prototypes is available. All DOM methods are under-scored to preserve forwards compatibility.
Work on this extension is being done on Github. Please share comments and feedback using the Github issue tracker.
Introduction
The concept of a content panel originates in print media and has carried over into digital media. The transition to digital media brought about the ability to interact with collections of panels, and over time a number of visual metaphors for this interaction have emerged. Tabs, accordions, decks and carousels are all design patterns based on interactions with sets of content panels.
The history of interface design shows that each of these design patterns has evolved independently, despite their similarities. The WAI-ARIA Authoring Practices Guide for example, describes a set of tabs and an accordion widget in identical terms except for visual orientation.
With the growing number of screen sizes and the advent of responsive design, these visual metaphors may no longer be constant. A set of tabs may be the logical choice for displaying content on a wide-screen, but the same content may be more intuitively displayed as an accordion or a deck on a narrow-screen. However, the interaction model and semantic information for each of these design patterns remains the same, regardless of the visual representation.
This extension defines a set of HTML elements and attributes for representing collections of content panels with appropriate semantics and interactions. The task of adopting a particular visual metaphor is left to CSS.
Conformance
All authoring guidelines, diagrams, examples, notes, and sections marked "informative" in this specification are informational. Everything else in this specification is "normative" as described in [[!qaframe-spec]]. The key words "must", "should", "should not" and "may" in this specification are to be interpreted as described in [[!RFC2119]].
Dependencies and Definitions
The Interface Definition Language (IDL) fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [[!WEBIDL]]
This document uses the terms accessible and accessibility in the sense of ensuring people with disabilities can use the Web.
Use cases and Requirements
The panels specification describes a number of elements and attributes that give authors the ability to present panels or collections of panels in a semantically consistent way.
Use Cases for Panels and Panel Sets
Use cases for the tab set metaphor
Displaying semester timetables for the school year on a college intranet.
Displaying nutritional values, ingredients, allergy warnings etc. about a food product on a grocery store website.
Displaying configuration settings, statistics, performance data etc. about a software deployment pipeline on a continuous build server.
Displaying descriptions, details, floor plans etc. about a house for sale on a property website.
Displaying alternative representations of data (graphical and tabular) in an analytics web application.
Use cases for the accordion metaphor
Displaying bulletin board messages on an office intranet.
Displaying an A to Z of glossary definitions on a medical research website.
Displaying answers to frequently asked questions for newbies on a gamer’s forum.
Use cases for the carousel metaphor
Displaying bulletin board messages on an office intranet.
Displaying attractive pictures of a spa resort on a vacation brochure website.
Advertising key features of a prototype flying car on the company’s corporate website.
Use cases for the coverflow metaphor
Flipping through an album of sky dive photos on a photo sharing website.
Browsing a portfolio of watercolours on an artist’s brochure website.
Use cases for the deck metaphor
Displaying a slide deck from a conference talk.
Storing contact information in a rolodex application.
Viewing pictures of a spa resort's vacation brochure website on a small device.
Flipping through an album on a photo sharing website.
Browsing a portfolio of watercolours on an artist’s brochure website.
Advertising key features of a prototype flying car on the company’s corporate website, for display on a small device.
Presenting a series of comic panel mock-ups, each representing a significant moment in the overall narrative.
Requirements for Panels and Panel Sets
Consistent
It must be possible to interact with a panel or set of panels in a consistent way, using different modes of interaction including keyboard, mouse, voice and touch.
Identifiable
It must be possible for a user agent to identify the components of a panel, and the component panels within a set.
Stylable
It must be possible to style a panel or set of panels to provide different visual affordances.
A panel element represents a chunk of content with a header that includes a visible title (paneltitle element). A panel element may be used on its own, or with other panel elements as part of a collection (panelset element).
Github issue 16
It isn't presently possible to imperitively create a panel element.
Github issue 9
Should it be possible to script a panel element to become either removable or expandable?
Github issue 32
Is panel-title a required child of panel element?
Github issue 33
why not re-use open attribute instead of expandable?
A paneltitle element represents the visible title of a panel (panel element). A paneltitle is the basic component of the panel header.
panel element with paneltitle element
<panel>
<paneltitle>Favourite books</paneltitle>
<p>Here is a list of my favourite books:</p>
<ul>
<li>Hitchhiker's Guide to the Galaxy</li>
<li>Pride and Prejudice</li>
<li>Green Eggs and Ham</li>
</ul>
</panel>
A panelset element represents a collection of panels (panel elements). A panelset may contain one or more panel elements.
The panelset element manages the selection of its child panel elements. In other words, when panel elements are children of a panelset element, they are automatically collapsible.
The first panel element within a panelset element should be expanded by default. Any subsequent claims of expansion trump the original claim.
panelset element containing multiple panel elements
<panelset>
<panel>
<paneltitle>Tequila Chamucos</paneltitle>
<p>Chamucos reposado tequila is preserved in white oak barrels for...</p>
</panel>
<panel>
<paneltitle>Gran Patron Platinum</paneltitle>
<p>Gran Patron Platinum tequila is distilled three times...</p>
</panel>
<panel>
<paneltitle>Jose Cuervo 1800 Coleccion</paneltitle>
<p>Jose Cuervo 1800 is reputed to be the second most expensive tequila...</p>
</panel>
</panelset>
Github issue 5
Should the panelset element have selectedIndex?
Github issue 25
If HTML authors are encouraged to follow this separation, it inevitably begs the question about how CSS authors can correctly manage which type of display the element takes on in which conditions. This is currently "up in the air". One approach, prollyfilled here, is to use an attribute.
Github issue 19
Different visual metaphors have different selection (expansion) patterns. How can this be managed if the panelset element is predicated on a single selection model?
Github issue 28
When an AT is enabled on a touch device, only basic events are fired (mouse events, and in some circumstances blur/focus events). Is this something to consider?
The removable attribute
The removable attribute is a Boolean attribute that indicates that a panel element can be removed from the user interface. When a panel element is dismissed from the user interface, it is removed from the DOM.
When the removable attribute is present, a mechanism to dismiss the panel is included in the panel element header.
panel element with the removable attribute.
<panel removable>
<paneltitle>Reminder</paneltitle>
<p>
Today is the first day of the rest of your life.
</p>
</panel>
The expandable attribute
The expandable attribute indicates the expanded or collapsed state of a panel element.
When the expandable attribute is present, the paneltitle element becomes a control that allows the panel element to be toggled between an expanded or collapsed state.
When the expandable attribute is present and has no value, the panel is in a collapsed state. If the expandable attribute is not present, or is set to true, the panel is in an expanded state.
panel element with expandable attribute (collapsed state).
<panel expandable>
<paneltitle>Today's news</paneltitle>
<p>Something <a href="amazing.html">amazing</a> happened on the internet today...</p>
</panel>
Github issue 20
When you follow a link to a panel does it automatically expand?
The prefereddisplay attribute
The prefereddisplay attribute determines the initial visual representation of a panelset element containing one or more panel elements.
DOM interfaces
The panel element DOM interface
attribute HTMLElement headerElement
Provides access to the header element for this panel
attribute HTMLElement contentElement
Provides access to the content element for this panel
attribute HTMLElement tabProxyElement
Provides access to the tab proxy element associated with this panel if it exists (if the panel is part of a panel set) or null
attribute DOMString expansionState
Sets the panel's expansion state to "opened" or "closed" and manages associated accessibility attributes on relevant elements. // TODO: Should this be const instead of DOMString?
void toggleExpansionState()
Inverts the current expansion state of the panel.
The panelset element DOM interface
attribute HTMLPanelElement activePanelElement
Get or set an element as active (currently selected) panel element in this panel set
void selectNextTab()
Selects/activates the next panel in this panel set in document order if any remain
void selectPreviousTab()
Selects/activates the previous panel in this panel set in document order if any previous exist
User interfaces
This section is non-normative. [section is full of conformance requirements ??]
When the panel and paneltitle elements are used, the user agent should expose a user interface to the user. This user interface should include a visible title, and may optionally include an author provided icon or indicator of expandable state.
If the removable attribute is present, the user interface should include a control for dismissing the panel element from the user interface. The control should be focusable and have an accessible name.
If the expandable attribute is present, the paneltitle should become a control for toggling the panel between an expanded or collapsed state. The control must be focusable.
Composite tree
Elements and pseudo-elements of the composite tree of a panel element with a paneltitle element.
::--common-panel-header-box
Used for styling, it contains all the visual features of a panel header.
::--common-panel-header
When a panel element is used on its own, this has default styles and hooks. When a panel element is used as a child of a panelset element, this has special affordances.
::--common-panel-icon
Optional styling hook for an icon. Empty/blank/dimensionless by default, it can be used to display an icon via the CSS background:; property.
Authors can also use the ::before pseudo-element to display a left-orientated indicator of the expandable state of the panel element.
::--common-panel-title
Author specified flow content which serves as the panel element's title.
::--common-panel-hook
Optional hook for a right-orientated indicator of the expandable state of the panel element.
::--common-panel-destroy
When the removable attribute is set, this displays a control for dismissing the panel element from the user interface. The control must be focusable and have an accessible name, otherwise it is hidden.
::--common-panel-content
Author provided content for the panel element.
Github issue 27
Should we include recommended/suggested interaction models here?
