<oui-panelset>: The Panelset element

The <oui-panelset> HTML element represents a generic division of a document, which is composed of flat sections of content. Panelsets can be assigned affordances to present sections of content with distinct controls to consume them.

<oui-panelset>
	<h2>Mail</h2>
	<p>… Mail content …</p>
	<p>… Mail content …</p>

	<h2>News</h2>
	<p>… News content …</p>
	<p>… News content …</p>
	<p>… News content …</p>
</oui-panelset>

Installation

<script src="https://tabvengers.github.io/spicy-sections/register.js"></script>

How it works

Any heading element child of the panelset represents the beginning of a panel. All content proceeding the heading element that is not another heading element represents the content of the given panel.

`OUIPanelsetElement`

The OUIPanelsetElement interface gives access to properties specific to <oui-panelset> elements. It inherits methods and properties from the base HTMLElement interface.

Attributes

The OUIPanelsetElement interface inherits attributes from its parent, HTMLElement.

affordance: A string containing the default affordance of the panelset. When set, this attribute does not update the current affordance of the panelset.

Usage

<oui-panelset affordance="exclusive-disclosure">
	<!-- flat sections of content -->
</oui-panelset>

Properties

The OUIPanelsetElement interface inherits properties from its parent, HTMLElement.

affordance: A string containing the current affordance of the panelset. When set, this property updates the current affordance of the panelset. This does not reflect the affordance attribute.

Usage

const panelset = document.querySelector('oui-panelset')

panelset.affordance = 'exclusive-disclosure'

Methods

getPanels

An array of objects representing the sections of content as panels in the panelset.

Each panel object has a label property which returns the element identified as the label of the given panel, a contents property which returns the elements and text nodes identified as the contents of the given panel, and an open property which returns whether the given panel is open.

Usage

const panelset = document.querySelector('oui-panelset')
const panels = panelset.getPanels()

for (const panel of panels) {
	console.log(panel) /* {
		open: boolean
		label: HTMLHeadingElement,
		content: (Element | Text)[]
	} */
}

CSS Properties

--affordance: A string containing the active affordance of the panelset. When set, this property updates the current affordance of the panelset. This does not reflect the affordance attribute.

Usage

/* use with a disclosure interface on narrow width screens */
@media (max-width: 40em) {
	oui-panelset {
		--affordance: disclosure;
	}
}

/* use a tabset interface on wide width screens */
@media (min-width: 60em) {
	oui-panelset {
		--affordance: tabset;
	}
}

Events

In addition to the usual events supported by HTML elements, the <oui-panelset> element supports toggle and affordancechange events.

toggle: The toggle event is dispatched to the <oui-panelset> element whenever one of its panel states changes between open and closed. This event is dispatched after the state is changed.
affordancechange: The affordancechange event is dispatched to the <oui-panelset> element whenever its affordance state changes. This event is dispatched after the affordance state is changed, and it is not dispatched by the initial affordance state.

Usage

const panelset = document.querySelector('oui-panelset')

panelset.addEventListener('toggle', () => {
	const panels = panelset.getPanels()
})

panelset.addEventListener('affordancechange', () => {
	switch (panelset.affordance) {
		case 'content':
			break
		case 'disclosure':
			break
		case 'exclusive-disclosure':
			break
		case 'tabset':
			break
	}
})

Affordances

Type	Description
`disclosure`	Sequential sections of content that display independently.
`exclusive-disclosure`	Sequential sections of content that display one at a time.
`tabset`	Layered sections of content that display one at a time.
`content`	Sequential sections of content display as they are authored.

Parts

The generated shadow tree inside a Panelset element can be styled using ::part pseudo-elements.

<oui-panelset>
	::part(container)
		affordance parts
	::
</oui-panelset>

Content Affordance Parts

::part(section is-content)
	::part(label is-content)
	::part(content is-content)
::

Disclosure Affordance Parts

::part(section is-disclosure)
	::part(label is-disclosure)
	::part(content is-disclosure)
::

Tabset Affordance Parts

::part(label-container is-tabset)
	::part(label is-tabset)
::part(content-container is-tabset)
	::part(content is-tabset)
::

Any shadow tree part can be styled by a particular affordance by adding it to the part selector.

<style>
oui-panelset::part(container is-tabset) {
	/* panelset container styles during the tabset affordance */
}
</style>

Part	Description
`container`	The container of all content in the panelset.
`label-container`	The container of all labels, available in the tabset affordance.
`marker`	The marker before each label, available in the disclosure and exclusive-disclosure affordances.
`label`	The container of each label.
`panel-container`	The container of all panels, available in the tabset affordance.
`label`	The container of each panel.