@lightspeed/cirrus-table

Table

A set of recommended design rules and reusable React components to create tables of data quickly for specific workflow needs.

They should help customers find, view, organize and interact with their data in easy and convenient ways. The interface should disappear so that retailers can focus on the job at hand.

Installation

First, make sure you have been through the install steps steps required to add Flame in your application. Although it's not required to have Flame installed to use Logo, you will need to install its peer dependencies.

If using Yarn:

yarn add @lightspeed/cirrus-table

Or using npm:

npm i -S @lightspeed/cirrus-table

Styled System props

Component Name	styled-system props
Td	height
	width
	space
	fontSize
	textAlign
	color
Th	color
	height
	width
	space
	display
	alignItems, justifyContent
	fontSize
Tr	color
	space

Usage

Components

<Table>

Note: you need to manually wrap the <Table> with a <Card> to get the recommended visual for tables. This is left to the consumer for maximum flexibility.

Styled table tag (<table>) with the following props:

Prop	Type	Description
loadingStatus?	"loading" or "completed"	Shows a loading indicator between the table header and body

Base Table Elements

<Thead>

An augmented version of the table header which features a loading bar hooked onto the table's loading state

<Th>

A Styled System augmented table heading tag (<th>)

<Tr>

A Styled System augmented table row tag (<tr>)

Prop	Type	Description
isHoverable	bool	If true, no hover style will be applied, false by default

<Td>

A Styled System augmented table cell tag (<td>).

<Tbody>

An emotion instantiated tbody. No augmentation added, it's simply there for markup stylistic purposes.

<Tfoot>

An emotion instantiated tfoot. No augmentation added, it's simply there for markup stylistic purposes.

<NoDataTd>

An extension of <Td>. It comes with a pre-formatted styles for a no data state.

<Pager />

A simple pager component designed for the table.

Prop	Type	Description
isFirst	bool	If true, the "back" pager button is disabled
isLast	bool	If true, the "forward" pager button is disabled
handleNext	func	Callback function attached to the the "forward" pager button
handlePrevious	func	Callback function attached to the the "back" pager button
children	any	Element will be added to the front of the Pager button group

Table Action Components & Filtering

Additional actions can be added to the table.

Table exports an all encompassing Object called TableActions, which contains various components that are hooked to a single context that mostly handles the interconnected ui state possible within actions, e.g: filters and tags.

Using the TableActions.Context and Actions

The TableActions provides many ways to add and remove filters programaticaly.

Here are some of the exposed functions that will come in handy:

Prop	Description
applyFilter(filterKey, label, value)	Upserts a new filter with a corresponding label and raw values
applyFilters(Array<{key:string, value: any, label: string}>)	Replace filters with the current list sent in parameters
deleteFilter(filterKey)	Delete a filter by key
deleteAllFilters()	Deletes all filters
deleteAllFiltersAndSearchTerm	Deletes all filters, including the search term
getValues(filterKey)	Retrieves a global count of all active filters
getFilters()	Retrieves the entire list of active filters

There are two ways of gaining access to these functions:

Using React.useContext

const MyApp = () => {
  const { applyFilter, deleteFilter /* ... */ } = React.useContext(TableActions.Context);
};

Via the consumer component

const MyApp = () => {
  return (
    <TableActions.Consumer>
      {({ applyFilter, deleteFilter, /* ... */ }) => (
        /* ... */
      )}
    </TableActions.Consumer>
  );
}

TableActions.FilterPanelProvider

A Provider to keep track of active filters and routing of the TableActions.Dropdown

Prop	Type	Description
onFilterChange	func	Callback function that will receive in parameters the currently selected array of filters
initialSearchTerm	string	The initial search term. If using TableActions.SearchBar, it'll automatically use the initialSearchTerm as it's value
initialFilters	Array<{key:string, value: any, label: string}>	The initial filters for the table actions. See PagerTable on how to set initialFilters properly
renderDropdownContent	ReactNode	The content that will be used within dropdowns. Primarely used to have a single point of entry for dropdown content used by the search bar dropdown and the filter tag dropdowns

const MyApp = () => (
  <TableActions.Provider
    initialSearchTerm={{}}
    initialFilters={{}}
    onFilterChange={() => {}}
    renderDropdownContent={<div>The shared content that will appear in the Dropdown</div>}
  >
    {/*
        Render the rest of your content here.
    */}
  </TableActions.Provider>
);

TableActions.ActionBar

A wrapper component which sets the right positioning of elements. This is a simple dumb component with no logic.

Prop	Type	Description
leftHandActions	ReactNode	Render slot the left. Usually, you will want to add you search bar and dropdown here
rightHandActions	ReactNode	Render slot for right. The pager should be here
children	ReactNode

const MyApp = () => (
  <TableActions.ActionBar
    leftHandActions={<div>this div will appear on the left</div>}
    rightHandActions={<div>this div will appear on the right</div>}
  >
    <div>this div will appear underneath the previously set actions</div>
  </TableActions.ActionBar>
);

TableActions.SearchBar

A prebuilt search bar component hooked onto the filtering context. Simply add and use.

Pressing enter or clicking on the button will trigger a change to the stored search term within the provider and cause onFilterChange to be executed.

Prop	Type	Description
buttonText	string	Text that appears on the search button
buttonTitle	string	Text for title attribute of the search button
placeholder	string	Placeholder text that appears on the search input
disabled	bool	Set to true to disable search input and search button

const MyApp = () => (
  <TableActions.Provider
    initalSearchTerm="I will automatically appear in the search bar"
    onFilterChange={(filters, searchTerm) => {
      // When pressing enter on the search bar or clicking on the submit button,
      // This function will be triggered
    }}
    renderDropdownContent={<div>The shared content that will appear in the Dropdown</div>}
  >
    <TableActions.SearchBar placeholder="Put your search term here" buttonText="Search" />
  </TableActions.Provider>
);

TableActions.FilterTagLister

A list of all Filters active. Automatically hooked to the TableActions.FilterPanelProvider. It will automatically select the right dropdown view, based on which tag has been picked.

Prop	Type	Description
renderDropdown	ReactNode	(Optional) Override of the provider's renderDropdownContent
dropdownWidth	ReactNode	Width of the dropdown
children	ReactNode

const MyApp = () => (
  <TableActions.Provider
    initalFilters={{
      status: {
        value: 'Any value to store relevant data for the filtering process'
        label: 'This is what will appear on a tag'
      }
    }}
    renderDropdownContent={
        <TableActions.Dropdown>
          {/*
            Notice how the initialFilters object has `status` as an object key
            If we want the TableActions.FilterTagLister to pick up the right
            TableActions.DropdownSection, ensure that the key and filterKey match!
          */}
          <TableActions.DropdownSection title="Just some title" filterKey="status">
            Anything in the `TableActions.DropdownSection` will be rendered when clicking
            on the Tag generated from `TableActions.FilterTagLister`
          </TableActions.DropdownSection>
        </TableActions.Dropdown>
    }
  >
    <TableActions.FilterTagLister />
  </TableActions.Provider>
);

TableActions.DropdownMenu

A wrapper component which will render automatically render the TableActions.Dropdown acquired from the provider. It will handle swapping between a list view or a detailed view.

Prop	Type	Description
renderDropdown	ReactNode	(Optional) Override of the provider's renderDropdownContent
dropdownWidth	ReactNode	Width of the dropdown
children	ReactNode

const MyApp = () => (
  <TableActions.Provider
    renderDropdownContent={
      <TableActions.Dropdown>
        This content will only be rendered within the list view...
        <TableActions.DropdownSection title="Just some title" filterKey="status">
          Anything in the `TableActions.DropdownSection` will be rendered when clicking on the
          corresponding link in the list view.
        </TableActions.DropdownSection>
      </TableActions.Dropdown>
    }
  >
    <TableActions.DropdownMenu />
  </TableActions.Provider>
);

TableActions.Dropdown

The main Dropdown component to be used within the container. This is needed to create the multi-page approach of the filtering dropdown.

Concretely, there are two pages within this dropdown: The listing page and the details page.

The "listing" page is simply whatever components passed in as child to the TableActions.Dropdown. It'll render whatever is passed in as is, with the exception of TableActions.DropdownSection.

If a TableActions.DropdownSection is detected, that component will instead output a clickable menu item. When clicked, the dropdown view will automatically swap to render out the given TableActions.DropdownSection children elements instead.

Prop	Type	Description
goBackText	string	Text that appears on the "back" button within a details view. Automatically hidden when rendered within a tag.

TableActions.DropdownSection

A section/page of the dropdown. Use this component to automatically create the filter menu within the Dropdown, as well as rendering a "details" view that will be rendered when selected.

Prop	Type	Description
title	string	Text that appears on the list view of the dropdown
filterKey	string	Identifier for the section. For syncing the rendering of a section to a given tag
children	ReactNode

TableActions.DropdownTitle

A pre configured version of Cirrus Text to fit the dropdown styling.

TableActions.DropdownActions

A pre configured version of Cirrus Flex to fit within dropdown styling. Use this to output your filter buttons.

TableActions.DropdownDivider

A pre configured version of Cirrus Divider. Use this to add a properly padded seperator between elements.

TableActions.DropdownButtonLink

A pre configured version of Cirrus Button that makes a button look like a link for usage within the Dropdown.

TableActions.CheckboxGroup

A prestyled and context aware checkbox group.

Prop	Type	Description
checkboxes	Array<{ label: string, value: string}>	Config object to generate checkboxes. Simply pass in the label and the associated value
filterKey	string	Identifier for the filter. Use this to bind the child functions to the appropriate filter key
children	Child function ReactNode	Accepts a child function. It forwards an object with two following functions: undoChanges and applyFilter. undoChanges will clear the internal state of the checkbox group but not trigger an actual filter change. applyFilter accepts either a string to be applied as the label for a given tag or a callback function that sends the selected items in parameter and expects a string in return

TableActions.RadioGroup

A prestyled and context aware radio group.

Prop	Type	Description
radios	Array<{ label: string, value: string}>	Config object to generate radios. Simply pass in the label and the associated value
filterKey	string	Identifier for the filter. Use this to bind the child functions to the appropriate filter key
children	Child function ReactNode	Accepts a child function. It forwards an object with two following functions: undoChanges and applyFilter. undoChanges will clear the internal state of the radio group but not trigger an actual filter change. applyFilter accepts either a string to be applied as the label for a given tag or a callback function that sends the selected items in parameter and expects a string in return

All About Table Features

The Basics

By default, the table is completely stateless and allows you to build and structure it however you want, since the table provides multiple small building blocks.

We also provide some pre-built functionality in form of hooks that you can use immediately with the provided components.

The Sort Feature

Sort exports a hook that pre-binds state as well as a convenient SortButton component and a pre-built Th component that you can slide into the appropriate spot of the table.

import { Table, Thead, Tr, Td, Sortable } from '@lightspeed/cirrus-table';

const MyComponent = () => {
  const {  getSortingDirection, toggleSort, sortKey, sortDirection, setSort }  = Sortable.useSortable();
  // Observe our sortKey/sortDirection for any changes
  React.useEffect(() => {
      // And trigger a side-effect!
    }
  }, [sortKey, sortDirection]);

  return (
    <Card>
      {/* You can use setSort to force save a particular sort state */}
      <button onClick={() => setSort('animal', 'desc')}>
        Descending animals
      </button>

      <Table>
        <Thead>
          <Tr>
          <Sortable.Th
            onClick={toggleSort('animal') /* toggleSort automatically cycle through the sort */}
            direction={getSortingDirection('animal') /* Fully uncontrolled props*/}
          >
            Animal
          </Sortable.Th>
          </Tr>
        </Thead>
        <Tr>
          <Td>Lion</Td>
        </Tr>
        <Tr>
          <Td>Tiger</Td>
        </Tr>
        <Tr>
          <Td>Bear</Td>
        </Tr>
      </Table>
    </Card>
  );
}

Options

Sortable.useSortable

This hook takes two parameters, the first one is the sorting key and second value is the sort order.

Use this to set a default sort order.

const MyComponent = () => {
  const { getSortingDirection } = Sortable.useSortable('color', 'asc');

  getSortingDirection('color'); // this will return `asc`
  toggleSort('color'); // This will cycle through the next sorting direction...
  getSortingDirection('color'); // meaning this will now return `desc`

  // ...
};

As per UX, only one item can be sorted at a time, and it will always follow the following cycle:

unsorted -> ascending -> descending

Important note: as of right now, we only support 1 sort option at a time.

Components

<Sortable.SortButton>

Prop	Type	Description
direction	string	The direction of the arrow for sorting

<Sortable.Th>

Convenience compone that simply wraps the SortButton inside a Th.

Prop	Type	Description
direction	string	The direction of the arrow for sorting
onClick	function	Good ol' function

Examples

See the examples folder.

The Batch Select Feature

Batch Select exposes multiple components as well a hook to manage state. You may use both of them, or mix and match functionalities.

While there may be many functions to bind, most of them are fairly straight forwards to use and self explanatory.

Example

import { Table, Thead, TBody, Td, BatchSelect } from '@lightspeed/cirrus-table';

const MyApp = () => {
  const {
    itemsSelectedCount,
    toggleAllItems,
    isItemSelected,
    isAllItemsSelected,
    isPartiallySelected,
    toggleItem,
  } = BatchSelect.useBatchSelect(data, {
    idKey: 'id',
    initialSelectedItems: [],
  });

  return (
    <Table>
      <Thead>
        <BatchSelect.HeaderTr
          itemsSelectedCount={itemsSelectedCount}
          selectedItemsText={`${itemsSelectedCount} selected item${
            itemsSelectedCount > 1 ? 's' : ''
          }`}
          checkboxProps={{
            checked: isAllItemsSelected,
            indeterminate: isPartiallySelected,
            onChange: toggleAllItems,
          }}
        >
          <Th>Name</Th>
          <Th>Updated at</Th>
          <Th>Visible</Th>
        </BatchSelect.HeaderTr>
      </Thead>
      <TBody>
        {data.map(item => (
          <BatchSelect.Tr
            key={item.id}
            selected={isItemSelected(item.id)}
            checkboxProps={{
              checked: isItemSelected(item.id),
              onChange: () => {
                toggleItem(item.id);
              },
            }}
          >
            <Td>{item.name}</Td>
            <Td width="150px">{item.updatedAt}</Td>
            <Td width="150px">{item.isVisible}</Td>
          </BatchSelect.Tr>
        ))}
      </TBody>
    </Table>
  );
};

BatchSelect.useBatchSelect

The userBatchSelect hook is used to track what items have been selected.

useBatchSelect accepts a configuration object

const {} = BatchSelect.useBatchSelect(data, {
  idKey: 'id', // optional
  selectedItems: [], // optional
});

Key	Is Required?	Description
data	Required	useBatchSelect will use that data to appropriately track what items are selected or not. useBatchSelect will NOT mutate the data
idKey	Optional	Change the tracking identifier. By default, useBatchSelect will only keep track of the id key within the data object.
selectedItems	Optional	Preselect items by forwarding an array of id (or whatever unique indentifier). By default, this field is an empty array.

useBatchSelect returns the following variables:

Name	Description
selectedItems	Get the list of all item IDs that are currently selected
itemsSelectedCount	Get a numeric count of the selectedItems
isAllItemsSelected	Return a boolean value of whether or not the selectedItems is empty or has all items contained within
isPartiallySelected	return a boolean value of whether or not there is at least 1 item selected, but not all items selected

useBatchSelect returns the following functions

Name	Params	Description
isItemSelected	itemID	Checks whether or not an item is selected
toggleItem	itemID	Automatically add or remove an item from the selectedItems list.
toggleAllItems	-	Automatically add or remove ALL items from the selectedItems list.
selectItem	itemID	Add an item to the selectedItems list.
deselectItem	itemID	Remove an item from the selectedItems list.
selectAll	-	Add all items to the SelectedItems list.
deselectAll	-	Remove all items from the SelectedItems list.

<BatchSelect.HeaderTr>

An augmented header table row <Tr> that handles adding the initial checkbox column and swapping out the table header row to use an action group when items are selected. This component is a wrapper on top of <BatchSelect.CheckboxWell> and handles the logic of replacing table headers with a <BatchSelect.CheckboxWell> when an item is selected.

Prop	Type	Description
itemsSelectedCount	number	Quantity of items selected.
selectedItemsText	ReactNode	The text or element to appear right beside the checkbox when at least one item is selected.
innerGroup	ReactNode	Slot to render elements to be attached to the right of the checkbox addon
outerGroup	ReactNode	Slot to render elements outside of the checkbox addon group.
checkboxProps	HTMLCheckboxElement	Same properties as a regular cirrus Checkbox
children	ReactNode	Typically, we put the table header (<Th> or <th>) elements here

<BatchSelect.Checkbox>

A specially styled cirrus checkbox for the table. Features a slightly larger hit box.

<BatchSelect.CheckboxWell>

A special checkbox that is wrapped in a container and can have an attached button to it.

Prop	Type	Description
selectedItemsText	ReactNode	The text or element to appear right beside the checkbox when at least one item is selected.
innerGroup	ReactNode	Slot to render elements to be attached to the right of the checkbox addon
outerGroup	ReactNode	Slot to render elements outside of the checkbox addon group.
checked	boolean	-
indeterminate	boolean	-
onChange	boolean	Event handler attached on the Checkbox
children	ReactNode	Typically, we put the table header (<Th> or <th>) elements here

<BatchSelect.Tr>

An augmented table row <Tr> that injects a checkbox in the first <Td />. Use this component when you do not want to bother with adjusting padding and margins to match specs.

Prop	Type	Description
checkboxProps	HTMLCheckboxElement	Same properties as a regular cirrus Checkbox
...restProps	Tr	Same properties as the Tr component

<BatchSelect.Dropdown>

A custom dropdown component for the table.

Prop	Type	Description
title	string	The text content of the dropdown button
children	ReactNode	What will be rendered within the dropdown menu when the dropdown button is clicked. BatchSelect. Dropdown can also take a child function. Destructuring it will give back a toggleOpen function to programatically close the menu.

example

<BatchSelect.Dropdown title="Action">
  <BatchSelect.DropdownList>
    <li>An element</li>
    <li>Another element</li>
  </BatchSelect.DropdownList>
</BatchSelect.Dropdown>

// If we need access to toggleOpen function...
<BatchSelect.Dropdown title="Action">
  {({ toggleOpen }) => (
    <BatchSelect.DropdownList>
    <li>An element</li>
    <li>
      <button onClick={toggleOpen}>Close dropdown</button>
    </li>
  </BatchSelect.DropdownList>
  )}
</BatchSelect.Dropdown>

<BatchSelect.DropdownList>

A prestyled <ul> element to be used within the dropdown.

example:

<BatchSelect.DropdownList>
  <li>An element</li>
  <li>Another element</li>
</BatchSelect.DropdownList>

<BatchSelect.BulkButton>

A prestyled cirrus <Button> element to be used within a BatchSelect.HeaderTr or BatchSelect.CheckboxWell inner group.

The Draggable feature

Draggable enables to drag and drop rows to for the purpose of sorthing them.

The draggable feature is a collection of pre-bound HOC elements that uses the react-sortable-hoc library.

<Draggable.Table>

A Table that uses the SortableContainer HOC and pre-binds certain props for convenience sake.

It takes care of setting column sizes on drag, adding a helper class and styling the rows.

The <Draggable.Table> takes the exact same props as a regular <Table>, as well as all the props provided by SortableContainer react-sortable-hoc.

In general, you will only need to your own sorting callback on the onSortEnd prop.

The <Draggable.Table> will automatically enable the useDragHandle prop, meaning it will be required to add a drag handle to your rows. You may of course always set the useDragHandle prop to false.

example

import { Tbody, Td, Draggable } from '@lightspeed/cirrus-table';

const MyApp = () => {
  return (
    <Draggable.Table
      onSortEnd={(({oldIndex, newIndex, collection, isKeySorting})) => {
        console.log('Do your sorting here');
      }}
    >
      <Tbody>
        {/* Add whatever elements */}
      </Tbody>
    </Draggable.Table>
  );
};

<Draggable.Tr> & <Draggable.DragHandle />

<Draggable.Tr> is a <Tr /> that uses the SortableElement HOC. Enables the row to be moved.

<Draggable.DragHandle /> is basically a pre-styled Icon with the SortableHandle HOC applied.

For further details, please consult the react-sortable-hoc library.

Important note: You need to add the index prop on <Draggable.Tr> for proper tracking of row position. You will also need to include the <Draggable.DragHandle /> inside the row, or else you will not be able to move the row. Should you wish to be able to drag the row no matter the cursor location, you may set useDragHandle on the <Draggable.Tbody> to false.

import { Flex } from '@lightspeed/cirrus/core';
import { Table, Draggable, Td } from '@lightspeed/cirrus-table';

const MyApp = () => {
  return (
    <Draggable.Table>
      <Tbody>
        {data.map((item, index) => (
            {/* Notice the presence of the `index` prop. This is important to add! */}
            <Draggable.Tr key={item.id} index={index}>
              <Td>
                {/* Use the Draggable.DragHandle. Or else the row cannot be dragged. */}
                <Draggable.DragHandle>
                  {item.name}
                </Draggable.DragHandle>
              </Td>
              <Td textAlign="right">{item.price}</Td>
            </Draggable.Tr>
          ))}
      </Tbody>
    </Draggable.Table>
  );
};