@react-ui-org/react-ui 0.52.1 → 0.53.0

package/src/components/Table/README.md

@@ -0,0 +1,259 @@
+# Table
+
+Table presents complex tabular data in an easy-to-scan way.
+
+## Basic Usage
+
+To implement the Table component, you need to import it first:
+
+```js
+import { Table } from '@react-ui-org/react-ui';
+```
+
+And use it:
+
+```docoff-react-preview
+<Table
+  columns={[
+    {
+      label: 'ID',
+      name: 'id',
+    },
+    {
+      label: 'Name',
+      name: 'name',
+    },
+    {
+      format: (date) => date.toLocaleDateString('en-GB'),
+      label: 'Date of birth',
+      name: 'dateOfBirth',
+    },
+  ]}
+  rows={[
+    {
+      dateOfBirth: new Date(1940, 10, 9),
+      id: 1,
+      name: 'John Lennon',
+    },
+    {
+      dateOfBirth: new Date(1942, 6, 18),
+      id: 2,
+      name: 'Paul McCartney',
+    },
+    {
+      dateOfBirth: new Date(1943, 2, 25),
+      id: 3,
+      name: 'George Harrison',
+    },
+    {
+      dateOfBirth: new Date(1940, 7, 7),
+      id: 4,
+      name: 'Richard Starkey (Ringo Starr)',
+    },
+  ]}
+/>
+```
+
+See [API](#api) for all available options.
+
+## General Guidelines
+
+- **Keep headers short** so users can quickly scan the content of the table.
+  Just one or two words should be enough.
+
+- Tables are **good for displaying complex tabular data.** For simpler data sets
+  or even plain key-value pairs, consider using the
+  [Grid](/components/Grid) component.
+
+- Tables make **lots of information easier to scan and compare.** If you have
+  fewer sections and want to emphasize each group more, consider using
+  [Cards](/components/Card).
+
+## Responsive Tables
+
+The easiest way to make tables responsive is to wrap them with the
+[ScrollView](/components/ScrollView) component in the horizontal mode.
+
+```docoff-react-preview
+<ScrollView direction="horizontal">
+  <Table
+    columns={[
+      {
+        label: 'ID',
+        name: 'id',
+      },
+      {
+        format: (name) => (
+          <span style={{ whiteSpace: 'nowrap' }}>{name}</span>
+        ),
+        label: 'Name',
+        name: 'name',
+      },
+      {
+        format: (note) => (
+          <span style={{ whiteSpace: 'nowrap' }}>{note}</span>
+        ),
+        label: 'Note',
+        name: 'note',
+      },
+      {
+        format: (date) => date.toLocaleDateString('en-GB'),
+        label: 'Date of birth',
+        name: 'dateOfBirth',
+      },
+    ]}
+    rows={[
+      {
+        dateOfBirth: new Date(1940, 10, 9),
+        id: 1,
+        name: 'John Lennon',
+        note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+          + 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+          + 'natoque penatibus et magnis dis parturient montes, nascetur '
+          + 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+          + 'eu, pretium quis, sem.',
+      },
+      {
+        dateOfBirth: new Date(1942, 6, 18),
+        id: 2,
+        name: 'Paul McCartney',
+        note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+          + 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+          + 'natoque penatibus et magnis dis parturient montes, nascetur '
+          + 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+          + 'eu, pretium quis, sem.',
+      },
+      {
+        dateOfBirth: new Date(1943, 2, 25),
+        id: 3,
+        name: 'George Harrison',
+        note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+          + 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+          + 'natoque penatibus et magnis dis parturient montes, nascetur '
+          + 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+          + 'eu, pretium quis, sem.',
+      },
+      {
+        dateOfBirth: new Date(1940, 7, 7),
+        id: 4,
+        name: 'Richard Starkey (Ringo Starr)',
+        note: 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. '
+          + 'Aenean commodo ligula eget dolor. Aenean massa. Cum sociis '
+          + 'natoque penatibus et magnis dis parturient montes, nascetur '
+          + 'ridiculus mus. Donec quam felis, ultricies nec, pellentesque '
+          + 'eu, pretium quis, sem.',
+      },
+    ]}
+  />
+</ScrollView>
+```
+
+## Sortable Columns
+
+The Table supports sorting indicators by adding a simple configuration.
+
+⚠️ The Table component only provides necessary visual support for sorting. Aside
+from icons, you must **provide the comparing functionality yourself** if you
+aren't rendering **already sorted data.** The reason for this decision is that
+client often does not have access to the full dataset.
+
+The following is an example of custom sorting function executed on the client.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [tableSortColumn, setTableSortColumn] = React.useState('id');
+  const [tableSortDirection, setTableSortDirection] = React.useState('asc');
+  const [rows, setRows] = React.useState([
+    {
+      dateOfBirth: new Date(1940, 10, 9),
+      id: 1,
+      name: 'John Lennon',
+    },
+    {
+      dateOfBirth: new Date(1942, 6, 18),
+      id: 2,
+      name: 'Paul McCartney',
+    },
+    {
+      dateOfBirth: new Date(1943, 2, 25),
+      id: 3,
+      name: 'George Harrison',
+    },
+    {
+      dateOfBirth: new Date(1940, 7, 7),
+      id: 4,
+      name: 'Richard Starkey (Ringo Starr)',
+    },
+  ]);
+  const compare = (items, key, direction) => {
+    const sortedItems = [...items];
+    if (key === 'id' || key === 'dateOfBirth') {
+      sortedItems.sort((a, b) => b[key] - a[key]);
+    } else if (key === 'name') {
+      sortedItems.sort((a, b) => {
+        if (a.name > b.name) {
+          return -1;
+        }
+        if (a.name < b.name) {
+          return 1;
+        }
+        return 0;
+      });
+    }
+    return direction === 'desc' ? sortedItems.reverse() : sortedItems;
+  };
+  const columns = [
+    {
+      isSortable: true,
+      label: 'ID',
+      name: 'id',
+    },
+    {
+      isSortable: true,
+      label: 'Name',
+      name: 'name',
+    },
+    {
+      format: (date) => date.toISOString(),
+      isSortable: true,
+      label: 'Date of birth',
+      name: 'dateOfBirth',
+    },
+  ];
+  return (
+    <Table
+      columns={columns}
+      rows={rows}
+      sort={{
+        ascendingIcon: <rui-icon icon="up" />,
+        column: tableSortColumn,
+        descendingIcon: <rui-icon icon="down" />,
+        direction: tableSortDirection,
+        onClick: (column, direction) => {
+          setTableSortColumn(column);
+          setTableSortDirection(direction === 'asc' ? 'desc' : 'asc');
+          setRows(compare(rows, column, direction));
+        },
+      }}
+    />
+  );
+});
+```
+
+## Forwarding HTML Attributes
+
+In addition to the options below in the [component's API](#api) section, you
+can specify [React synthetic events] or **any HTML attribute you like.** All
+attributes that don't interfere with the API are forwarded to the `<table>` HTML
+element. This enables making the component interactive and helps to improve its
+accessibility.
+
+👉 Refer to the MDN reference for the full list of supported attributes of the
+[table] element.
+
+## API
+
+<docoff-react-props src="/components/Table/Table.jsx"></docoff-react-props>
+
+[React synthetic events]: https://reactjs.org/docs/events.html
+[table]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table#attributes

package/src/{lib/components → components}/Table/Table.jsx

@@ -32,7 +32,10 @@ export const Table = ({
     </thead>
     <tbody>
       {rows.map((row) => (
-        <tr key={row.id} className={styles.tableRow}>
+        <tr
+          className={styles.tableRow}
+          key={row.id}
+        >
           {columns.map((column) => (
             <TableBodyCell
               format={column.format}

package/src/{lib/components → components}/Table/_components/TableHeaderCell/TableHeaderCell.jsx

@@ -1,6 +1,6 @@
 import PropTypes from 'prop-types';
 import React from 'react';
-import { Button } from '../../../..';
+import { Button } from '../../../Button';
 import styles from '../TableCell.scss';
 
 export const TableHeaderCell = ({

package/src/{lib/components/Tabs/README.mdx → components/Tabs/README.md}

@@ -1,22 +1,5 @@
----
-name: Tabs
-menu: 'Miscellaneous'
-route: /components/tabs
----
-
 # Tabs
 
-import {
-  Playground,
-  Props,
-} from 'docz'
-import { Icon } from '../../../docs/_components/Icon/Icon'
-import {
-  ScrollView,
-  Tabs,
-  TabsItem,
-} from '../..'
-
 Tabs separate related content into groups within a single context.
 
 ## Basic Usage
@@ -29,37 +12,37 @@ import { Tabs, TabsItem } from '@react-ui-org/react-ui';
 
 And use it:
 
-<Playground>
-  {() => {
-    const [activeTab, setActiveTab] = React.useState(1);
-    const navigate = (event, tab) => {
-      setActiveTab(tab);
-      event.preventDefault();
-    };
-    return (
-      <Tabs>
-        <TabsItem
-          href="#design"
-          isActive={activeTab === 1}
-          label="Design"
-          onClick={(e) => navigate(e, 1)}
-        />
-        <TabsItem
-          href="#code"
-          isActive={activeTab === 2}
-          label="Code"
-          onClick={(e) => navigate(e, 2)}
-        />
-        <TabsItem
-          href="#resources"
-          isActive={activeTab === 3}
-          label="Resources"
-          onClick={(e) => navigate(e, 3)}
-        />
-      </Tabs>
-    );
-  }}
-</Playground>
+```docoff-react-preview
+React.createElement(() => {
+  const [activeTab, setActiveTab] = React.useState(1);
+  const navigate = (event, tab) => {
+    setActiveTab(tab);
+    event.preventDefault();
+  };
+  return (
+    <Tabs>
+      <TabsItem
+        href="#design"
+        isActive={activeTab === 1}
+        label="Design"
+        onClick={(e) => navigate(e, 1)}
+      />
+      <TabsItem
+        href="#code"
+        isActive={activeTab === 2}
+        label="Code"
+        onClick={(e) => navigate(e, 2)}
+      />
+      <TabsItem
+        href="#resources"
+        isActive={activeTab === 3}
+        label="Resources"
+        onClick={(e) => navigate(e, 3)}
+      />
+    </Tabs>
+  );
+})
+```
 
 See [API](#api) for all available options.
 
@@ -82,101 +65,101 @@ See [API](#api) for all available options.
 Tab titles can be accompanied by icons. Once you decide to have icons, use one
 for each tab and don't leave some tabs without an icon.
 
-<Playground>
-  {() => {
-    const [activeTab, setActiveTab] = React.useState(1);
-    const navigate = (event, tab) => {
-      setActiveTab(tab);
-      event.preventDefault();
-    };
-    return (
-      <Tabs>
-        <TabsItem
-          beforeLabel={<Icon icon="pencil" />}
-          href="#design"
-          isActive={activeTab === 1}
-          label="Design"
-          onClick={(e) => navigate(e, 1)}
-        />
-        <TabsItem
-          beforeLabel={<Icon icon="code" />}
-          href="#code"
-          isActive={activeTab === 2}
-          label="Code"
-          onClick={(e) => navigate(e, 2)}
-        />
-        <TabsItem
-          beforeLabel={<Icon icon="star" />}
-          href="#resources"
-          isActive={activeTab === 3}
-          label="Resources"
-          onClick={(e) => navigate(e, 3)}
-        />
-      </Tabs>
-    );
-  }}
-</Playground>
+```docoff-react-preview
+React.createElement(() => {
+  const [activeTab, setActiveTab] = React.useState(1);
+  const navigate = (event, tab) => {
+    setActiveTab(tab);
+    event.preventDefault();
+  };
+  return (
+    <Tabs>
+      <TabsItem
+        beforeLabel={<rui-icon icon="pencil" />}
+        href="#design"
+        isActive={activeTab === 1}
+        label="Design"
+        onClick={(e) => navigate(e, 1)}
+      />
+      <TabsItem
+        beforeLabel={<rui-icon icon="code" />}
+        href="#code"
+        isActive={activeTab === 2}
+        label="Code"
+        onClick={(e) => navigate(e, 2)}
+      />
+      <TabsItem
+        beforeLabel={<rui-icon icon="star" />}
+        href="#resources"
+        isActive={activeTab === 3}
+        label="Resources"
+        onClick={(e) => navigate(e, 3)}
+      />
+    </Tabs>
+  );
+});
+```
 
 ## Scrollable Tabs
 
 If you have more than a few tabs, you may need to make sure they will be all
 accessible no matter the space they have around. Wrap Tabs into
-[ScrollView](/components/scroll-view) to make them scrollable if necessary.
-
-<Playground>
-  {() => {
-    const [activeTab, setActiveTab] = React.useState(1);
-    const navigate = (event, tab) => {
-      setActiveTab(tab);
-      event.preventDefault();
-    };
-    return (
-      <div style={{ width: '19rem' }}>
-        <ScrollView direction="horizontal">
-          <Tabs>
-            <TabsItem
-              href="#design"
-              isActive={activeTab === 1}
-              label="Design"
-              onClick={(e) => navigate(e, 1)}
-            />
-            <TabsItem
-              href="#code"
-              isActive={activeTab === 2}
-              label="Code"
-              onClick={(e) => navigate(e, 2)}
-            />
-            <TabsItem
-              href="#resources"
-              isActive={activeTab === 3}
-              label="Resources"
-              onClick={(e) => navigate(e, 3)}
-            />
-            <TabsItem
-              href="#other"
-              isActive={activeTab === 4}
-              label="Other"
-              onClick={(e) => navigate(e, 4)}
-            />
-            <TabsItem
-              href="#more"
-              isActive={activeTab === 5}
-              label="More"
-              onClick={(e) => navigate(e, 5)}
-            />
-          </Tabs>
-        </ScrollView>
-      </div>
-    );
-  }}
-</Playground>
+[ScrollView](/components/ScrollView) to make them scrollable if necessary.
+
+```docoff-react-preview
+React.createElement(() => {
+  const [activeTab, setActiveTab] = React.useState(1);
+  const navigate = (event, tab) => {
+    setActiveTab(tab);
+    event.preventDefault();
+  };
+  return (
+    <div style={{ width: '19rem' }}>
+      <ScrollView direction="horizontal">
+        <Tabs>
+          <TabsItem
+            href="#design"
+            isActive={activeTab === 1}
+            label="Design"
+            onClick={(e) => navigate(e, 1)}
+          />
+          <TabsItem
+            href="#code"
+            isActive={activeTab === 2}
+            label="Code"
+            onClick={(e) => navigate(e, 2)}
+          />
+          <TabsItem
+            href="#resources"
+            isActive={activeTab === 3}
+            label="Resources"
+            onClick={(e) => navigate(e, 3)}
+          />
+          <TabsItem
+            href="#other"
+            isActive={activeTab === 4}
+            label="Other"
+            onClick={(e) => navigate(e, 4)}
+          />
+          <TabsItem
+            href="#more"
+            isActive={activeTab === 5}
+            label="More"
+            onClick={(e) => navigate(e, 5)}
+          />
+        </Tabs>
+      </ScrollView>
+    </div>
+  );
+})
+```
 
 ## Forwarding HTML Attributes
 
 In addition to the options below in the [component's API](#api) section, you
 can specify [React synthetic events] or **any HTML attribute you like.** All
 attributes that don't interfere with the API are forwarded to the `<nav>` HTML
-element in case of `Tabs` component and to the `<li>` HTML element in
+element in case of `Tabs` component and to the `<a>` HTML element in
 case of `TabsItem`. This enables making the component interactive and helps
 to improve its accessibility.
 
@@ -185,11 +168,11 @@ to improve its accessibility.
 
 ## API
 
-<Props table of={Tabs} />
+<docoff-react-props src="/components/Tabs/Tabs.jsx"></docoff-react-props>
 
 ### TabsItem
 
-<Props table of={TabsItem} />
+<docoff-react-props src="/components/Tabs/TabsItem.jsx"></docoff-react-props>
 
 ## Theming
 

package/src/{lib/components → components}/Tabs/TabsItem.jsx

@@ -16,7 +16,6 @@ export const TabsItem = ({
   ...restProps
 }) => (
   <li
-    {...transferProps(restProps)}
     className={classNames(
       styles.root,
       isActive && styles.isRootActive,
@@ -25,10 +24,11 @@ export const TabsItem = ({
     key={href}
   >
     <a
-      href={href}
-      onClick={onClick}
+      {...transferProps(restProps)}
       className={styles.link}
+      href={href}
       id={id && `${id}__link`}
+      onClick={onClick}
     >
       <span className={styles.linkContent}>
         {beforeLabel}