@commercetools-uikit/data-table 19.9.0 → 19.10.0

package/README.md

@@ -78,6 +78,9 @@ export default Example;
 | `sortedBy`                | `string`                                                         |          |                                    | The key of the column for which the data is currently sorted by.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `onSortChange`            | `Function`<br/>[See signature.](#signature-onSortChange)         |          |                                    | A callback function, called when a sortable column's header is clicked.&#xA;It's required when the `isSortable` flag is set on at least one column.                                                                                                                                                                                                                                                                                                                                                                                               |
 | `sortDirection`           | `union`<br/>Possible values:<br/>`'desc' , 'asc'`                |          |                                    | The sorting direction.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `customSettingsPayload`   | `Record<string, unknown>`                                        |          |                                    | Manage custom settings for the table                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `customColumns`           | `Array: TColumn<Row>[]`                                          |          |                                    | The columns of the nested items to be rendered in the table. Just like the columns, Each object requires a unique `key` which should correspond to property key of the items of `rows` that you want to render under this column, and a `label` which defines the name shown on the header. The list of columns to be rendered.                                                                                                                                                                                                                   |
+| `customRows`              | `Array: Row[]`                                                   |          |                                    | The list of data that needs to be rendered in the nested component. Each object in the list can have any shape as long as it has a unique identifier.                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ## Signatures
 

package/dist/commercetools-uikit-data-table.cjs.dev.js

@@ -648,7 +648,8 @@ DataRow.propTypes = process.env.NODE_ENV !== "production" ? {
   rowIndex: _pt__default["default"].number.isRequired,
   columns: _pt__default["default"].arrayOf(_pt__default["default"].any).isRequired,
   shouldClipContent: _pt__default["default"].bool.isRequired,
-  shouldRenderBottomBorder: _pt__default["default"].bool.isRequired
+  shouldRenderBottomBorder: _pt__default["default"].bool.isRequired,
+  onExpandRow: _pt__default["default"].func
 } : {};
 DataRow.defaultProps = defaultProps$1;
 DataRow.displayName = 'DataRow';
@@ -838,6 +839,16 @@ const DataTable = props => {
   const isValueFromProvider = Boolean(columns && columns.length !== 0);
   const columnsData = isValueFromProvider ? columns : props.columns;
   const condensedValue = isValueFromProvider && isCondensed !== undefined ? isCondensed : props.isCondensed;
+
+  //  TODO - initial poc for the nested rows
+  // const [openedItemIds, setOpenedItemIds] = useState<string[]>([]);
+  // const handleExpandRow = (row: Row) => {
+  //   const newOpenedItemIds = openedItemIds.includes(row.id)
+  //     ? openedItemIds.filter((id) => id !== row.id)
+  //     : [...openedItemIds, row.id];
+  //   setOpenedItemIds(newOpenedItemIds);
+  // };
+
   process.env.NODE_ENV !== "production" ? utils.warning(columnsData.length > 0, "ui-kit/DataTable: empty table \"columns\", expected at least one column. If you are using DataTableManager you need to pass the \"columns\" there and they will be injected into DataTable.") : void 0;
   const tableRef = react$1.useRef();
   const columnResizingReducer = useManualColumnResizing$1(tableRef);
@@ -935,6 +946,19 @@ DataTable.propTypes = process.env.NODE_ENV !== "production" ? {
     disableResizing: _pt__default["default"].bool,
     shouldIgnoreRowClick: _pt__default["default"].bool
   })).isRequired,
+  customColumns: _pt__default["default"].arrayOf(_pt__default["default"].shape({
+    key: _pt__default["default"].string.isRequired,
+    label: _pt__default["default"].node.isRequired,
+    width: _pt__default["default"].string,
+    align: _pt__default["default"].oneOf(['left', 'center', 'right']),
+    onClick: _pt__default["default"].func,
+    renderItem: _pt__default["default"].func,
+    headerIcon: _pt__default["default"].node,
+    isTruncated: _pt__default["default"].bool,
+    isSortable: _pt__default["default"].bool,
+    disableResizing: _pt__default["default"].bool,
+    shouldIgnoreRowClick: _pt__default["default"].bool
+  })),
   footer: _pt__default["default"].node,
   maxWidth: _pt__default["default"].oneOfType([_pt__default["default"].number, _pt__default["default"].string]),
   maxHeight: _pt__default["default"].oneOfType([_pt__default["default"].number, _pt__default["default"].string]),
@@ -949,14 +973,16 @@ DataTable.propTypes = process.env.NODE_ENV !== "production" ? {
   horizontalCellAlignment: _pt__default["default"].oneOf(['left', 'center', 'right']),
   sortedBy: _pt__default["default"].string,
   onSortChange: _pt__default["default"].func,
-  sortDirection: _pt__default["default"].oneOf(['desc', 'asc'])
+  sortDirection: _pt__default["default"].oneOf(['desc', 'asc']),
+  renderNestedRow: _pt__default["default"].func,
+  maxExpandableHeight: _pt__default["default"].number
 } : {};
 DataTable.defaultProps = defaultProps;
 DataTable.displayName = 'DataTable';
 var DataTable$1 = DataTable;
 
 // NOTE: This string will be replaced on build time with the package version.
-var version = "19.9.0";
+var version = "19.10.0";
 
 Object.defineProperty(exports, 'useRowSelection', {
   enumerable: true,

package/dist/commercetools-uikit-data-table.cjs.prod.js

@@ -759,7 +759,7 @@ DataTable.displayName = 'DataTable';
 var DataTable$1 = DataTable;
 
 // NOTE: This string will be replaced on build time with the package version.
-var version = "19.9.0";
+var version = "19.10.0";
 
 Object.defineProperty(exports, 'useRowSelection', {
   enumerable: true,

package/dist/commercetools-uikit-data-table.esm.js

@@ -624,7 +624,8 @@ DataRow.propTypes = process.env.NODE_ENV !== "production" ? {
   rowIndex: _pt.number.isRequired,
   columns: _pt.arrayOf(_pt.any).isRequired,
   shouldClipContent: _pt.bool.isRequired,
-  shouldRenderBottomBorder: _pt.bool.isRequired
+  shouldRenderBottomBorder: _pt.bool.isRequired,
+  onExpandRow: _pt.func
 } : {};
 DataRow.defaultProps = defaultProps$1;
 DataRow.displayName = 'DataRow';
@@ -814,6 +815,16 @@ const DataTable = props => {
   const isValueFromProvider = Boolean(columns && columns.length !== 0);
   const columnsData = isValueFromProvider ? columns : props.columns;
   const condensedValue = isValueFromProvider && isCondensed !== undefined ? isCondensed : props.isCondensed;
+
+  //  TODO - initial poc for the nested rows
+  // const [openedItemIds, setOpenedItemIds] = useState<string[]>([]);
+  // const handleExpandRow = (row: Row) => {
+  //   const newOpenedItemIds = openedItemIds.includes(row.id)
+  //     ? openedItemIds.filter((id) => id !== row.id)
+  //     : [...openedItemIds, row.id];
+  //   setOpenedItemIds(newOpenedItemIds);
+  // };
+
   process.env.NODE_ENV !== "production" ? warning(columnsData.length > 0, "ui-kit/DataTable: empty table \"columns\", expected at least one column. If you are using DataTableManager you need to pass the \"columns\" there and they will be injected into DataTable.") : void 0;
   const tableRef = useRef();
   const columnResizingReducer = useManualColumnResizing$1(tableRef);
@@ -911,6 +922,19 @@ DataTable.propTypes = process.env.NODE_ENV !== "production" ? {
     disableResizing: _pt.bool,
     shouldIgnoreRowClick: _pt.bool
   })).isRequired,
+  customColumns: _pt.arrayOf(_pt.shape({
+    key: _pt.string.isRequired,
+    label: _pt.node.isRequired,
+    width: _pt.string,
+    align: _pt.oneOf(['left', 'center', 'right']),
+    onClick: _pt.func,
+    renderItem: _pt.func,
+    headerIcon: _pt.node,
+    isTruncated: _pt.bool,
+    isSortable: _pt.bool,
+    disableResizing: _pt.bool,
+    shouldIgnoreRowClick: _pt.bool
+  })),
   footer: _pt.node,
   maxWidth: _pt.oneOfType([_pt.number, _pt.string]),
   maxHeight: _pt.oneOfType([_pt.number, _pt.string]),
@@ -925,13 +949,15 @@ DataTable.propTypes = process.env.NODE_ENV !== "production" ? {
   horizontalCellAlignment: _pt.oneOf(['left', 'center', 'right']),
   sortedBy: _pt.string,
   onSortChange: _pt.func,
-  sortDirection: _pt.oneOf(['desc', 'asc'])
+  sortDirection: _pt.oneOf(['desc', 'asc']),
+  renderNestedRow: _pt.func,
+  maxExpandableHeight: _pt.number
 } : {};
 DataTable.defaultProps = defaultProps;
 DataTable.displayName = 'DataTable';
 var DataTable$1 = DataTable;
 
 // NOTE: This string will be replaced on build time with the package version.
-var version = "19.9.0";
+var version = "19.10.0";
 
 export { DataTable$1 as default, version };

package/dist/declarations/src/data-table.d.ts

@@ -3,36 +3,186 @@ export interface TRow {
     id: string;
 }
 export type TColumn<Row extends TRow = TRow> = {
+    /**
+     * The unique key of the column that is used to identify your data type.
+     * You can use this value to determine which value from a row item should be rendered.
+     * <br>
+     * For example, if the data is a list of users, where each user has a `firstName` property,
+     * the column key should be `firstName`, which renders the correct value by default.
+     * The key can also be some custom or computed value, in which case you need to provide
+     * an explicit mapping of the value by implementing either the `itemRendered` function or
+     * the column-specific `renderItem` function.
+     */
     key: string;
+    /**
+     * The label of the column that will be shown on the column header.
+     */
     label: ReactNode;
+    /**
+     * Sets a width for this column. Accepts the same values as the ones specified for
+     * individual [grid-template-columns](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns).
+     * <br>
+     * For example, using `minmax` pairs (e.g. `minmax(200px, 400px)`), a combinations of
+     * fraction values (`1fr`/`2fr`/etc), or fixed values such as `200px`.
+     * By default, the column grows according to the content and respecting the total table available width.
+     */
     width?: string;
+    /**
+     * Use this to override the table's own `horizontalCellAlignment` prop for this specific column.
+     */
     align?: 'left' | 'center' | 'right';
+    /**
+     * A callback function, called when the header cell is clicked.
+     */
     onClick?: (event: MouseEventHandler) => void;
+    /**
+     * A callback function to render the content of cells under this column, overriding
+     * the default `itemRenderer` prop of the table.
+     */
     renderItem?: (row: Row, isRowCollapsed: boolean) => ReactNode;
+    /**
+     * Use this prop to place an `Icon` or `IconButton` on the left of the column label.
+     * It is advised to place these types of components through this prop instead of `label`,
+     * in order to properly position and align the elements.
+     * This is particularly useful for medium-sized icons which require more vertical space than the typography.
+     */
     headerIcon?: ReactNode;
+    /**
+     * Set this to `true` to allow text content of this cell to be truncated with an ellipsis,
+     * instead of breaking into multiple lines.
+     * <br>
+     * NOTE: when using this option, it is recommended to specify a `width` for the column, because
+     * if the table doesn't have enough space for all columns, it will start clipping the columns
+     * with _truncated_ content, and if no `width` is set (or the value is set `auto` -- the default)
+     * it can shrink until the column disappears completely.
+     * By enforcing a minimum width for these columns, the table will respect them and grow horizontally,
+     * adding scrollbars if needed.
+     */
     isTruncated?: boolean;
+    /**
+     * Set this to `true` to show a sorting button, which calls `onSortChange` upon being clicked.
+     * You should enable this flag for every column you want to be able to sort.
+     * When at least one column is sortable, the table props `sortBy`, `sortDirection` and `onSortChange` should be provided.
+     */
     isSortable?: boolean;
+    /**
+     * Set this to `true` to prevent this column from being manually resized by dragging
+     * the edge of the header with a mouse.
+     */
     disableResizing?: boolean;
+    /**
+     * Set this to `true` to prevent click event propagation for this cell.
+     * You might want this if you need the column to have its own call-to-action or input while
+     * the row also has a defined `onRowClick`.
+     */
     shouldIgnoreRowClick?: boolean;
 };
 export type TDataTableProps<Row extends TRow = TRow> = {
+    /**
+     * The list of data that needs to be rendered in the table. Each object in the list can
+     * have any shape as long as it has a unique identifier.
+     * The data is rendered by using the callback render function `itemRenderer`.
+     */
     rows: Row[];
+    /**
+     * Each object requires a unique `key` which should correspond to property key of
+     * the items of `rows` that you want to render under this column, and a `label`
+     * which defines the name shown on the header.
+     * The list of columns to be rendered.
+     * Each column can be customized (see properties below).
+     */
     columns: TColumn<Row>[];
+    /**
+     * The columns of the nested items to be rendered in the table. Just like the columns, Each object requires a unique `key` which should correspond to property key of
+     * the items of `rows` that you want to render under this column, and a `label`
+     * which defines the name shown on the header.
+     * The list of columns to be rendered.
+     */
+    customColumns?: TColumn<Row>[];
+    /**
+     * Element to render within the `tfoot` (footer) element of the table.
+     */
     footer?: ReactNode;
+    /**
+     * The max width (a number of pixels or a css value string with units) for which the table
+     * is allowed to grow. If unset, the table will grow horizontally to fill its parent.
+     */
     maxWidth?: number | string;
+    /**
+     * The max height (a number of pixels or a css value string with units) for which the table
+     * is allowed to grow. If unset, the table will grow vertically to fill its parent and we are able to have a sticky header.
+     */
     maxHeight?: number | string;
+    /**
+     * A callback function, called when a user clicks on a row.
+     */
     onRowClick?: (row: Row, rowIndex: number, columnKey: string) => void;
+    /**
+     * Set this to `true` to reduce the paddings of all cells, allowing the table to display
+     * more data in less space.
+     */
     isCondensed?: boolean;
+    /**
+     * A callback function, called when a column has been resized.
+     * Use this callback to get the resized column widths and save them, to be able to restore the
+     * value once the user comes back to the page.
+     */
     onColumnResized?: (args: TColumn<Row>[]) => void;
+    /**
+     * Set this to `true` to take control of the containment of the table and doing it on a parent element.
+     * This means that the table will grow in size without adding scrollbars on itself,
+     * both vertically and horizontally and, as a consequence, the `maxHeight` and `maxWidth` props are ignored.
+     * If you need to enforce these constraints, you must also apply them on the parent element.
+     * Additionally, the sticky behaviour of the header will get fixed relatively to the closest
+     * parent element with `position: relative`.
+     */
     disableSelfContainment?: boolean;
+    /**
+     * Set this to `true` to prevent the header from being sticky.
+     * The header can be sticky only if the table does not have a `maxHeight` set.
+     */
     disableHeaderStickiness?: boolean;
+    /**
+     * The default function used to render the content of each item in a cell.
+     * In case a column has its own `renderItem` render function, it will take precedence over this function.
+     */
     itemRenderer: (item: Row, column: TColumn<Row>, isRowCollapsed: boolean) => ReactNode;
+    /**
+     * Set this to `false` to ensure that every column can render their label in one line.
+     * By default the header cell grows in height in case the label does not fit in one line.
+     */
     wrapHeaderLabels?: boolean;
+    /**
+     * The default cell vertical alignment of each row (not the table header).
+     */
     verticalCellAlignment?: 'top' | 'center' | 'bottom';
+    /**
+     * The default cell horizontal alignment.
+     * In case a column has its own `align` property, it will take precedence over this value.
+     */
     horizontalCellAlignment?: 'left' | 'center' | 'right';
+    /**
+     * The key of the column for which the data is currently sorted by.
+     */
     sortedBy?: string;
+    /**
+     * A callback function, called when a sortable column's header is clicked.
+     * It's required when the `isSortable` flag is set on at least one column.
+     */
     onSortChange?: (columnKey: string, sortDirection: 'asc' | 'desc') => void;
+    /**
+     * The sorting direction.
+     */
     sortDirection?: 'desc' | 'asc';
+    /**
+     * Custom row renderer for nested rows.
+     */
+    renderNestedRow?: (row: Row) => ReactNode;
+    /**
+     * If this is provided, then it should control the height of the expanded rows. In the event where there is more content than the maxHeight,
+     *  a scrollbar should make provision for the overflow.
+     */
+    maxExpandableHeight?: number;
 };
 declare const DataTable: {
     <Row extends TRow = TRow>(props: TDataTableProps<Row>): import("@emotion/react/jsx-runtime").JSX.Element;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@commercetools-uikit/data-table",
   "description": "A component for rendering tabular data.",
-  "version": "19.9.0",
+  "version": "19.10.0",
   "bugs": "https://github.com/commercetools/ui-kit/issues",
   "repository": {
     "type": "git",
@@ -21,13 +21,13 @@
   "dependencies": {
     "@babel/runtime": "^7.20.13",
     "@babel/runtime-corejs3": "^7.20.13",
-    "@commercetools-uikit/accessible-button": "19.9.0",
-    "@commercetools-uikit/data-table-manager": "19.9.0",
-    "@commercetools-uikit/design-system": "19.9.0",
-    "@commercetools-uikit/hooks": "19.9.0",
-    "@commercetools-uikit/icons": "19.9.0",
-    "@commercetools-uikit/secondary-icon-button": "19.9.0",
-    "@commercetools-uikit/utils": "19.9.0",
+    "@commercetools-uikit/accessible-button": "19.10.0",
+    "@commercetools-uikit/data-table-manager": "19.10.0",
+    "@commercetools-uikit/design-system": "19.10.0",
+    "@commercetools-uikit/hooks": "19.10.0",
+    "@commercetools-uikit/icons": "19.10.0",
+    "@commercetools-uikit/secondary-icon-button": "19.10.0",
+    "@commercetools-uikit/utils": "19.10.0",
     "@emotion/react": "^11.10.5",
     "@emotion/styled": "^11.10.5",
     "lodash": "4.17.21",