Expansion Panel Specification

Overview

The IgxExpansionPanelComponent provides a way to display information in a toggleable way -

• compact summary view containing title and description and
• expanded detail view containing additional content in addition to the summary header.

Objectives

Provide Ignite UI for Angular igx-expansion-panel component that supports the following features:

• Collapsible body
• Header Icon Templates
• Disable user interaction
• Animations configuration

Design definition

User Stories

Developer

Story 1: As a developer, I want a component that is able to expand its content upon user interaction or collapse it if already expanded to return to the default state i.e. collapsed. I expect that I am able to change this default state to expanded if I need to.

Story 2: As a developer, I want to be able to template the expanded and collapsed content areas.

Story 3: As a developer, I want to be able to show, hide the expand/collapse icon.

Story 4: As a developer, I want to be able to determine the position of the expand/collapse icon.

Story 5: As a developer, I want to be able to select an icon glyph for the expand/collapse icon.

Story 6: As a developer, I expect that the component can be used as an element of a collection i.e. composition of an accordion as a list of instances of this component is easily doable.

Story 7: As a developer, I want to be able to cancel the default header interaction behavior, depending on certain conditions

End user

Story 1: As an end user, I want to be able to expand an area in order to reveal more detailed content.

Story 2: As an end user, I want to be able to collapse an area with detailed content to reduce the amount of scrolling I need to perform in order to reach further content.

Story 3: As an end user, I expect that the expansion and collapsing happens smoothly (with a nice animation).

Story 4: As an end user, I want to expand/collapse a content area using my keyboard e.g. by pressing space, enter, alt + arrow down (to expand) or alt + arrow up (to collapse).

Story 5: As an end user, I expect that defined components, such as the igx-Navbar, can utilize the expansion/collapsing mechanics internally to offer smart behavior upon user interaction such as scrolling the view EXAMPLE.

Test Scenarios

Automation

• The component gets expanded/collapsed on
  • header clicking
  • expand/collapse icon clicking
  • using the keyboard (enter/space/alt+arrowdown/alt+arrowup key pressing)
  • using the API toggle() method
  • using the API expand()/collapse() methods
  • setting component's collapsed property
• onCollapsed and onExpanded events are fired on collapsing/expanding the panel
• onInteraction event gets fired on user interaction with the panel header
• The component is not interactable when disabled
• User can choose if the expand/collapse icon will be displayed
• User can choose the position of the expand/collapse icon (left/right)
• Expansion panel applies all appropriate classes on initialization, on panel expanding and collapsing.
• User can choose the animations that will be played when expand/collapse is triggered
• The expandable area displays properly all of the input elements (E.g. text, images, another components)

Acceptance criteria

• Expanding
• Collapsing
• Template Header expand/collapse image
• Animations configuration

Functionality

The IgxExpansionPanelComponent allows full configuration of the content shown in the control.

API

IgxExpansionPanel

Properties

Name	Type	Description	Default
id	string	The unique id of the control	igx-expansion-panel-0
cssClass	string	If the control applies a css class. Set to `` to omit	igx-expansion-panel

Input

Name	Type	Description	Default
collapsed	boolean	Should the contents of the control be hidden. Does not trigger animations.	true
animationSettings	{ openAnimation: AnimationMetadata, closeAnimation: AnimationMetadata }	What animations should be played when expand/collapse is triggered	{ openAnimation: growVerIn, closeAnimation: growVerOut }

Outputs

Name	Emits	Description
contentCollapsed	IExpansionPanelEventArgs	Emitted when collapse() finishes
contentExpanded	IExpansionPanelEventArgs	Emitted when expanded() finishes

Methods

Name	Signature	Description
collapse	() => void	Collapses the control
expand	() => void	Expands the control
toggle	() => void	Toggles the control

Directives

Name	Selector	Description
IgxExpansionPanelHeader	igx-expansion-panel-header	Marks the header of the component

IgxExpansionPanelHeader

Properties

Name	Type	Description	Default
id	string	The unique id of the control	igx-expansion-panel-0
panel	IgxExpansionPanelComponent	The control the header belongs to	null
title	IgxExpansionPanelTitleDirective	The title element of the header	null
iconRef	ElementRef	Gets the reference to the element being used as expand/collapse indicator. If iconPosition is NONE - return null

Inputs

Name	Type	Description	Default
disabled	boolean	Should the control respond to user interaction	false
iconPosition	enum ICON_POSITION	Where should the icon be displayed ('left', 'right' or 'none')	left

Marking a header as disabled sets its tabindex to -1, making in inaccessible via Tab navigation.

Outputs

Name	Emits	Description
onInteraction	IExpansionPanelCancelableEventArgs	Emitted on user interaction with the component header

Directives

Name	Selector	Description
IgxExpansionPanelTitle	igx-expansion-panel-title	Marks the title of the component header
IgxExpansionPanelDescription	igx-expansion-panel-description	Marks the description of the component header
IgxExpansionPanelIcon	igx-expansion-panel-icon	Marks the template that should be used as the icon in the collapsible header

IgxExpansionPanelBody

Properties

Name	Type	Description	Default
panel	IgxExpansionPanelComponent	The control the header belongs to	null
role	string	Binds to the host attribute role	region

Inputs

Name	Type	Description	Default
labelledBy	string	Binds to the host attribute aria-labelledby	panel.title.id
label	string	Binds to the host attribute aria-label	''

End User Experience

• The igx-expansion-panel provides a short title and description in the header when in collapsed state.
• When expanded, the igx-expansion-panel body provides more details to the user.
• The igx-expansion-panel is responsive.

Developer Experience

User Interface

ARIA support

IgxExpansionPanel:

• role defaults to region.
• aria-labelledby attribute contains the element IDs of labels. If the title text is visible on screen, defaults to the expansion panel's title id. If title is not specified, aria-label takes precedence for readers.
• aria-label attribute to be used by readers if title text(respectively aria-labelledby) are not present.

IgxExpansionPanelHeader @Host:

• role defaults to heading.
• aria-level attribute defaults to level 3.
• aria-labelledby attribute is set if the title text is visible on screen, defaults to the expansion panel's title id.

IgxExpansionPanelHeader @Content:

• role defaults to button.
• aria-expanded attributes indicates whether the collapsible content below is in the expanded or in the collapsed state.
• aria-disabled attribute indicates that the collapsible-header is perceivable but disabled, so it is not collapsible.
• aria-controls attribute indicates what element's functionality is governed by this element. Defaults to expansion panel's id.

Known Issues and Limitations