@relate-by-ui/relatable
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.1 • Public • Published

    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)

    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:

    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

    Aggregate cell values

    Column filter fields

    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.

    Keywords

    none

    Install

    npm i @relate-by-ui/relatable

    DownloadsWeekly Downloads

    1

    Version

    1.0.1

    License

    Apache-2.0

    Unpacked Size

    229 kB

    Total Files

    104

    Last publish

    Collaborators

    • huboneo
    • linuslundahl
    • neo4j-organization