Skip to content

Accordion

Jump to bottom
Damyan Petev edited this page Jul 7, 2022 · 30 revisions

Accordion Specification

Contents

  1. Overview
  2. User Stories
  3. Functionality
  4. Test Scenarios
  5. Accessibility
  6. Assumptions and Limitations
  7. References

Owned by

Astrea

Developer Name: Bozhidara Pachilova

Designer Name

Requires approval from

  • Peer Developer: Martin Evtimov | Date: 20.06.2022
  • Design Manager: Svilen Dimchevski | Date: 20.06.2022

Signed off by

  • Product Owner: Radoslav Mirchev | Date: 20.06.2022
  • Platform Architect Damyan Petev | Date: 2022-06-29

Revision History

Version Users Date Notes
1 Names of Developers and Designers Date 25-May-2022
1.01 Teodosia Hristodorova Date 26-May-2022 Developer Stories, API and Test Scenarios

1. Overview

Objectives

The Accordion web component is combining a collection of IgcExpansionPanelComponents 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 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 customizable out of the box since each of them is an IgcExpansionPanelComponent that comes with built-in customization. The Accordion has two interactive modes:

  • only one igc-expansion-panel can be expanded at a time (expanding a collapsed panel would collapse the currently expanded one) prototype
  • multiple IgcExpansionPanelComponents can be expanded together, which means that only explicit user interaction or use of the API affects the state of the Accordion prototype

Acceptance criteria

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

  • Sign off
  • Available prototypes and Figma designs [x]
  • Created file structure in Indigo_Platform Accordion feature

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 expect that each igc-expansion-panel within an igc-accordion supports the same degree of customizations and styling as they normally do as a standalone component.
  • Story 4: 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 (via CSS variable).
  • Story 5: As a developer, I expect the accordion is accessible and supports keyboard navigation out of the box.
  • Story 6: 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.

End-user stories:

  • Story 1: 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 2: 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.
  • Story 3: As an end-user, I want to be able to expand multiple or only one branch at a time.

3. Functionality

The Accordion supports the exploration of information in a compact way through progressive disclosure of items/panels. It supports a 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

  1. single expand prototype
  2. multiple expand prototype

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.

Design hand-off in Figma with all themes and a prototype

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

When a header is focused:

Keys Description
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

Options

Name Description Type Default value Valid values
singleExpand Allows only one panel to be expanded at a time boolean false
panels Get all IgcExpansionPanel children of the accordion IgcExpansionPanelComponent[]

Methods

Name Description Return type Parameters
hideAll Collapse all opened expansion panels void N/A
showAll Expand all closed expansion panels void N/A

4. Test Scenarios

Basic

  • Should render accordion w/ expansion panels
  • Should calculate accordion's panels correctly
  • Should be able to render nested accordions

Expand/Collapse

  • Should update the current expansion state when hideAll is invoked.
  • Should update the current expansion state when showAll 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 preserve expanded panel when singleBranchExpand is changed from false to true
  • Should preserve expanded panels when singleBranchExpand is changed from true to false

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 expand only the focused panel when singleBranchExpand is true on Shift + Alt + Arrow Down key press
  • Should collapse all panels on Shift + Alt + Arrow Up key press
  • Should collapse only the focused panel on Shift + Alt + Arrow Up key press
  • Should navigate to the first panel on Home key press
  • Should navigate to the last panel on End key press

5. Accessibility

ARIA Support Per https://www.w3.org/WAI/ARIA/apg/patterns/accordion/ This spec covers the optional Arrows and Home/End navigation WAI-ARIA Roles, States, and Properties are implemented by the Expansion Panel, along with Space/Enter keyboard interaction and Tab navigation.

RTL Support

6. Assumptions and Limitations

Assumptions Limitation Notes

7. References

Specify all referenced external sources

Clone this wiki locally