Tabs Specification

Owned by

Team Name: CodeX

Developer Name: Diyan Dimitrov

Designer Name

Requires approval from

Peer Developer Name | Date:
Stefan Ivanov | Date:

Signed off by

Radoslav Mirchev | Date:
Radoslav Karaivanov | Date:

Revision History

Version	Users	Date	Notes
1	Names of Developers and Designers	Date

1. Overview

igx-tabs component is used to organize or switch between similar data sets. It contains igx-tab-item components. The igx-tab-item component is a wrapper for igx-tab-content and igx-tab-header components that will represent respectively the container for the data and the tab header. The igx-tab-header may contain a label and/or icon or other custom content. The igxTabHeaderIcon and igxTabHeaderLabel directives are exposed for styling the tab header icon and label. Tabs component places the tabs at the top and allows scrolling when there are multiple tab items.

Tabs are ordered in a single row above their associated content.

<igx-tabs>
  <igx-tab-item>
    <igx-tab-header>
        <igx-icon igxTabHeaderIcon>folder</igx-icon>
        <span igxTabHeaderLabel>Tab 1</span>
    </igx-tab-header>
    <igx-tab-content>
        <h1>Tab 1 Content</h1>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </igx-tab-content>
  </igx-tab-item>
  <igx-tab-item>
    <igx-tab-header>
        <igx-icon igxTabHeaderIcon>folder</igx-icon>
        <span igxTabHeaderLabel>Tab 2</span>
    </igx-tab-header>
    <igx-tab-content>
        <h1>Tab 2 Content</h1>
        <p>Lorem ipsum dolor sit amet...</p>
    </igx-tab-content>
  </igx-tab-item>
</igx-tabs>

The igx-tabs component could also be used as a tab strip integrated with routing. In this scenario tab contents are not defined. The component is not tied to any particular router. The following code snippet demonstrates an integration with the Angular router:

<igx-tabs>
    <igx-tab-item
        routerLinkActive
        #rla1="routerLinkActive"
        [selected]="rla1.isActive"
    >
        <igx-tab-header
            routerLink="/tabs-routing/view1"
        >
            <igx-icon igxTabHeaderIcon>folder</igx-icon>
            <span igxTabHeaderLabel>Tab 1</span>
        </igx-tab-header>
    </igx-tab-item>

    <igx-tab-item
        routerLinkActive
        #rla2="routerLinkActive"
        [selected]="rla2.isActive"
    >
        <igx-tab-header
            routerLink="/tabs-routing/view2"
        >
            <igx-icon igxTabHeaderIcon>folder</igx-icon>
            <span igxTabHeaderLabel>Tab 2</span>
        </igx-tab-header>
    </igx-tab-item>
</igx-tabs>

<router-outlet></router-outlet>

Objectives

Selecting a tab header and viewing its content
Differentiation between tab items states (active, inactive, disabled)
Start (default), end, center and justify tab alignments
Horizontal/Vertical tabs (Not supported)
Templatable tab header - modifying by including icon/label, setting icon position (on application level), prefix/suffix support
Setting the number of tab items
Scrolling when there are multiple tab items
Keyboard navigation between tab items
Customizing the animation for the transition of the content of the tabs (Not supported)
Wrapping long labels in tab header to a second line
Closing/Hiding tabs (on application level)

Acceptance criteria

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

The tabs component should calculate its layout based on the Material guidelines.
The tabs should be scrollable in the container through buttons.

The developer should be able to determine whether the tab item is disabled.
The developer should be able to customize the tab item by icon and label or custom template.
The developer should be able to set random HTML content in a group.
The developer should be able to specify explicitly the selected tab item through code.
The end-user should be able to select a tab item.
The tabs and their content should synchronize their states: selected/disabled.

2. User Stories

Elaborate more on the multi-facetted use cases

Developer stories:

Story 1: As a developer, I want to display multiple tab items with their associated contents in a tabs component.
Story 2: As a developer, I want to customize each tab header with a label, an icon, or both.
Story 3: As a developer, I want to have the option to set the currently selected tab item through code.
Story 4: As a developer, I want to be able to choose between 4 modes of tab header alignments:
- Start - the size of the tab headers depends on their content (label, icon, both), all tabs have equal padding and are aligned to start.
- End - the size of the tab headers depends on their content (label, icon, both), all tabs have equal padding and are aligned to end.
- Center - the size of the tab headers depends on their content (label, icon, both), all tabs have equal padding and are aligned to center.
- Justify - all tab headers are equal in size and fit the width of the tabs component.
If the alignment is not justify and the tab headers don't fit in the available width for the tabs container it can be scrolled (left and right scroll buttons/left and right swipe/mousewheel) to show the tabs that are not in view.
Story 5: As a developer, I want to have the option to disable and enable the animation of the transition of the tabs' contents.
Story 6: As a developer, I want to template the tab header with a suffix icon to let the user "Close" that tab (closing tab is application logic).
Story 7: As a developer, I want to be able to disable certain tabs.
Story 8: As a developer, I want to be able to set the number of displayed tab items.
Story 9: As a developer, I want to wrap long labels in the tab header to a second line. In case the text is too long it will overflow and it will not be fully visible (three points at the end).

End-user stories:

Story 1: As an end-user, I want to navigate between the tab items upon tab header click.
Story 2: As an end-user, I want to navigate by scrolling to tabs that are out of view when they are too many to fit the parent container.
Story 3: As an end-user, I want to have customized tab headers e.g. with a label, an icon, both, close button.
Story 4: As an end-user, I want to be able to visually differentiate active, inactive, and disabled tabs.
Story 5: As an end-user, I want to be able to view tabs in a horizontal or vertical direction.(Not supported)
Story 6: As an end-user, I want to be able to close tabs removing their header from the parent container (application logic).

3. Functionality

Describe behavior, design, look and feel of the implemented feature. Always include visual mock-up

3.1. End-User Experience

The default dimensions of the tabs are as follows:

Width minimum and maximum (inclusive of padding)

Maximum (whichever fits and is smaller): 360dp or (the value of view size minus 56dp)
Minimum: 160dp for larger views, 90dp for smaller views

Height

48dp when content is only icon, only text, or horizontal stack of text and icon
72dp when content is icon and text stacked vertically

Alignment

Centered, start, or end

Justify

Scrollable Tabs: As the tab headers overflow the tabs container, a designated area appears at the start and at the end of the tabs container. It has an arrow in disabled state pointing to the start and an arrow in enabled state pointing to the end. After scrolling by pressing the enabled arrow at the end, once you have tabs that are not fully visible in the left of the container the left arrow becomes enabled as well. After scrolling to the end of the container, the arrow at the end of the tabs container becomes disabled.

In case of a selection of a partially visible tabs item, the tabs pre-scroll so that the latter is seen fully visible.

The scroll's range is done in pixels.

Icons

Text and icon stacked vertically

Content-fit Type - text and icon stacked horizontally

Tabs with a suffix - for example a close button

Wrapped long label to a second line

** Prepared design files for styling e.g. interplay with features and light/dark variants design hand-off

3.2. Developer Experience

The developer should be able to add multiple tab items.
The developer should be able to specify the tab header alignment (start, end, center, justify).
The developer should be able to set enable/disable state to tabs items.
Tabs component should provide its current selected tab item and its index.

3.3. Globalization/Localization

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

3.4. Keyboard Navigation

Tabs with Automatic Activation https://www.w3.org/TR/wai-aria-practices-1.1/examples/tabs/tabs-1/tabs.html

Keys	Description
Tab	When the focus moves into the tab list, places focus on the active tab element. When the tab list contains the focus, moves focus to the next element in the tab sequence, which is the tab content element
Right Arrow	Moves focus to the next tab. If focus is on the last tab, moves focus to the first tab. Activates the newly focused tab.
Left Arrow	Moves focus to the previous tab. If focus is on the first tab, moves focus to the last tab. Activates the newly focused tab.
Home	Moves focus to the first tab and activates it.
End	Moves focus to the last tab and activates it.

3.5. API

IgxTabsComponent

Options

Name	Description	Type	Default value	Valid values
`selectedIndex`	Gets/sets the index of the selected tab.	`number`
`selectedItem`	Gets the selected tab item component.	`IgxTabItemDirective`
`tabAlignment`	Gets/sets the tab header alignment. By default, the it is `start` and the tab item width is sized to its content in the range of min/max width and is start aligned. When `justify` is set, all tabs have equal size to fit the view port.	`IgxTabsAlignment`	`start`	`start \| end \| center \| justify`
`disableAnimation`	Enables/disables the animation for transition of the contents of the tabs.	`boolean`	`false`

Events

Name	Description	Cancelable	Parameters
`selectedIndexChange`	Emitted when the selected index changes.	no	index: number
`selectedIndexChanging`	Emitted when the selected index is about to change.	yes	{ owner: IgxTabsDirective, cancel: boolean, oldIndex: number, newIndex: number }
`selectedItemChange`	Emitted when the selected tab item changes.	no	{ owner: IgxTabsDirective, oldItem: IgxTabItemDirective, newItem: IgxTabItemDirective }

IgxTabItemComponent

Options

Name	Description	Type	Default value	Valid values
`selected`	Gets/sets whether the tab item is selected.	boolean	`false`
`disabled`	Gets/sets whether the tab item is disabled.	boolean	`false`

IgxTabHeaderComponent

(No public API)

IgxTabContentComponent

(No public API)

4. Test Scenarios

Automation

Scenario 1:
scenario 2:

5. Accessibility

ARIA Support

Roles:
- Tab content has tabpanel role.
- Tab header has tab role.
- Tab headers container has tablist role.
Attributes:
- Include aria-controls on the tab header to link it to its content.
- Include aria-labelledby on the tab content to link it to its header.
- Include aria-selected on the tab header.