Relate by UI - Relatable

This package is part of the Relate by UI Kit, an opiniated collection of components and styles based on Semantic UI.

This package provides an abstraction over the react-table API to facilitate creating performant data tables.

Table of Contents

1. Basic Usage
2. Advanced Usage
3. Base Components
4. Exposed Typings
5. Add-ons
6. Further Enhancements

Basic usage

import React from 'react';
import Relatable from '@relate-by-ui/relatable';

// see https://react-table.js.org/api/usetable
const COLUMNS = []
const DATA = []

const ATable = () => <Relatable columns={COLUMNS} data={DATA}/>

Advanced usage

import React from 'react';
import Relatable, {Table, Toolbar, Pagination} from '@relate-by-ui/relatable';

// see https://react-table.js.org/api/usetable
const COLUMNS = []
const DATA = []

const ATable = () => (
  <Relatable columns={COLUMNS} data={DATA}>
    <Toolbar/>
    <Table/>
    <Pagination/>
  </Relatable>
)

Base components

There are currently four components available:

• Relatable (default)
• Table
• Toolbar
• Pagination

Relatable (default)

Source

The base component of the library.

import React from 'react';
import {
  StateChangeHandler,
  ITableProps,
  IWithFiltersOptions,
  IWithGroupingOptions,
  IWithSortingOptions,
  IWithPaginationOptions,
  IWithExpandedOptions,
  IWithSelectionOptions
} from '@relate-by-ui/relatable'

export interface IRelatableProps {
  // see https://react-table.js.org/api/usetable
  columns: any[];
  data: any[];
  defaultColumn?: any;
  
  // Relatable state change handler
  onStateChange?: StateChangeHandler;
  
  // add on options
  filterable?: boolean | IWithFiltersOptions;
  groupable?: boolean | IWithGroupingOptions;
  sortable?: boolean | IWithSortingOptions;
  expandable?: boolean | IWithExpandedOptions;
  paginated?: boolean | IWithPaginationOptions;
  selectable?: boolean | IWithSelectionOptions;
}

// when used without children, Table props are passed along as well
export interface IRelatableBasicProps extends IRelatableProps, ITableProps {
}

export interface IRelatableChildrenProps extends React.PropsWithChildren<IRelatableProps> {
}

function Relatable(props: IRelatableChildrenProps | IRelatableBasicProps): JSX.Element;

Table

Source

The Table component of the library.

export interface ITableProps {
  // used for rendering loading animation and empty rows
  loading?: boolean;
  expectedRowCount?: number;
  headless?: boolean;

  // semantic ui react props https://react.semantic-ui.com/collections/table/
  attached?: boolean | string;
  basic?: boolean | string;
  className?: string;
  collapsing?: boolean;
  color?: string;
  compact?: boolean | string;
  definition?: boolean;
  fixed?: boolean;
  inverted?: boolean;
  padded?: boolean | string;
  singleLine?: boolean;
  size?: string;
  striped?: boolean;
  structured?: boolean;
  textAlign?: string;
  verticalAlign?: string;
}

function Table({ loading, expectedRowCount, ...rest }: ITableProps): JSX.Element;

Toolbar

Source

The Toolbar component of the library. Enables basic interaction for:

• Groupable
• Filterable
• Sortable
• Selectable

See Toolbar Items for examples on how to create your own interactive elements for the table.

import React from 'react';
import {MenuProps} from 'semantic-ui-react';

function Toolbar(props: React.PropsWithChildren<MenuProps> = {}): JSX.Element;

Basic Usage

import React from 'react';
import Relatable, {Table, Toolbar} from '@relate-by-ui/relatable';

// see https://react-table.js.org/api/usetable
const COLUMNS = []
const DATA = []

const ATable = () => (
  <Relatable columns={COLUMNS} data={DATA}>
    <Toolbar/>
    <Table/>
  </Relatable>
)

Advanced Usage

import React from 'react';
import Relatable, {Table, Toolbar, FilterableToolbar, GroupableToolbar} from '@relate-by-ui/relatable';

// see https://react-table.js.org/api/usetable
const COLUMNS = []
const DATA = []

const ATable = () => (
  <Relatable columns={COLUMNS} data={DATA}>
    <Toolbar>
      <FilterableToolbar/>
      <GroupableToolbar/>
    </Toolbar>
    <Table/>
  </Relatable>
)

Pagination

Source

The Pagination component of the library.

import {PaginationProps} from 'semantic-ui-react';

import {Omit} from './<internal>'

export interface IPaginationProps extends Omit<PaginationProps, 'totalPages'>{
  totalPages?: number;
}

function Pagination(props: IPaginationProps = {}): JSX.Element;

Exposed typings

Source

import {
  Row,
  ColumnInstance,
  UseExpandedRowProps,
  UseGroupByColumnProps,
  UseFiltersColumnProps,
  UseSortByColumnProps,
  Cell,
} from 'react-table';

export type CellCollSpanGetter<Data extends object = any> = (cell: Cell<Data>) => number | string | undefined;
export type StateChangeHandler = (state: any, changedKeys: string[]) => void;
export type PageSetter = (pageIndex: number) => void;
export type PageSizeSetter = (pageSize: number) => void;
export type GroupSetter<Data extends object = any> = (column: (ColumnInstance<Data> & UseGroupByColumnProps<Data>), group: boolean) => void;
export type ExpandSetter<Data extends object = any> = (rows: (Row<Data> & UseExpandedRowProps<Data>)[], expand: boolean) => void;
export type SelectSetter<Data extends object = any> = (rows: Row<Data>[], select: boolean) => void;

/* Sorting */
export enum SORT_ACTIONS {
  SORT_CLEAR = 'SORT_CLEAR',
  SORT_DESC = 'SORT_DESC',
  SORT_ASC = 'SORT_ASC',
}

export type SortSetter<Data extends object = any> = (column: (ColumnInstance<Data> & UseSortByColumnProps<Data>), action: SORT_ACTIONS) => void;

/* Filters */
export enum FILTER_ACTIONS {
  FILTER_CLEAR = 'FILTER_CLEAR',
  FILTER_ADD = 'FILTER_ADD',
  FILTER_REMOVE = 'FILTER_REMOVE',
}

export type FilterSetter<Data extends object = any> = (column: (ColumnInstance<Data> & UseFiltersColumnProps<Data>), action: FILTER_ACTIONS, values: any[]) => void;

Add-ons

There are currently six add-ons available:

1. Filterable
2. Groupable
3. Sortable
4. Expandable
5. Paginated
6. Selectable

Please note that add-ons are ordinal, as defined by the react-table API, and subject to the Rules of Hooks.

Filterable

react-table hook

Source

Enables filtering of table. Please ensure the Toolbar component is rendered in advanced use cases.

Parameters:

import { IdType, UseFiltersOptions } from 'react-table';
import { IFilterFieldProps, FilterSetter, FilterFunc } from '@relate-by-ui/relatable';

export interface IWithFiltersOptions<Data extends object = any> extends UseFiltersOptions<Data> {
  defaultFilterCell?: React.FC<IFilterFieldProps>;
  defaultFilterFunc?: FilterFunc<Data>;
  onFilterChange?: FilterSetter<Data>;

  // react-table state override https://react-table.js.org/api/useFilters
  filters?: {id: IdType<Data>, value: any}[];
}

Usage

import React from 'react';
import Relatable, {IWithFiltersOptions} from '@relate-by-ui/relatable';

const options: IWithFiltersOptions = {}
const FilterableTable = () => <Relatable
  columns={[]}
  data={[]}
  filterable={true || options}
/>

Groupable

react-table hook

Source

Enables grouping of table rows. Please ensure the Toolbar component is rendered in advanced use cases.

Parameters:

import { IdType, UseGroupByOptions } from 'react-table';
import { ICellProps, GroupSetter } from '@relate-by-ui/relatable';

export interface IWithGroupingOptions<Data extends object = any> extends UseGroupByOptions<Data> {
  defaultAggregate?: string[] | string | ((values: any[]) => any);
  defaultAggregateCell?: React.FC<ICellProps>;
  onGroupChange?: GroupSetter<Data>;

  // react-table state override https://react-table.js.org/api/useGroupBy
  groupBy?: IdType<Data>[];
}

Usage

import React from 'react';
import Relatable, {IWithGroupingOptions} from '@relate-by-ui/relatable';

const options: IWithGroupingOptions = {}
const GroupableTable = () => <Relatable
  columns={[]}
  data={[]}
  groupable={true || options}
/>

Sortable

react-table hook

Source

Enables sorting of table.

Parameters:

import { SortingRule, UseSortByOptions } from 'react-table';
import {SortSetter} from '@relate-by-ui/relatable';

export interface IWithSortingOptions<Data extends object = any> extends UseSortByOptions<Data> {
  onSortChange?: SortSetter<Data>;

  // react-table state override https://react-table.js.org/api/useSortBy
  sortBy?: SortingRule<Data>[];
}

Usage

import Relatable, {IWithSortingOptions} from '@relate-by-ui/relatable';

const options: IWithSortingOptions = {}
const SortableTable = () => <Relatable
  columns={[]}
  data={[]}
  sortable={true || options}
/>

Expandable

react-table hook

Source

Enables expanding rows of table.

Parameters:

import { IdType, UseExpandedOptions } from 'react-table';
import {ExpandSetter, IRowProps} from '@relate-by-ui/relatable';

export interface IWithExpandedOptions<Data extends object = any> extends UseExpandedOptions<Data> {
  onExpandedChange?: ExpandSetter<Data>;
  expandedRowComponent?: React.FC<IRowProps>;

  // react-table state override https://react-table.js.org/api/useExpanded
  expanded?: IdType<Data>[];
}

Usage

import Relatable, {IWithExpandedOptions} from '@relate-by-ui/relatable';

const options: IWithExpandedOptions = {}
const ExpandableTable = () => <Relatable
  columns={[]}
  data={[]}
  expandable={true || options}
/>

Paginated

react-table hook

Source

Enables pagination of table. Please ensure the Pagination component is rendered in advanced use cases.

Parameters:

import { UsePaginationOptions } from 'react-table';
import {PageSetter, PageSizeSetter} from '@relate-by-ui/relatable';

export interface IWithPaginationOptions<Data extends object = any> extends UsePaginationOptions<Data> {
  onPageChange?: PageSetter;
  onPageSizeChange?: PageSizeSetter;
  pageSizeOptions?: number[];

  // react-table state overrides https://react-table.js.org/api/usePagination
  pageSize?: number;
  pageIndex?: number;
}

Usage

import Relatable, {IWithPaginationOptions} from '@relate-by-ui/relatable';

const options: IWithPaginationOptions = {}
const PaginatedTable = () => <Relatable
  columns={[]}
  data={[]}
  paginated={true || options}
/>

Selectable

react-table hook

Source

Enables selection of table rows. Please ensure the Toolbar component is rendered in advanced use cases.

Parameters:

import { UseRowSelectOptions } from 'react-table';
import { SelectSetter } from '@relate-by-ui/relatable';

export interface IWithSelectionOptions<Data extends object = any> extends UseRowSelectOptions<Data> {
  onSelectionChange?: SelectSetter<Data>;

  // react-table state override https://react-table.js.org/api/useRowSelect
  selectedRowPaths?: {[id: string]: boolean};
}

Usage

import Relatable, {IWithSelectionOptions} from '@relate-by-ui/relatable';

const options: IWithSelectionOptions = {}
const SelectableTable = () => <Relatable
  columns={[]}
  data={[]}
  paginated={true || options}
/>

Further Enhancements

Cell Renderers

The react-table API allows you to specify custom Cells, Aggregates, and Filters for columns. As a courtesy this library provides some standard components for this purpose. You can create your own simply by copying the implementation.

Cell values

• TextCell
• DateCell
• NumberCell
• JSONCell

Aggregate cell values

• ValueAggregate

Column filter fields

• TextFilter

Toolbar Items

As a courtesy this library provides some standard components for enabling add-on interactions. You can create your own simply by copying the implementation.

• GroupableToolbar
• FilterableToolbar
• SortableToolbar
• SelectableToolbar