Accordion Specification

Owned by

Astrea

Developer Name

Stefan Ivanov

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Konstantin Dinev | Date: 11 Jun 2021
Platform Architect Name | Date:

Revision History

Version	Users	Date	Notes
1	Stefan Ivanov	18 May 2021

1. Overview

Objectives

igx-accordion - Angular native accordion component combining a collection of igx-Expansion-panels in a vertical layout. It allows the end-user to see an overview of data and dig into the details that come with it in an interactive fashion. The igx-accordion does not overload the user with information, making it compact in size and using progressive disclosure to unveil more of it. Its items are templatable out of the box since each of them is an igx-expansion-panel that comes with built-in templating. The igx-accordion has two interactive modes:

only one igx-expansion-panel can be expanded at a time (selecting a collapsed panel would collapse the currently expanded one, while the selected one is expanding at the same time) prototype
multiple igx-expansion-panels can be expanded together, which means that only explicit user interaction or use of the API affects the state of the igx-accordion prototype

Acceptance criteria

Must-have before we can consider the feature a sprint candidate

...

2. User Stories

Elaborate more on the multi-facetted use cases

Developer stories:

Story 1: As a developer, I want to create a simple accordion in a declarative fashion, showing a title when collapsed and complementing it with a text paragraph when expanded, so that I can display a compact FAQ section.
Story 2: As a developer, I want to be able to choose whether single or multiple panels can be expanded at the same time so that I can determine the accordion interactivity.
Story 3: As a developer, I want to be able to template each igx-expansion-panel individually, so that I can add a CTA button or hyperlink where appropriate.
Story 4: As a developer, I expect that each igx-expansion-panel within an igx-accordion supports the same degree of customizations and styling as they normally do as a standalone component.
Story 5: As a developer, I want to be able to remove the default margins added to an expanded panel, so that it does not stand out as much from the rest of the accordion.
Story 6: As a developer, I expect that all panels in an accordion have responsive sizing out of the box that is controlled by the size of the accordion.
Story 7: As a developer, I expect that the accordion is accessible and supports keyboard navigation out of the box.
Story 8: As a developer, I want to be able to place an accordion within another component e.g. a side panel, navigation drawer or dock-manager pane, so that I can create elaborate UIs.
Story 9: As a developer, I want to be able to define certain panels as disabled at initialization or at runtime.

End-user stories:

Story 1: As an end-user, I want to be able to expand an accordion item/panel, so that I can read more details about it.
Story 2: As an end-user, I want to be able to collapse an accordion item/panel, so that I can hide the details and focus on another one.
Story 3: As an end-user, I want to be able to collapse all accordion items/panels at once, so that I can move on to the next section of the webpage.
Story 4: As an end-user, I want to be able to navigate the accordion and its items with the keyboard, so that I can navigate faster and take advantage of screen readers.

3. Functionality

The Accordion supports the exploration of information in a compact way through progressive disclosure of items/panels. It supports mouse and keyboard to facilitate ease of use, navigation and accessibility.

3.1. End-User Experience The Accordion component lets the end-user interact with an overview of the data to see its full details for a collection of items/panels. It can be seen as a collection of vertically stacked Expansion Panels supporting simple navigation between them. The paradigm is frequently used to show simple or more complex FAQ sections with primarily textual content, but it is also possible to have actions and other elements in the details part.

Sometimes, an accordion may appear in the details of an Expansion Panel when more complex structures need to be presented creating some sort of shallow nesting.

Other times, an Accordion may appear in a side panel e.g. to render some elaborate filter options.

There are two navigation modes that can be seen below

The Accordion comes with the built-in styling from the Expansion Panel. The only extra care that has to be accounted for is that the Accordion size i.e. its width is propagated to each Expansion Panel in it and there is an 8px margin above and below the element in an expanded state.

3.2. Developer Experience

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. Keyboard Navigation

Keys	Description
Tab	Moves the focus to the first(if the focus is before accordeon)/next panel
Shift + Tab	Moves the focus to the last(if the focus is after accordeon)/previous panel
Arrow Down	Move the focus to the panel below
Arrow Up	Move the focus to the panel above
Alt + Arrow Down	Expand the focused panel in the accordion
Alt + Arrow Up	Collapse the focused panel in the accordion
Shift + Alt + Arrow Down	Expand all panels when this is enabled
Shift + Alt + Arrow Up	Collapse all panels whichever panel is focused
Home	Navigates to the first panel in the accordion
End	Navigates to the last panel in the accordion

3.5. API

Accessors

Name	Description	Type
panels	All `IgxExpansionPanel` children of the accordion	`IgxExpansionPanelComponent[]`

Properties

Name	Description	Type	Default value	Valid values
id	The id of the accordion. Bound to `attr.id`	`string`	'accordion-${iter}'	N/A
singleBranchExpand	How the accordion handles panel expansion	`boolean`	`'false'`	`'false' \| 'true'`
animationSettings	Animation settings that override all single animations passed to underlying panels	`AnimationSettings`	`null`	N/A

Methods

Name	Description	Return type	Parameters
collapseAll	Collapse all expanded expansion panels	`void`	N/A
expandAll	Expands all collapsed expansion panels when `singleBranchExpand === false`	`void`	N/A

Events

Name	Description	Cancelable	Parameters
panelExpanded	Re-emits the `IgxExpansionPanel.contentExpanded` event.	`false`	`{ owner: IgxExpansionPanel, event?: Event }`
panelCollapsed	Re-emits the `IgxExpansionPanel.contentCollapsed` event.	`false`	`{ owner: IgxExpansionPanel, event?: Event }`
panelExpanding	Re-emits the `IgxExpansionPanel.contentExpanding` event.	`true`	`{ owner: IgxExpansionPanel, event?: Event }`
panelCollapsing	Re-emits the `IgxExpansionPanel.contentCollapsing` event.	`true`	`{ owner: IgxExpansionPanel, event?: Event }`

4. Test Scenarios

Basic

Should render accordion w/ expansion panels
Should only render expansion panels inside of accordion (no other elements)
Should calculate accordion's panels correctly
Should allow overriding animationSettings that are used for expansion panels toggle
Should be able to render nested accordions

Expand/Collapse

Should update the current expansion state when collapseAll is invoked.
Should update the current expansion state when expandAll is invoked.
Should be able to expand only one panel when singleBranchExpand is set to 'true'
Should be able to expand multiple panels when singleBranchExpand is set to 'false'
Should emit ing and ed events when expand panel state is toggled
Should preserve expanded panel when singleBranchExpand is changed from 'false' to 'true'

Keyboard Navigation

Should navigate to first (if the focus is before accordion)/next panel on TAB key press
Should navigate to last (if the focus is after accordion)/previous panel on SHIFT + TAB key press
Should navigate to the panel below on Arrow Down key press
Should navigate to the panel above on Arrow Up key press
Should navigate between direct child panels only (nested accordion scenario)
Should expand the focused panel on ALT + Arrow Down key press
Should collapse the focused panel on ALT + Arrow Up key press
Should expand all panels when singleBranchExpand is 'false' on Shift + Alt + Arrow Down key press
Should collapse all panels on Shift + Alt + Arrow Up key press
Should navigate to first panel on Home key press
Should navigate to last panel on End key press