Lead:  Liav Nadler  ONGOING

Description

Data tables display sets of raw data. They are used to make large volumes of data easy to understand, access and manipulate

Usage & Behaviour

General Guidelines

Structure

• A data table includes:
  
  • A header row
  • At least one data row
  • A toolbar (optional)
  • A pagination component (optional)

Content

• Each column contains data of a specific type. Common data types are:
  • Free text (e.g. author name)
  • List item, sometimes with additional icon or indicator (e.g. Status)
  • Number (e.g. score)
  • Date / time
  • A single icon
  • Link
• A table may contain a multiple selection column, allowing users to select one or more rows using checkboxes. If exists, the multiple selection column will always be the first one
• A table may contain an actions column, allowing users to perform row-level actions (see below). If exists:
  • The actions column will be the last one, unless otherwise specified
  • The column will contain up to 3 icons. If more actions exist, the last icon () will allow the user to open action menu (see Contextual Menu)

Width

• TBD

Toolbar

• The toolbar may include:
  • Table-level actions, like create, refresh etc.
  • Row-level actions, like delete, export item etc. These actions can be applied on single or multiple rows
  • A search component
  • An indicator for the number of items found
• Actions will be align to the left of the table's container. The search component and the number of items indicator will be aligned to the right of the table's container
• Table-level actions and row-level actions will be separated by a vertical divider
• For button appearance and interaction see Buttons

Header Row

• The header row is the first row of the table, containing column titles and some additional functionality, as described below

• All columns (except the checkboxes column, if exists) should have titles. In rare cases a column header can show an icon instead of title
• The header row is sticky - it is always shown, even when table content is scrolled
• On single icon columns the column title is centered. In any other case, column titles are left-aligned
• If the column width is too narrow to show the column title it will be truncated, ending with three dots. In this case a tooltip with the full name will show on hover

Defaults

• A table is always sorted by one of the columns
• The sorted column is marked with a light background
• The header of the column that the table is sorted by is marked with an icon, also indicating the order of the sort - ascending or descending (see example above)

Interaction

• Clicking the header cell that the table is sorted by will reverse the order of the sort and flip the icon to represent the new sorting order
• Clicking a header cell that the table is not sorted by will sort the table by that column and move the icon to that column
• Users can resize column width:
  • Hovering over the border between two header cells will turn the cursor into a double-sided arrow
  • Dragging the border to the right or to the left will resize the left column of the two accordingly  
  • Double clicking the border will resize the column to the minimum width possible without truncating the text of the column title or the text inside the column cells  
  • The minimum width will be the width of the title text + X pixels to contain the sorting indicator (TBD)
• Users can reorder columns:
  • Dragging a header cell to the the right or left will update columns order. See Drag and Drop.
  • Checkbox column (on the left) and actions column (on the right) cannot be reordered
  • Another way to reorder column is using the Dual List Selector

Data Row

States

• Data rows have three possible states:
  • Idle - white background (default state)
  • Hover - light blue background
  • Selected - light grey background

Interaction

• On Hover:
  • Only one row can be in hover state at any given time
  • If an action column exists, the action icons will show on hover
  • Each action should have a hover state of its own. See Buttons
• On Click:
  • Clicking anywhere within a data row selects that row
  • An exception of the above is clicking a link or an action inside a cell. Clicking a link goes to the link's target
  • If a multiple selection column exists, clicking any checkbox will select the relevant row
  • If an action column exists, the action icons will show on hover
• On Double Click
  • If relevant, double clicking a row will perform the primary action related to that row (e.g. drilling down to edit the item)

Alignment

• The instructions below refer to LTR languages. On RTL languages switch left and right
• Text inside a cell will be aligned to the left of the column
• Numbers will be aligned to the right and have the same number of digits after the decimal point (if relevant)
• Icons, either a single icon or a group of icons, will be aligned to the center
• Dates will be aligned to the left
• Cells with no applicable value will show the text "N/A", aligned to the center
• Cells with no values yet will show the character "-", aligned to the center
• For further information see Text Formats

Text

• Text that is longer than its column will be truncated, ending with three dots. In this case, hovering over the text will show a tooltip with the complete text (exact delay TBD)

Best practices

• Use short, single-line column titles
• On the initial view of the table:
  
  • Don't show more than ten columns
  • If possible, the first row will be selected
  • Columns will be ordered by importance or popularity, from left to right
  • The first column will be sorted (excluding the multi-selection column, if exists)
  • Set column width to fit typical data

Components

Action Menu

• Action menu is a contextual menu, allowing users to access a list of row-relevant actions
• Clicking the action menu icon opens the action menu
• For full description and interaction see Contextual Menu

Column Contextual  Menu

Pagination Component

Accessibility compliance

<<In general each component should be A11y complied,  please follow the 3 guidelines linked below. At the very least we should document that each component is in compliance with each of the 3>>

Focus management

<<How will the component work with keyboard only - without a mouse. Can be reference if written above

We already set a general guidelines described in /wiki/spaces/UX/pages/308969693 >>

Screen reader support 

 <<Make sure the components support screen reader for content or behaviour where needed - see /wiki/spaces/UX/pages/308248620 >>

Contrast & size compliance

<<Visual designers must comply with the minimal of /wiki/spaces/UX/pages/301498483 for each component>>

Keyboard Operation

<<Explore and describe conventions>>

Design

Code

<<a box containing the code - discuss with Femi>>