List Specification

Overview

igx-list should represent vertical container for contextual similar items. List is a building block of any complex UI used in almost every mobile application.

<igx-list>
    <igx-list-item isHeader="true">Header 1</igx-list-item>
    <igx-list-item>Item 1</igx-list-item>
    <igx-list-item>Item 2</igx-list-item>
    <igx-list-item>Item 3</igx-list-item>
    <igx-list-item isHeader="true">Header 2</igx-list-item>
    <igx-list-item>Item 4</igx-list-item>
    <igx-list-item>Item 5</igx-list-item>
    <igx-list-item>Item 6</igx-list-item>
</igx-list>

Objectives

Provides means for the developers to implement a simple common case, yet customizable list with minimal efforts. The list item component should be a container for text or some HTML content. A group of items into the list can be separated and labeled by header.

User Stories

Developer

As a developer I want to:

add a list, so that I can create rows of similar list-items.
have a vertically scrollable list, so that I can add as many list-items as I need.
be able provide data items to the list using an ngFor directive:

<igx-list>
    <igx-list-item *ngFor=”#apple of apples”>
        {{apple.sweetLevel}}
    </igx-list-item>
</igx-list>

be able display group headers by adding a special header item into the list:

<igx-list>
    <igx-list-item isHeader="true">Mildly Sweet</igx-list-item>
    <igx-list-item>Red Delicious</igx-list-item>
    <igx-list-item>Ambrosia</igx-list-item>
    <igx-list-item>Rome</igx-list-item>

    <igx-list-item isHeader="true">Sweet</igx-list-item>
    <igx-list-item>Golden Delicious</igx-list-item>
    <igx-list-item>Cosmic Crisp</igx-list-item>
    <igx-list-item>Pinova</igx-list-item>

    <igx-list-item isHeader="true">Super Sweet</igx-list-item>
    <igx-list-item>Gala</igx-list-item>
    <igx-list-item>Fuji</igx-list-item>
    <igx-list-item>Kiku</igx-list-item>
</igx-list>

be able to implement custom logic and behavior to be executed when clicking a list item.
be able to provide a custom template for templating the list when it is empty.

<igx-list>
  <ng-template igxEmptyList>
    <p>My custom empty list template</p>
  </ng-template>
</igx-list>

be able to set an active item.
be able to focus list items.
be able to change focused items via keyboard keys: Enter, Space, Home, End, Arrow keys.
be able to remove focus from an item via the Escape key.
be able to control whether keyboard navigation would continue when reaching the start/end of the list.
be able to specify a display density for the layout of the list and its items:

<igx-list [displayDensity]="'compact'">
    <igx-list-item isHeader="true">Mildly Sweet</igx-list-item>
    <igx-list-item>Red Delicious</igx-list-item>
    <igx-list-item>Ambrosia</igx-list-item>
    <igx-list-item>Rome</igx-list-item>
</igx-list>

End user

As a end user, I want to:

have a list of information, so that I can quickly review rows of data.
be able to vertically scroll the list, so that I can review all of the available list items.
be able to use on-swipe gestures.
be able to click any item, so that a certain behavior gets triggered.
be able to navigate through list items via the keyboard.

Acceptance criteria

The developer can add a list component to the application.
The developer can define list items as headers, so they label other items below them.
The end-users can view a list.
The end-users can vertically scroll the list items.
The end-users can interact the list items by swiping them left or right.

Functionality

A list consists of a single continuous column of tessellated sub-divisions of equal width called rows that function as containers for list-items.

End User Experience

Swipe gesture - I want to slide list items through swipe (or pan) gesture.
Layout - Lists should scroll only vertically and the scroll should appear only when the list items overflow the screen view.

API

igx-list

Inputs

Name	Description
allowLeftPanning	Determines whether the left panning of an item is allowed
allowRightPanning	Determines whether the right panning of an item is allowed
emptyListTemplate	The custom template to be used when the list is empty

Properties

Name	Description
children	Collection of all `IListChild` components: items and headers
items	Array of items in the list
headers	Array of headers in the list
innerStyle	Currently used inner style depending on whether the list is empty or not
role	Gets the role of the list

Outputs

Name	Description
Event emitters	Notify for a change
panStateChange	Triggered when pan gesture is executed on list item
leftPan	Triggered when left pan gesture is executed on list item
rightPan	Triggered when right pan gesture is executed on list item
itemClicked	Triggered when a list item has been clicked
startPan	Triggered when start a pan gesture on list item
endPan	Triggered when a pan gesture execution on list item has ended
resetPan	Triggered when the pan end threshold not reached

igx-list-item

Inputs

Name	Description
hidden	Determines whether the item should be displayed
isHeader	Determines whether the item should be displayed as a header, default value is false

Properties

Name	Description
index	The index of item in children collection
panState	Gets the item's pan state
list	Gets the list that is associated with the item
role	Gets the role of the item within its respective list - separator if isHeader is true and listitem otherwise
element	Gets the native element that is associated with the item
width	Gets the width of the item
maxLeft	Gets the maximum left position of the item
maxRight	Gets the maximum right position of the item
touchAction	Determines in what way the item can be manipulated by the user via a touch action
headerStyle	Gets if the item is styled as header item
innerStyle	Gets if the item is styled as list item

ARIA support

Roles:
- List will need list role
- List item will need separator role when it is a header and listitem role when it is not.

Test Scenarios

Test defining a list:
- with content items only;
- with items and header;
- with multiple headers.
Test defining an empty list and verify the default empty template is used.
Verify the specified list width is honored.
Verify items' maxLeft, maxRight and left property values are properly reflected.
Verify allowRightPanning properly controls whether panning items right is allowed.
Verify allowLeftPanning properly controls whether panning items left is allowed.
Verify custom empty template would be shown when specified instead of the default one.
Verify the loading template is always shown when IgxList's isLoading property is set to true.
Verify the loading template is hidden once IgxList's isLoading property is set to false.
Verify a custom loading template would be shown when specified instead of the default one.
Verify IgxList's ItemClicked event is emitted on clicking a list item.
Verify ItemClicked event is emitted with the correct direction when swiping items.
Verify items' roles are properly set.
Verify items can be hidden.
Test panning events.
Verify list items get activated on click and on key press.
Verify list items get focused on click and on key press.
Verify Escape key clears the focus from the focused item.
Verify Arrow keys navigate successfully through list items.
Verify Space and Enter keys activate & focus the first list item if there's no active item already.
Verify Home and End keys navigate to the first and last list item respectively.