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-panel 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-panel>
        <h1>Tab 1 Content</h1>
        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
    </igx-tab-panel>
  </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-panel>
        <h1>Tab 2 Content</h1>
        <p>Lorem ipsum dolor sit amet...</p>
    </igx-tab-panel>
  </igx-tab-item>
</igx-tabs>

The igx-tabs component could also be used as a tab strip integrated with routing. In this scenario tab panels 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)
Content-fit (default) and fluid tab header sizing modes
???Horizontal/Vertical tabs
Templatable tab header - modifying by including icon/label, setting icon position, 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
Wrapping long labels in tab header to a second line
Closing/Hiding tabs

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 associate panels 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 2 modes of tab headers sizing using headerSizing:
- Fluid size - all tab headers are equal in size and fit the width of the tabs component.
- Content-fit - the size of the tab headers depends on their content (label, icon, both) and all tabs have equal padding. If they 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' panels.

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.
Story 6: As an end-user, I want to be able to close tabs removing their header from the parent container.

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

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. This visually pushes the first tab thus causing a "jump" in case of resizing. The area at the start displays a disabled arrow, and at the end, it has an arrow pointing to the end. After a scroll, the first area is populated with an arrow pointing at the start.

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.

Fluid Type - text and active, inactive, disabled states of tab items

Icons

Text and icon stacked vertically

Content-fit Type - text and icon stacked horizontally

Tabs with a suffix - close button

Active tab indication line positioned at the top

Wrapped long label to a second line

Vertical orientation

A dropdown (show more) button that shows the hidden content

3.2. Developer Experience

The developer should be able to add multiple tab items.
The developer should be able to specify the mechanism for tab header sizing (fluid, content-fit).
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 tabpanel 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`
`headerSizing`	Gets/sets the tab header sizing mode. By default, the sizing mode is `contentfit` and the tab item width is sized to its content in the range of min/max width. When `fluid` is set, all tabs have equal size to fit the view port.	`IgxTabsHeaderSizing`	`contentfit`	`fluid \| contentfit`
`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)

IgxTabPanelComponent

(No public API)

4. Test Scenarios

Automation

Scenario 1:
scenario 2:

5. Accessibility

ARIA Support

Roles:
- Tabs has tabs role.
- Tab panel 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 panel.
- Include aria-labelledby on the tab panel to link it to its header.
- Include aria-selected on the tab header.