@veeqo/ui 0.0.1 → 0.0.3

package/src/components/DataTable/DataTableDocs.mdx

@@ -0,0 +1,625 @@
+import { Meta, Primary, Controls, Story } from '@storybook/blocks';
+import { Text } from '../Text';
+import { Button } from '../Button';
+import { Stack } from '../Stack';
+import { DataTable } from '.';
+import * as DataTableStories from './DataTable.stories';
+
+<Meta of={DataTableStories} />
+
+# DataTable
+
+Table are the beating heart of Veeqo ❤️ They help our users understand their orders, manage inventory levels and review reports, so it's important that they're clear, informative and provide obvious affordances for performing actions.
+
+> **_Deprecated: Use DataTableExp_**
+
+<Primary />
+
+<Controls />
+
+## Contents
+
+- [Usage](#usage)
+- [Populating the table](#populating-the-table)
+- [Configuring headers](#configuring-headers)
+- [Adding a footer](#adding-a-footer)
+- [Selecting rows](#selecting-rows)
+- [Disable selection input of some rows](#disable-selection-input-of-some-rows)
+- [Sorting](#sorting)
+- [Fixed columns](#fixed-columns)
+- [Nested rows](#nested-rows)
+- [Cell sub-components](#cell-sub-components)
+- [Specific states](#specific-states)
+- [Loading state](#loading-state)
+- [Props](#props)
+
+## Usage
+
+```jsx
+import { VeeqoCommon } from '@veeqo/components';
+const { DataTable } = VeeqoCommon;
+
+<DataTable
+  rows={[...]}
+  renderRow={(row) => (...)}
+/>
+```
+
+## Populating the table
+
+To start populating the table, we must assign 2 props - `rows` and `renderRow`.
+
+We'll pass an array of data to `rows` and then create a handler for `renderRow` which takes some row data and returns multiple cells wrapped inside a `React.Fragment`.
+
+```jsx
+const ProductTable = () => {
+  const rows = [
+    {
+      id: 1,
+      data: {
+        name: 'T-Shirt',
+        sku: 'TS-1',
+        quantity: 12
+      },
+      nestedRows: [...],              // optional
+      accentColour: colors.blue.base  // optional
+    },
+    ...
+  ];
+
+  const renderRow = ({ id, data }) => (
+    <>
+      <DataTable.Cell>
+        {data.name}
+      </DataTable.Cell>
+      <DataTable.Cell>
+        {data.sku}
+      </DataTable.Cell>
+      <DataTable.Cell align="right">
+        {data.quantity}
+      </DataTable.Cell>
+    </>
+  );
+
+  return (
+    <DataTable
+      rows={rows}
+      renderRow={renderRow}
+    />
+  );
+}
+```
+
+You can also pass optional `e2eClassNames` as part of `data` object with custom class names:
+
+```
+{
+    e2eClassNames: {
+        body: string
+        row: string
+    }
+}
+```
+
+## Configuring headers
+
+To configure column headers and other options we need to add the `columns` prop, which is an array of header configuration objects:
+
+```js
+const headers = [
+  {
+    id: 1,            // required
+    title: 'Tags',
+    icon: 'tags',
+    onlyIcon: true,  // optional, false by default
+    align: 'center',
+    sortable: false,
+    grow: false,
+    tooltip: 'This is tooltip' // optional, tooltip won't be shown if not present
+  },
+  ...
+];
+```
+
+The header contents are defined by `title` and `iconName`. If you want an empty header, then simply omit both of those properties.
+
+You can use `align` to specify whether you want the header contents to be aligned `left`, `center` or `right`. Be aware that this will only align the header cell. To align row cells you should use the `align` prop on `<DataTable.Cell>`.
+
+Each column can be marked as `sortable` which adds sorting icons next to the column title and lets the user click on the header cell to change the active sorting order. You can find out more in the [Sorting](#sorting).
+
+Finally you can use the `grow` property to force the column to take up any available space.
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [
+    {
+      id: 'name',
+      title: 'Product name'
+    },
+    {
+      id: 'sku',
+      title: 'SKU',
+      grow: true
+    },
+    {
+      id: 'quantity',
+      title: 'Stock level',
+      align: 'right'
+    }
+  ];
+
+  const renderRow = (row) => (...);
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+    />
+  );
+}
+```
+
+## Rendering Scrollbars
+
+Some browsers may not automatically render a horizontal scrollbar for a table, hiding columns that users may not know they can access.
+
+You can use `showScrollbar` to ensure that a scrollbar will be shown whenever one is required.
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [
+    {
+      id: 'name',
+      title: 'Product name'
+    },
+    {
+      id: 'sku',
+      title: 'SKU',
+    },
+    {
+      id: 'quantity',
+      title: 'Stock level',
+    }
+  ];
+
+  const renderRow = (row) => (...);
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+      showScrollbar={true}
+    />
+  );
+}
+```
+
+## Adding a footer
+
+To add a footer we just need to pass a handler to `renderFooterRow` that returns some cells - exactly the same as using `renderRow`.
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [...];
+
+  const renderRow = (row) => (...);
+
+  const renderFooterRow = (rows) => {
+    const totalQuantity = rows.reduce((sum, row) => sum + row.data.quantity, 0);
+    return (
+      <>
+        <DataTable.Cell />
+        <DataTable.Cell>
+          Total
+        </DataTable.Cell>
+        <DataTable.Cell>
+          {totalQuantity}
+        </DataTable.Cell>
+      </>
+    );
+  };
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+      renderFooterRow={renderFooterRow}
+    />
+  );
+}
+```
+
+## Selecting rows
+
+To enable row selection we'll need to keep track of the selected row IDs and implement a handler to get updates when the selection changes.
+
+You can switch between `multiple` and `single` selection using the `selectionMode` prop - by default this is set to `multiple`.
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [...];
+
+  const renderRow = (row) => (...);
+
+  const [selectedRowIds, setSelectedRowIds] = React.useState([]);
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+      selectedRowIds={selectedRowIds}
+      onChangeSelectedRowIds={setSelectedRowIds}
+      selectionMode="single"
+    />
+  );
+}
+```
+
+## Disable selection input of some rows
+
+You can disable the selection of several rows using the `disabledSelectionInputRowIds` prop.
+
+When `selectionMode` is set to `multiple`, input in the header will be disabled if `disabledSelectionInputRowIds` have at least one element.
+
+```jsx
+const Table = () => {
+  const rows = [
+    {
+      id: 1,
+      ...,
+    },
+    {
+      id: 2,
+      ...,
+    },
+    {
+      id: 'some-id',
+      ...,
+    }
+  ];
+
+  const headers = [...];
+
+  const renderRow = (row) => (...);
+
+  const [selectedRowIds, setSelectedRowIds] = React.useState([]);
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+      selectedRowIds={selectedRowIds}
+      onChangeSelectedRowIds={setSelectedRowIds}
+      selectionMode="single"
+      disabledSelectionInputRowIds={[1, 'some-id']}
+    />
+  );
+}
+```
+
+## Sorting
+
+> **Important:** `DataTable` does not actually implement any kind of data sorting. You must handle this yourself before passing data via the `rows` prop. Rows will be rendered in the order that they are passed in the array.
+
+To enable sorting, we begin by marking the relevant columns as `sortable`. This adds a sorting icon to the column header and makes it clickable:
+
+```jsx
+const headers = [
+  ...
+  {
+    id: 'name',
+    sortable: true,
+    ...
+  }
+];
+```
+
+Next we need to specify which column is current being sorted and the direction. To do this we implement `sortColumnId` and `sortDirection`.
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [
+    { id: 'name', title: 'Product name', sortable: true },
+    { id: 'sku', title: 'SKU', grow: true },
+    { id: 'quantity', title: 'Stock level', align: 'right', sortable: true }
+  ];
+
+  const renderRow = (row) => (...);
+
+  const [sortColumnId, setSortColumnId] = React.useState('name');
+  const [sortDirection, setSortDirection] = React.useState('ascending');
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={rows}
+      renderRow={renderRow}
+      sortColumnId={sortColumnId}
+      sortColumnDirection={sortDirection}
+    />
+  );
+}
+```
+
+Finally we need to pass a handler to `onChangeSort` to be notified when the user clicks a column header and changes the sorting options.
+
+Here's an example of how we could utilise header `id` properties to implement very simple sorting:
+
+```jsx
+const ProductTable = () => {
+  const rows = [...];
+
+  const headers = [
+    { id: 'name', title: 'Product name', sortable: true },
+    { id: 'sku', title: 'SKU', grow: true },
+    { id: 'quantity', title: 'Stock level', align: 'right', sortable: true }
+  ];
+
+  const renderRow = (row) => (...);
+
+  const [sortColumnId, setSortColumnId] = React.useState('name');
+  const [sortDirection, setSortDirection] = React.useState('ascending');
+
+  const handleChangeSort = (columnId, direction) => {
+    setSortColumnId(columnId);
+    setSortDirection(direction);
+  };
+
+  const sortedRows = rows.sort((rowA, rowB) => {
+    const a = rowA.data[sortColumnId];
+    const b = rowB.data[sortColumnId];
+
+    if (a > b) return 1;
+    if (a < b) return -1;
+    return 0;
+  });
+
+  if (sortDirection === 'descending') {
+    sortedRows.reverse();
+  }
+
+  return (
+    <DataTable
+      headers={headers}
+      rows={sortedRows}
+      renderRow={renderRow}
+      sortColumnId={sortColumnId}
+      sortDirection={sortDirection}
+      onChangeSort={handleChangeSort}
+    />
+  );
+}
+```
+
+## Fixed columns
+
+You can easily enable fixed columns at the beginning and at the end of the table by using props `startFixedColumnsNumber` and `endFixedColumnsNumber` props respectively.
+
+**IMPORTANT:** When you pass these props, [the table layout is changing to fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/table-layout).
+
+To work it correctly, you should pass **numeric** `width` in px in each fixed column. The rest of the columns also need to set the width, but it doesn't require numeric value, you can use percentage if you want. `width` works like a `max-width` so you can don't care about the state without overflow.
+
+````jsx
+<DataTable
+  rows={rows}
+  renderRow={renderRow}
+  headers={headers}
+  startFixedColumnsNumber={2}
+  endFixedColumnsNumber={1}
+  isHeaderSticky={false}
+  showScrollbar={true}
+/>
+```
+
+## Nested rows
+
+Across the Veeqo app it is common that we need to display secondary information that is related to the contents of a table. For example, the inventory page allows customers to break down stock levels by warehouse.
+
+For this, we can use nested rows which will render beneath their "parent" row and can be optionally hidden.
+
+First, we must add the `nestedRows` property to our `rows` data structure. It has the same basic properties as an ordinary row - an `id` and some `data`.
+
+```js
+const rows = [
+  {
+    id: 1,
+    data: { ... },
+    nestedRows: [
+      {
+        id: 1,
+        data: { warehouseName: 'Swansea', quantity: 1 }
+      },
+      {
+        id: 2,
+        data: { warehouseName: 'Toronto', quantity: 3 }
+      }
+    ]
+  }
+];
+````
+
+Next, we define a render method for our nested rows.
+
+```jsx
+const renderNestedRow = ({ id, data }) => (
+  <>
+    <DataTable.Cell />
+    <DataTable.Cell />
+    <DataTable.Cell>
+      {data.warehouseName}
+    </DataTable.Cell>
+    <DataTable.Cell>
+      {data.quantity}
+    </DataTable.Cell>
+  </>
+);
+
+return (
+  <DataTable
+    renderNestedRow={renderNestedRow}
+    ...
+  />
+);
+```
+
+By default all nested rows will be visible, but we can control their visibility by passing an array of row IDs with the `expandedRowIds` prop.
+
+```jsx
+const [expandedRowIds, setExpandedRowIds] = useState([]);
+
+const toggleExpandedRow = (rowId) => {
+  const newIds = [...expandedRowIds];
+  if (newIds.includes(rowId)) {
+    const index = newIds.findIndex((id) => id === rowId);
+    newIds.splice(index, 1);
+  } else {
+    newIds.push(rowId);
+  }
+  setExpandedRowIds(newIds);
+};
+
+const renderRow = ({ id, data }) => {
+  const isExpanded = expandedRowIds.includes(id);
+  return (
+    <>
+      <DataTable.Cell>
+        {data.name}
+      </DataTable.Cell>
+      <DataTable.Cell>
+        {data.sku}
+      </DataTable.Cell>
+      <DataTable.Cell>
+        <Button onClick={() => toggleExpandedRow(id)} variant="link" dropdown>
+          {isExpanded ? 'Hide warehouses' : 'Show warehouses'}
+        </Button>
+      </DataTable.Cell>
+      <DataTable.Cell>
+        {data.quantity}
+      </DataTable.Cell>
+    </>
+  );
+};
+
+return (
+  <DataTable
+    expandedRowIds={expandedRowIds}
+    renderRow={renderRow}
+    ...
+  />
+);
+```
+
+## Cell Sub-components
+
+The most common cell types are provided as sub-components for you to use when rendering rows:
+
+- `DataTable.Cell`
+- `DataTable.ClickableCell`
+- `DataTable.EditableCell`
+- `DataTable.SkeletonCell`
+- `DataTable.SkeletonContent`
+
+## Specific states
+
+Specific states appear when you pass `isError` prop or empty array in `rows` prop
+
+### Empty data
+
+<Story of={DataTableStories.Empty} />
+
+### Error
+
+The error state has a priority higher than empty state. It means that if you pass empty array in `rows` and `isError` prop then error state appear
+
+<Story of={DataTableStories.ErrorState} />
+
+### Custom text and icons
+
+You can also provide any text and icons you want via `customSpecificState` prop
+
+```jsx
+<DataTable
+  rows={[]}
+  headers={headers}
+  customSpecificState={{
+    icon: 'search',
+    title: "Oops! We don't find anything",
+  }}
+/>
+<DataTable
+  rows={[]}
+  headers={headers}
+  customSpecificState={{
+    icon: 'calendar',
+    title: "Oops! Seems you trying to find something that doesn't exist!",
+    subTitle: 'Try again!',
+  }}
+/>
+<DataTable
+  rows={[]}
+  headers={headers}
+  isError
+  customSpecificState={{
+    icon: 'fail',
+    title: 'Something strange has happened',
+    subTitle: 'Try to reload page',
+  }}
+/>
+```
+
+### Body height
+
+Default body height in specific state is 375, but you can pass different value via `bodyHeightInSpecificStates` prop
+
+```jsx
+<DataTable rows={[]} headers={headers} isError bodyHeightInSpecificStates={250} />
+```
+
+## Loading state
+
+To enable the loading state you can add the `isLoading` prop.
+
+By default, rows will be rendered with skeleton content. If you have defined `headers` then each row will contain the same number of cells as there are columns. If `headers` is not defined, then a single cell will be rendered in each row.
+
+```jsx
+<DataTable isLoading={true} />
+```
+
+<Story of={DataTableStories.LoadingState} />
+
+To render custom loading rows, you can implement the `renderLoadingRow` prop:
+
+```jsx
+const renderLoadingRow = () => (
+  <>
+    <DataTable.SkeletonCell />
+    <DataTable.Cell>
+      <DataTable.SkeletonContent style={{ width: '50%' }} />
+    </DataTable.Cell>
+    <CustomLoadingCell />
+  </>
+);
+
+return <DataTable isLoading={true} renderLoadingRow={renderLoadingRow} />;
+```
+
+You can override the number of loading rows shown with `skeletonRowsNumber`:
+
+```jsx
+<DataTable isLoading={true} skeletonRowsNumber={3} />
+```

package/src/components/DataTable/SkeletonContent/SkeletonContent.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import styled from 'styled-components';
+import { theme } from '../../../theme';
+
+const { grey } = theme.colors.neutral;
+
+const SkeletonContentWrapper = styled.div`
+  height: 16px;
+  width: 100%;
+`;
+
+const SkeletonContentComponent = styled.div<{ isLoading?: boolean }>`
+  display: inline-block;
+  color: transparent;
+  border-radius: 4px;
+  animation-duration: ${({ isLoading = true }) => (isLoading ? '1s' : 0)};
+  animation-fill-mode: forwards;
+  animation-iteration-count: infinite;
+  animation-name: placeHolderShimmer;
+  animation-timing-function: linear;
+  background: linear-gradient(to right, ${grey.base} 8%, ${grey.dark} 15%, ${grey.base} 33%);
+  background-size: 800px 104px;
+  border: 0;
+  width: 100%;
+  height: 100%;
+
+  @keyframes placeHolderShimmer {
+    0% {
+      background-position: -380px 0;
+    }
+    100% {
+      background-position: 380px 0;
+    }
+  }
+`;
+
+type SkeletonContentPropTypes = {
+  isLoading?: boolean;
+  style?: React.CSSProperties;
+};
+
+export const SkeletonContent = ({ isLoading, style }: SkeletonContentPropTypes) => (
+  <SkeletonContentWrapper style={style}>
+    <SkeletonContentComponent isLoading={isLoading} />
+  </SkeletonContentWrapper>
+);

package/src/components/DataTable/SkeletonContent/index.ts

@@ -0,0 +1 @@
+export { SkeletonContent } from './SkeletonContent';

package/src/components/DataTable/SpecificState/SpecificState.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+
+import { SpecificStateContainer, EllipseContainer, TitleText, SubTitleText } from './styled';
+
+import { SpecificStateType } from '../utils/types';
+
+type SpecificStatePropTypes = SpecificStateType & {
+  height: number;
+};
+
+export const SpecificState = ({ height, icon, title, subTitle }: SpecificStatePropTypes) => (
+  <SpecificStateContainer height={height}>
+    <EllipseContainer>{icon}</EllipseContainer>
+    <TitleText variant="headingLarge">{title}</TitleText>
+    {subTitle && <SubTitleText variant="subheadingMedium">{subTitle}</SubTitleText>}
+  </SpecificStateContainer>
+);

package/src/components/DataTable/SpecificState/index.ts

@@ -0,0 +1 @@
+export { SpecificState } from './SpecificState';