@stack-spot/citric-react 0.38.0 → 0.39.0

package/src/components/SmartTable.tsx

@@ -1,227 +1,227 @@
-import { useMemo } from 'react'
-import { withRef } from '../utils/react'
-import { BaseTableProps, SortingDirection, Table, TableProps, Th, Tr } from './Table'
-
-export type TableColumn<T> = {
-  /**
-   * A unique identifier for the column.
-   */
-  key: string,
-  /**
-   * A label to use as the column's header.
-   * 
-   * If not provided, the key will be used.
-   */
-  label?: React.ReactNode,
-  /**
-   * A custom render function. It receives the item (row) and must return a React node.
-   * 
-   * If not provided, the value of `item[key]` will be converted to a string and used. If it's undefined, an empty string is rendered.
-   * 
-   * @param item the current item.
-   * @returns the React Node to render.
-   */
-  render?: (item: T) => React.ReactNode,
-  /**
-   * What to do when the header is clicked (sorting)
-   */
-  onSort?: (value: SortingDirection | undefined) => void,
-  /**
-   * Which is the current direction of the sorting? Only relevant if 'onSort' is set.
-   * 
-   * @default 'desc'
-   */
-  direction?: SortingDirection,
-  /**
-   * Additional properties for the "th" corresponding to this column.
-   */
-  th?: Omit<JSX.IntrinsicElements['th'], 'children'>,
-  /**
-   * Additional properties for the "td" corresponding to this column.
-   */
-  td?: Omit<JSX.IntrinsicElements['td'], 'children'>,
-}
-
-interface ExtraSmartTableProps<T extends Record<string, any>> {
-  /**
-   * An array where each item is a row in the table.
-   */
-  data: T[],
-  /**
-   * A function to generate a unique key for each item. If not provided, the item's index will be used.
-   * @param item
-   * @returns a unique key
-   */
-  keygen?: (item: T) => React.Key,
-  /**
-   * The columns to display in the table.
-   * 
-   * Attention: always save your columns with `useMemo` to avoid unnecessary rerenders.
-   */
-  columns: TableColumn<T>[],
-  /**
-   * If set, an extra row and column for each item is rendered. The extra row is collapsed by default and can be expanded through a button
-   * that is placed in the extra column.
-   * 
-   * The extra row is, effectively, an accordion. The content of this accordion is defined by whatever this function returns.
-   * 
-   * @param item the current item.
-   * @returns the React Node to render.
-   */
-  renderAccordion?: (item: T) => React.ReactNode,
-  /**
-   * What should make the accordions expand or contract? A click on a button in the last column or a click anywhere in the row?
-   * 
-   * Only valid if `renderAccordion` is set.
-   * 
-   * @default 'button'
-   */
-  accordionTrigger?: 'button' | 'row',
-  /**
-   * The maximum height for accordion rows.
-   * 
-   * @default '200px'
-   */
-  accordionMaxHeight?: string,
-  /**
-   * If true, no header is rendered for the table.
-   * 
-   * @default false
-   */
-  headless?: boolean,
-  /**
-   * Making a row clickable is not accessible, i.e. it creates an unfriendly UI for people who rely on assistive technologies.
-   * 
-   * Instead you should place the action in an element inside the row, e.g. an anchor or a button.
-   * 
-   * For users who don't rely on assistive technologies we may still want the click on the row to mimic the behavior of the element with
-   * the actual action. This property does exactly this!
-   * 
-   * The value of this property must be a CSS selector relative to this row, it must refer to the element with the click listener that
-   * should be triggered when this row is clicked.
-   * 
-   * When this property is set, the row cursor becomes a pointer.
-   * 
-   * @example
-   * 
-   * ```
-   * rowClickElement="a" // the first anchor element inside the row will be triggered when the row is clicked.
-   * ```
-   */
-  rowClickElement?: string,
-}
-
-export type BaseSmartTableProps<T extends Record<string, any>> = BaseTableProps & ExtraSmartTableProps<T>
-
-export type SmartTableProps<T extends Record<string, any>> = Omit<TableProps, 'children'> & ExtraSmartTableProps<T>
-
-function createRowClickListener(elementQuerySelector: string) {
-  return (event: React.MouseEvent) => {
-    const target = event.target instanceof HTMLElement ? event.target : undefined
-    const row = target instanceof HTMLTableRowElement ? target : target?.closest('tr')
-    if (row) {
-      const element = row.querySelector(elementQuerySelector)
-      if (element instanceof HTMLElement) element.click()
-    }
-  }
-}
-
-/**
- * Renders a table. Always prefer using this component over the raw Table component.
- * 
- * This receives a dataset and renders each item as a row. The columns are determined by the property "columns".
- * 
- * To change the overall table style, use the property "appearance".
- * 
- * To check more complex table examples, like tables with accordions and sorting, check the storybook.
- * 
- * @example
- * 
- * ```
- * const data = useMemo(() => [
- *   { id: 1, name: 'Yuri Tyson', phone: '1-801-475-4561', country: 'Poland', age: 21 },
- *   { id: 2, name: 'Amal Mcclure', phone: '(695) 948-4102', country: 'Ukraine', age: 32 },
- *   { id: 3, name: 'Levi Glass', phone: '1-976-544-4872', country: 'Colombia', age: 45 },
- * ], [])
- * const columns = useMemo(() => [
- *   { key: 'name', label: 'Name', render: item => `${item.name} (${item.age})` },
- *   { key: 'phone', label: 'Phone' },
- *   { key: 'country', label: 'Country' },
- *   {
- *      key: 'settings',
- *      render: item => (
- *        <Row gap={2}>
- *          <IconButton icon="ExternalLink" title="View" />
- *          <IconButton icon="Pencil" title="Edit" />
- *          <IconButton icon="Trash" title="Delete" colorScheme="danger" />
- *        </Row>
- *      ),
- *   },
- * ], [])
- * return <SmartTable data={data} columns={columns} />
- * ```
- */
-export const SmartTable = withRef(
-  function SmartTable<T extends Record<string, any>>({
-    data, keygen, columns, renderAccordion, accordionTrigger, accordionMaxHeight, id, rowClickElement, headless, ...props
-  }: SmartTableProps<T>) {
-    id = useMemo(() => id || `${Math.random()}`, [id])
-
-    const headers = useMemo(
-      () => headless ? [] : columns.map((c) => (
-        <Th {...c.th} key={c.key} onSort={c.onSort} direction={c.direction} tabIndex={c.onSort ? 0 : undefined}>
-          {c.label ?? c.key}
-        </Th>
-      )),
-      [columns, headless],
-    )
-
-    const rows = useMemo(
-      () => data.map((item, index) => {
-        const key = keygen ? keygen(item) : index
-        const accordionContent = renderAccordion?.(item)
-        const row = (
-          <Tr
-            key={key}
-            accordionTrigger={accordionContent ? accordionTrigger : undefined}
-            onClick={rowClickElement ? createRowClickListener(rowClickElement) : undefined}
-          >
-            {columns.map(c => <td {...c.td} key={c.key}>{c.render ? c.render(item) : (item[c.key] || '')}</td>)}
-            {renderAccordion && (
-              <td>
-                {accordionContent && (
-                  <input
-                    type="checkbox"
-                    aria-controls={`${id}-${key}`}
-                    onKeyDown={e => e.key === 'Enter' && e.target instanceof HTMLElement && e.target.click()}
-                  />
-                )}
-              </td>
-            )}
-          </Tr>
-        )
-        return renderAccordion ? (
-          <tbody key={`${key}-group`}>
-            {row}
-            <Tr id={`${id}-${key}`} accordion accordionMaxHeight={accordionMaxHeight}>
-              <td colSpan={columns.length + 1}><div>{accordionContent}</div></td>
-            </Tr>
-          </tbody>
-        ) : row
-      }),
-      [columns, data, !!renderAccordion, accordionTrigger],
-    )
-
-    return (
-      <Table id={id} accordionRows={!!renderAccordion} {...props}>
-        {!headless && <thead>
-          <tr>
-            {headers}
-            {renderAccordion && <th></th>}
-          </tr>
-        </thead>}
-        {renderAccordion ? rows : <tbody>{rows}</tbody>}
-      </Table>
-    )
-  },
-)
+import { useMemo } from 'react'
+import { withRef } from '../utils/react'
+import { BaseTableProps, SortingDirection, Table, TableProps, Th, Tr } from './Table'
+
+export type TableColumn<T> = {
+  /**
+   * A unique identifier for the column.
+   */
+  key: string,
+  /**
+   * A label to use as the column's header.
+   * 
+   * If not provided, the key will be used.
+   */
+  label?: React.ReactNode,
+  /**
+   * A custom render function. It receives the item (row) and must return a React node.
+   * 
+   * If not provided, the value of `item[key]` will be converted to a string and used. If it's undefined, an empty string is rendered.
+   * 
+   * @param item the current item.
+   * @returns the React Node to render.
+   */
+  render?: (item: T) => React.ReactNode,
+  /**
+   * What to do when the header is clicked (sorting)
+   */
+  onSort?: (value: SortingDirection | undefined) => void,
+  /**
+   * Which is the current direction of the sorting? Only relevant if 'onSort' is set.
+   * 
+   * @default 'desc'
+   */
+  direction?: SortingDirection,
+  /**
+   * Additional properties for the "th" corresponding to this column.
+   */
+  th?: Omit<JSX.IntrinsicElements['th'], 'children'>,
+  /**
+   * Additional properties for the "td" corresponding to this column.
+   */
+  td?: Omit<JSX.IntrinsicElements['td'], 'children'>,
+}
+
+interface ExtraSmartTableProps<T extends Record<string, any>> {
+  /**
+   * An array where each item is a row in the table.
+   */
+  data: T[],
+  /**
+   * A function to generate a unique key for each item. If not provided, the item's index will be used.
+   * @param item
+   * @returns a unique key
+   */
+  keygen?: (item: T) => React.Key,
+  /**
+   * The columns to display in the table.
+   * 
+   * Attention: always save your columns with `useMemo` to avoid unnecessary rerenders.
+   */
+  columns: TableColumn<T>[],
+  /**
+   * If set, an extra row and column for each item is rendered. The extra row is collapsed by default and can be expanded through a button
+   * that is placed in the extra column.
+   * 
+   * The extra row is, effectively, an accordion. The content of this accordion is defined by whatever this function returns.
+   * 
+   * @param item the current item.
+   * @returns the React Node to render.
+   */
+  renderAccordion?: (item: T) => React.ReactNode,
+  /**
+   * What should make the accordions expand or contract? A click on a button in the last column or a click anywhere in the row?
+   * 
+   * Only valid if `renderAccordion` is set.
+   * 
+   * @default 'button'
+   */
+  accordionTrigger?: 'button' | 'row',
+  /**
+   * The maximum height for accordion rows.
+   * 
+   * @default '200px'
+   */
+  accordionMaxHeight?: string,
+  /**
+   * If true, no header is rendered for the table.
+   * 
+   * @default false
+   */
+  headless?: boolean,
+  /**
+   * Making a row clickable is not accessible, i.e. it creates an unfriendly UI for people who rely on assistive technologies.
+   * 
+   * Instead you should place the action in an element inside the row, e.g. an anchor or a button.
+   * 
+   * For users who don't rely on assistive technologies we may still want the click on the row to mimic the behavior of the element with
+   * the actual action. This property does exactly this!
+   * 
+   * The value of this property must be a CSS selector relative to this row, it must refer to the element with the click listener that
+   * should be triggered when this row is clicked.
+   * 
+   * When this property is set, the row cursor becomes a pointer.
+   * 
+   * @example
+   * 
+   * ```
+   * rowClickElement="a" // the first anchor element inside the row will be triggered when the row is clicked.
+   * ```
+   */
+  rowClickElement?: string,
+}
+
+export type BaseSmartTableProps<T extends Record<string, any>> = BaseTableProps & ExtraSmartTableProps<T>
+
+export type SmartTableProps<T extends Record<string, any>> = Omit<TableProps, 'children'> & ExtraSmartTableProps<T>
+
+function createRowClickListener(elementQuerySelector: string) {
+  return (event: React.MouseEvent) => {
+    const target = event.target instanceof HTMLElement ? event.target : undefined
+    const row = target instanceof HTMLTableRowElement ? target : target?.closest('tr')
+    if (row) {
+      const element = row.querySelector(elementQuerySelector)
+      if (element instanceof HTMLElement) element.click()
+    }
+  }
+}
+
+/**
+ * Renders a table. Always prefer using this component over the raw Table component.
+ * 
+ * This receives a dataset and renders each item as a row. The columns are determined by the property "columns".
+ * 
+ * To change the overall table style, use the property "appearance".
+ * 
+ * To check more complex table examples, like tables with accordions and sorting, check the storybook.
+ * 
+ * @example
+ * 
+ * ```
+ * const data = useMemo(() => [
+ *   { id: 1, name: 'Yuri Tyson', phone: '1-801-475-4561', country: 'Poland', age: 21 },
+ *   { id: 2, name: 'Amal Mcclure', phone: '(695) 948-4102', country: 'Ukraine', age: 32 },
+ *   { id: 3, name: 'Levi Glass', phone: '1-976-544-4872', country: 'Colombia', age: 45 },
+ * ], [])
+ * const columns = useMemo(() => [
+ *   { key: 'name', label: 'Name', render: item => `${item.name} (${item.age})` },
+ *   { key: 'phone', label: 'Phone' },
+ *   { key: 'country', label: 'Country' },
+ *   {
+ *      key: 'settings',
+ *      render: item => (
+ *        <Row gap={2}>
+ *          <IconButton icon="ExternalLink" title="View" />
+ *          <IconButton icon="Pencil" title="Edit" />
+ *          <IconButton icon="Trash" title="Delete" colorScheme="danger" />
+ *        </Row>
+ *      ),
+ *   },
+ * ], [])
+ * return <SmartTable data={data} columns={columns} />
+ * ```
+ */
+export const SmartTable = withRef(
+  function SmartTable<T extends Record<string, any>>({
+    data, keygen, columns, renderAccordion, accordionTrigger, accordionMaxHeight, id, rowClickElement, headless, ...props
+  }: SmartTableProps<T>) {
+    id = useMemo(() => id || `${Math.random()}`, [id])
+
+    const headers = useMemo(
+      () => headless ? [] : columns.map((c) => (
+        <Th {...c.th} key={c.key} onSort={c.onSort} direction={c.direction} tabIndex={c.onSort ? 0 : undefined}>
+          {c.label ?? c.key}
+        </Th>
+      )),
+      [columns, headless],
+    )
+
+    const rows = useMemo(
+      () => data.map((item, index) => {
+        const key = keygen ? keygen(item) : index
+        const accordionContent = renderAccordion?.(item)
+        const row = (
+          <Tr
+            key={key}
+            accordionTrigger={accordionContent ? accordionTrigger : undefined}
+            onClick={rowClickElement ? createRowClickListener(rowClickElement) : undefined}
+          >
+            {columns.map(c => <td {...c.td} key={c.key}>{c.render ? c.render(item) : (item[c.key] || '')}</td>)}
+            {renderAccordion && (
+              <td>
+                {accordionContent && (
+                  <input
+                    type="checkbox"
+                    aria-controls={`${id}-${key}`}
+                    onKeyDown={e => e.key === 'Enter' && e.target instanceof HTMLElement && e.target.click()}
+                  />
+                )}
+              </td>
+            )}
+          </Tr>
+        )
+        return renderAccordion ? (
+          <tbody key={`${key}-group`}>
+            {row}
+            <Tr id={`${id}-${key}`} accordion accordionMaxHeight={accordionMaxHeight}>
+              <td colSpan={columns.length + 1}><div>{accordionContent}</div></td>
+            </Tr>
+          </tbody>
+        ) : row
+      }),
+      [columns, data, !!renderAccordion, accordionTrigger],
+    )
+
+    return (
+      <Table id={id} accordionRows={!!renderAccordion} {...props}>
+        {!headless && <thead>
+          <tr>
+            {headers}
+            {renderAccordion && <th></th>}
+          </tr>
+        </thead>}
+        {renderAccordion ? rows : <tbody>{rows}</tbody>}
+      </Table>
+    )
+  },
+)