@trackunit/react-table 1.10.18 → 1.10.20

package/index.cjs.js

@@ -256,10 +256,107 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
 };
 
 /**
- * The Action Sheet appears when one or more items are selected from a table.
- * It primarily accommodates 1-3 main actions that represent the most crucial and frequently accessed functions on the specific page.
- * If the page supports more than 3 actions, the ones that are performed less often can be placed in a contextual menu, represented by the ‘three dots’ icon.
+ * The `<ActionSheet>` component appears as a floating bar when one or more items
+ * are selected from a table, providing bulk actions for the selection.
  *
+ * It primarily accommodates 1-3 main actions that represent the most crucial and
+ * frequently accessed functions on the specific page. If the page supports more
+ * than 3 actions, the ones that are performed less often can be placed in a
+ * contextual menu, represented by the 'three dots' icon via `moreActions`.
+ *
+ * ### When to use
+ * - Provide bulk operations when users select multiple table rows
+ * - For batch actions like delete, export, assign, or status changes
+ * - When actions need to operate on a collection of selected items
+ *
+ * ### When not to use
+ * - For single row actions - use `RowActions` instead
+ * - For page-level actions not tied to selection - use regular buttons
+ * - When the table doesn't support multi-selection
+ *
+ * @example Basic usage with table selection
+ * ```tsx
+ * import { Table, ActionSheet, useTableSelection } from "@trackunit/react-table";
+ *
+ * const MyTable = ({ data }) => {
+ *   const { selections, resetSelection, rowSelection, onRowSelectionChange } =
+ *     useTableSelection(data);
+ *
+ *   return (
+ *     <>
+ *       <Table
+ *         data={data}
+ *         columns={columns}
+ *         state={{ rowSelection }}
+ *         onRowSelectionChange={onRowSelectionChange}
+ *         enableRowSelection
+ *       />
+ *       {selections.length > 0 && (
+ *         <ActionSheet
+ *           selections={selections}
+ *           resetSelection={resetSelection}
+ *           actions={[
+ *             {
+ *               label: "Export",
+ *               iconName: "ArrowDownTray",
+ *               onClick: () => handleExport(selections),
+ *             },
+ *             {
+ *               label: "Delete",
+ *               iconName: "Trash",
+ *               variant: "danger",
+ *               onClick: () => handleDelete(selections),
+ *             },
+ *           ]}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * };
+ * ```
+ * @example With overflow actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={() => setSelectedIds([])}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *     { label: "Assign", iconName: "UserPlus", onClick: handleAssign },
+ *   ]}
+ *   moreActions={[
+ *     { label: "Archive", iconName: "ArchiveBox", onClick: handleArchive },
+ *     { label: "Move", iconName: "FolderArrowDown", onClick: handleMove },
+ *     { label: "Delete", iconName: "Trash", variant: "danger", onClick: handleDelete },
+ *   ]}
+ * />
+ * ```
+ * @example With dropdown actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ * import { MenuList, MenuItem } from "@trackunit/react-components";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={resetSelection}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *   ]}
+ *   dropdownActions={[
+ *     {
+ *       label: "Change Status",
+ *       iconName: "Flag",
+ *       dropdownContent: (close) => (
+ *         <MenuList>
+ *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
+ *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
+ *         </MenuList>
+ *       ),
+ *     },
+ *   ]}
+ * />
+ * ```
  * @param {ActionSheetProps} props - The props for the ActionSheet component
  * @returns {ReactElement} ActionSheet component
  */

package/index.esm.js

@@ -9,7 +9,7 @@ import { cvaLabel, ToggleSwitch, Search, RadioGroup, RadioItem, Checkbox } from
 import update from 'immutability-helper';
 import { useDrop, useDrag, DndProvider } from 'react-dnd';
 import { HTML5Backend } from 'react-dnd-html5-backend';
-import { flexRender, createColumnHelper, useReactTable, getSortedRowModel, getCoreRowModel } from '@tanstack/react-table';
+import { flexRender, createColumnHelper, useReactTable, getCoreRowModel, getSortedRowModel } from '@tanstack/react-table';
 export { createColumnHelper } from '@tanstack/react-table';
 import { TableRoot, Thead, Tr, Th, ResizeHandle, Tbody, Td } from '@trackunit/react-table-base-components';
 import { twMerge } from 'tailwind-merge';
@@ -255,10 +255,107 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
 };
 
 /**
- * The Action Sheet appears when one or more items are selected from a table.
- * It primarily accommodates 1-3 main actions that represent the most crucial and frequently accessed functions on the specific page.
- * If the page supports more than 3 actions, the ones that are performed less often can be placed in a contextual menu, represented by the ‘three dots’ icon.
+ * The `<ActionSheet>` component appears as a floating bar when one or more items
+ * are selected from a table, providing bulk actions for the selection.
  *
+ * It primarily accommodates 1-3 main actions that represent the most crucial and
+ * frequently accessed functions on the specific page. If the page supports more
+ * than 3 actions, the ones that are performed less often can be placed in a
+ * contextual menu, represented by the 'three dots' icon via `moreActions`.
+ *
+ * ### When to use
+ * - Provide bulk operations when users select multiple table rows
+ * - For batch actions like delete, export, assign, or status changes
+ * - When actions need to operate on a collection of selected items
+ *
+ * ### When not to use
+ * - For single row actions - use `RowActions` instead
+ * - For page-level actions not tied to selection - use regular buttons
+ * - When the table doesn't support multi-selection
+ *
+ * @example Basic usage with table selection
+ * ```tsx
+ * import { Table, ActionSheet, useTableSelection } from "@trackunit/react-table";
+ *
+ * const MyTable = ({ data }) => {
+ *   const { selections, resetSelection, rowSelection, onRowSelectionChange } =
+ *     useTableSelection(data);
+ *
+ *   return (
+ *     <>
+ *       <Table
+ *         data={data}
+ *         columns={columns}
+ *         state={{ rowSelection }}
+ *         onRowSelectionChange={onRowSelectionChange}
+ *         enableRowSelection
+ *       />
+ *       {selections.length > 0 && (
+ *         <ActionSheet
+ *           selections={selections}
+ *           resetSelection={resetSelection}
+ *           actions={[
+ *             {
+ *               label: "Export",
+ *               iconName: "ArrowDownTray",
+ *               onClick: () => handleExport(selections),
+ *             },
+ *             {
+ *               label: "Delete",
+ *               iconName: "Trash",
+ *               variant: "danger",
+ *               onClick: () => handleDelete(selections),
+ *             },
+ *           ]}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * };
+ * ```
+ * @example With overflow actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={() => setSelectedIds([])}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *     { label: "Assign", iconName: "UserPlus", onClick: handleAssign },
+ *   ]}
+ *   moreActions={[
+ *     { label: "Archive", iconName: "ArchiveBox", onClick: handleArchive },
+ *     { label: "Move", iconName: "FolderArrowDown", onClick: handleMove },
+ *     { label: "Delete", iconName: "Trash", variant: "danger", onClick: handleDelete },
+ *   ]}
+ * />
+ * ```
+ * @example With dropdown actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ * import { MenuList, MenuItem } from "@trackunit/react-components";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={resetSelection}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *   ]}
+ *   dropdownActions={[
+ *     {
+ *       label: "Change Status",
+ *       iconName: "Flag",
+ *       dropdownContent: (close) => (
+ *         <MenuList>
+ *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
+ *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
+ *         </MenuList>
+ *       ),
+ *     },
+ *   ]}
+ * />
+ * ```
  * @param {ActionSheetProps} props - The props for the ActionSheet component
  * @returns {ReactElement} ActionSheet component
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "1.10.18",
+  "version": "1.10.20",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,14 +14,14 @@
     "react-dnd-html5-backend": "16.0.1",
     "@tanstack/react-router": "1.114.29",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "1.14.18",
-    "@trackunit/shared-utils": "1.12.15",
-    "@trackunit/css-class-variance-utilities": "1.10.15",
-    "@trackunit/ui-icons": "1.10.15",
-    "@trackunit/react-table-base-components": "1.10.18",
-    "@trackunit/react-form-components": "1.11.18",
-    "@trackunit/i18n-library-translation": "1.10.15",
-    "@trackunit/iris-app-runtime-core-api": "1.10.15",
+    "@trackunit/react-components": "1.14.20",
+    "@trackunit/shared-utils": "1.12.16",
+    "@trackunit/css-class-variance-utilities": "1.10.16",
+    "@trackunit/ui-icons": "1.10.16",
+    "@trackunit/react-table-base-components": "1.10.20",
+    "@trackunit/react-form-components": "1.11.20",
+    "@trackunit/i18n-library-translation": "1.10.17",
+    "@trackunit/iris-app-runtime-core-api": "1.10.17",
     "graphql": "^16.10.0"
   },
   "module": "./index.esm.js",

package/src/ActionSheet/ActionSheet.d.ts

@@ -23,10 +23,107 @@ export interface ActionSheetProps extends CommonProps {
     resetSelection: () => void;
 }
 /**
- * The Action Sheet appears when one or more items are selected from a table.
- * It primarily accommodates 1-3 main actions that represent the most crucial and frequently accessed functions on the specific page.
- * If the page supports more than 3 actions, the ones that are performed less often can be placed in a contextual menu, represented by the ‘three dots’ icon.
+ * The `<ActionSheet>` component appears as a floating bar when one or more items
+ * are selected from a table, providing bulk actions for the selection.
  *
+ * It primarily accommodates 1-3 main actions that represent the most crucial and
+ * frequently accessed functions on the specific page. If the page supports more
+ * than 3 actions, the ones that are performed less often can be placed in a
+ * contextual menu, represented by the 'three dots' icon via `moreActions`.
+ *
+ * ### When to use
+ * - Provide bulk operations when users select multiple table rows
+ * - For batch actions like delete, export, assign, or status changes
+ * - When actions need to operate on a collection of selected items
+ *
+ * ### When not to use
+ * - For single row actions - use `RowActions` instead
+ * - For page-level actions not tied to selection - use regular buttons
+ * - When the table doesn't support multi-selection
+ *
+ * @example Basic usage with table selection
+ * ```tsx
+ * import { Table, ActionSheet, useTableSelection } from "@trackunit/react-table";
+ *
+ * const MyTable = ({ data }) => {
+ *   const { selections, resetSelection, rowSelection, onRowSelectionChange } =
+ *     useTableSelection(data);
+ *
+ *   return (
+ *     <>
+ *       <Table
+ *         data={data}
+ *         columns={columns}
+ *         state={{ rowSelection }}
+ *         onRowSelectionChange={onRowSelectionChange}
+ *         enableRowSelection
+ *       />
+ *       {selections.length > 0 && (
+ *         <ActionSheet
+ *           selections={selections}
+ *           resetSelection={resetSelection}
+ *           actions={[
+ *             {
+ *               label: "Export",
+ *               iconName: "ArrowDownTray",
+ *               onClick: () => handleExport(selections),
+ *             },
+ *             {
+ *               label: "Delete",
+ *               iconName: "Trash",
+ *               variant: "danger",
+ *               onClick: () => handleDelete(selections),
+ *             },
+ *           ]}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * };
+ * ```
+ * @example With overflow actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={() => setSelectedIds([])}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *     { label: "Assign", iconName: "UserPlus", onClick: handleAssign },
+ *   ]}
+ *   moreActions={[
+ *     { label: "Archive", iconName: "ArchiveBox", onClick: handleArchive },
+ *     { label: "Move", iconName: "FolderArrowDown", onClick: handleMove },
+ *     { label: "Delete", iconName: "Trash", variant: "danger", onClick: handleDelete },
+ *   ]}
+ * />
+ * ```
+ * @example With dropdown actions
+ * ```tsx
+ * import { ActionSheet } from "@trackunit/react-table";
+ * import { MenuList, MenuItem } from "@trackunit/react-components";
+ *
+ * <ActionSheet
+ *   selections={selectedIds}
+ *   resetSelection={resetSelection}
+ *   actions={[
+ *     { label: "Export", iconName: "ArrowDownTray", onClick: handleExport },
+ *   ]}
+ *   dropdownActions={[
+ *     {
+ *       label: "Change Status",
+ *       iconName: "Flag",
+ *       dropdownContent: (close) => (
+ *         <MenuList>
+ *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
+ *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
+ *         </MenuList>
+ *       ),
+ *     },
+ *   ]}
+ * />
+ * ```
  * @param {ActionSheetProps} props - The props for the ActionSheet component
  * @returns {ReactElement} ActionSheet component
  */

package/src/Table.d.ts

@@ -3,18 +3,71 @@ import { CommonProps, EmptyStateProps, RelayPagination } from "@trackunit/react-
 import { ReactElement, ReactNode } from "react";
 import "./table-animations.css";
 export interface TableProps<TData extends object> extends ReactTable<TData>, CommonProps {
+    /**
+     * Relay-style pagination object for infinite scroll. Use with `usePaginationQuery` hook
+     * to automatically handle fetching more data as the user scrolls.
+     */
     pagination?: RelayPagination;
+    /**
+     * ReactNode rendered on the left side of the table header area.
+     * Commonly used for column settings, search inputs or filter controls.
+     */
     headerLeftActions?: ReactNode;
+    /**
+     * ReactNode rendered on the right side of the table header area.
+     * Commonly used for primary actions for the table.
+     */
     headerRightActions?: ReactNode;
+    /**
+     * ReactNode rendered on the right side of the table footer.
+     * Commonly used for export actions.
+     */
     footerRightActions?: ReactNode;
+    /**
+     * Callback fired when a row is clicked. Receives the full Tanstack Row object
+     * which includes the original data via `row.original`.
+     */
     onRowClick?: (row: Row<TData>) => void;
+    /**
+     * Custom message or element shown when the table has no data.
+     * If not provided, a default empty state with search icon is displayed.
+     */
     noDataMessage?: ReactElement | string;
+    /**
+     * Shows a centered loading spinner when true. Use for initial data loading
+     * or when refreshing the entire table.
+     */
     loading?: boolean;
+    /**
+     * Height of each row in pixels. Used by the virtual scroll to estimate row sizes.
+     *
+     * @default 50
+     */
     rowHeight?: number;
+    /**
+     * Hides the footer that shows row count when true.
+     * Useful for compact tables or when count information isn't needed.
+     */
     hideFooter?: boolean;
+    /**
+     * Props passed to the EmptyState component shown when there's no data.
+     * Allows customizing the empty state image, title, and description.
+     */
     emptyState?: EmptyStateProps;
+    /**
+     * Column ID used to identify the selection checkbox column.
+     * When set, clicking on this column won't trigger `onRowClick`.
+     */
     selectionColId?: string;
+    /**
+     * Function to render custom filter buttons in column headers.
+     * Receives the filter key(s) from column meta and should return filter UI.
+     */
     renderFilterButton?: (filterKey: string | Array<string>) => ReactNode;
+    /**
+     * Function to determine if a specific row should be clickable.
+     * When provided, only rows returning true will have pointer cursor and trigger `onRowClick`.
+     */
     isRowClickable?: (row: TData) => boolean;
     onColumnDragStart?: (columnId: string) => void;
 }