@trackunit/react-table 1.13.25 → 1.13.27

package/index.cjs.js

@@ -959,13 +959,21 @@ const ColumnSorting = ({ canSort, sortingState = false }) => {
 };
 
 /**
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
+ * Table displays large data sets with virtual scrolling, column sorting, filtering, resizing, drag-and-drop column reordering,
+ * and row selection. It extends `@tanstack/react-table` and uses `useTable` to create the table instance.
+ * Infinite scroll pagination is handled via `RelayPagination` from `usePaginationQuery`.
  *
- * @param {ReactTable} props - The props for the Table component
+ * For the full TanStack Table API, see [TanStack Table docs](https://tanstack.com/table/v8/docs/guide/introduction).
+ *
+ * ### When to use
+ * Use Table for displaying structured data with sorting, pagination, or row actions — for example, asset lists, event logs, or user management views.
+ *
+ * ### When not to use
+ * Do not use Table for simple key-value displays — use a layout with `Text` components.
+ * Do not use Table for small card-based lists — use `List`.
+ *
+ * @param {TableProps} props - The props for the Table component
  * @returns {ReactElement} Table component
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
- * Table is extending the `@tanstack/react-table` Table component.
- * For more information about the `@tanstack/react-table` Table component, visit [https://tanstack.com/table/v8/docs/guide/introduction](https://tanstack.com/table/v8/docs/guide/introduction).
  * @example
  * ```tsx
  * import { createColumnHelper, Table, useTable } from "@trackunit/react-table";
@@ -1434,14 +1442,18 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
 };
 
 /**
- * `useTableSelection` is a custom hook that provides functionality for row selection in a table.
- * It returns an object containing methods and values related to row selection.
+ * `useTableSelection` provides row selection state management for the Table component.
+ * It returns a selection checkbox column definition, row selection state, and props to spread onto `useTable`.
+ *
+ * ### When to use
+ * Use useTableSelection when your Table needs checkbox-based row selection — for example, bulk actions on selected assets.
+ *
+ * ### When not to use
+ * Do not use useTableSelection if your table does not need row selection. For single-row actions, use `onRowClick` on the Table instead.
  *
- * @template TData - The type of data in the table. It must extend `selectableTableData`, which means it should at least have an `id` field.
- * @returns {TableSelectionReturn<TData>} An object containing:
- * - `selectionColumn`: A `ColumnDef` object for the selection column, which includes a checkbox in each cell and header.
- * - `rowSelection`: The current state of row selection.
- * - `setRowSelection`: A function to update the row selection state.
+ * @template TData - The type of data in the table. It must extend `SelectableTableData`.
+ * @param {TableSelectionProps} props - Configuration for selection behavior including data, idKey, and defaults
+ * @returns {TableSelectionReturn<TData>} Selection column, state, setters, and props to spread onto useTable
  * @example
  * const {
  *   selectionColumn,

package/index.esm.js

@@ -958,13 +958,21 @@ const ColumnSorting = ({ canSort, sortingState = false }) => {
 };
 
 /**
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
+ * Table displays large data sets with virtual scrolling, column sorting, filtering, resizing, drag-and-drop column reordering,
+ * and row selection. It extends `@tanstack/react-table` and uses `useTable` to create the table instance.
+ * Infinite scroll pagination is handled via `RelayPagination` from `usePaginationQuery`.
  *
- * @param {ReactTable} props - The props for the Table component
+ * For the full TanStack Table API, see [TanStack Table docs](https://tanstack.com/table/v8/docs/guide/introduction).
+ *
+ * ### When to use
+ * Use Table for displaying structured data with sorting, pagination, or row actions — for example, asset lists, event logs, or user management views.
+ *
+ * ### When not to use
+ * Do not use Table for simple key-value displays — use a layout with `Text` components.
+ * Do not use Table for small card-based lists — use `List`.
+ *
+ * @param {TableProps} props - The props for the Table component
  * @returns {ReactElement} Table component
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
- * Table is extending the `@tanstack/react-table` Table component.
- * For more information about the `@tanstack/react-table` Table component, visit [https://tanstack.com/table/v8/docs/guide/introduction](https://tanstack.com/table/v8/docs/guide/introduction).
  * @example
  * ```tsx
  * import { createColumnHelper, Table, useTable } from "@trackunit/react-table";
@@ -1433,14 +1441,18 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
 };
 
 /**
- * `useTableSelection` is a custom hook that provides functionality for row selection in a table.
- * It returns an object containing methods and values related to row selection.
+ * `useTableSelection` provides row selection state management for the Table component.
+ * It returns a selection checkbox column definition, row selection state, and props to spread onto `useTable`.
+ *
+ * ### When to use
+ * Use useTableSelection when your Table needs checkbox-based row selection — for example, bulk actions on selected assets.
+ *
+ * ### When not to use
+ * Do not use useTableSelection if your table does not need row selection. For single-row actions, use `onRowClick` on the Table instead.
  *
- * @template TData - The type of data in the table. It must extend `selectableTableData`, which means it should at least have an `id` field.
- * @returns {TableSelectionReturn<TData>} An object containing:
- * - `selectionColumn`: A `ColumnDef` object for the selection column, which includes a checkbox in each cell and header.
- * - `rowSelection`: The current state of row selection.
- * - `setRowSelection`: A function to update the row selection state.
+ * @template TData - The type of data in the table. It must extend `SelectableTableData`.
+ * @param {TableSelectionProps} props - Configuration for selection behavior including data, idKey, and defaults
+ * @returns {TableSelectionReturn<TData>} Selection column, state, setters, and props to spread onto useTable
  * @example
  * const {
  *   selectionColumn,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "1.13.25",
+  "version": "1.13.27",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -14,12 +14,12 @@
     "react-dnd-html5-backend": "16.0.1",
     "@tanstack/react-router": "1.114.29",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "@trackunit/shared-utils": "1.13.43",
     "@trackunit/css-class-variance-utilities": "1.11.43",
     "@trackunit/ui-icons": "1.11.42",
-    "@trackunit/react-table-base-components": "1.13.25",
-    "@trackunit/react-form-components": "1.14.25",
+    "@trackunit/react-table-base-components": "1.13.27",
+    "@trackunit/react-form-components": "1.14.27",
     "@trackunit/i18n-library-translation": "1.12.28",
     "@trackunit/iris-app-runtime-core-api": "1.12.24",
     "graphql": "^16.10.0"

package/src/Table.d.ts

@@ -69,16 +69,28 @@ export interface TableProps<TData extends object> extends ReactTable<TData>, Com
      * When provided, only rows returning true will have pointer cursor and trigger `onRowClick`.
      */
     isRowClickable?: (row: TData) => boolean;
+    /**
+     * Callback fired when a column drag operation begins. Receives the column ID being dragged.
+     * Used for custom column reorder logic or analytics.
+     */
     onColumnDragStart?: (columnId: string) => void;
 }
 /**
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
+ * Table displays large data sets with virtual scrolling, column sorting, filtering, resizing, drag-and-drop column reordering,
+ * and row selection. It extends `@tanstack/react-table` and uses `useTable` to create the table instance.
+ * Infinite scroll pagination is handled via `RelayPagination` from `usePaginationQuery`.
+ *
+ * For the full TanStack Table API, see [TanStack Table docs](https://tanstack.com/table/v8/docs/guide/introduction).
+ *
+ * ### When to use
+ * Use Table for displaying structured data with sorting, pagination, or row actions — for example, asset lists, event logs, or user management views.
+ *
+ * ### When not to use
+ * Do not use Table for simple key-value displays — use a layout with `Text` components.
+ * Do not use Table for small card-based lists — use `List`.
  *
- * @param {ReactTable} props - The props for the Table component
+ * @param {TableProps} props - The props for the Table component
  * @returns {ReactElement} Table component
- * Table component for displaying large sets of data in tables with infinite scroll, sorting, filtering and others.
- * Table is extending the `@tanstack/react-table` Table component.
- * For more information about the `@tanstack/react-table` Table component, visit [https://tanstack.com/table/v8/docs/guide/introduction](https://tanstack.com/table/v8/docs/guide/introduction).
  * @example
  * ```tsx
  * import { createColumnHelper, Table, useTable } from "@trackunit/react-table";

package/src/useTableSelection.d.ts

@@ -56,14 +56,18 @@ export interface TableSelectionReturn<TData extends SelectableTableData> {
     toggleRowSelectionState: (id: TData[keyof TData]) => void;
 }
 /**
- * `useTableSelection` is a custom hook that provides functionality for row selection in a table.
- * It returns an object containing methods and values related to row selection.
+ * `useTableSelection` provides row selection state management for the Table component.
+ * It returns a selection checkbox column definition, row selection state, and props to spread onto `useTable`.
  *
- * @template TData - The type of data in the table. It must extend `selectableTableData`, which means it should at least have an `id` field.
- * @returns {TableSelectionReturn<TData>} An object containing:
- * - `selectionColumn`: A `ColumnDef` object for the selection column, which includes a checkbox in each cell and header.
- * - `rowSelection`: The current state of row selection.
- * - `setRowSelection`: A function to update the row selection state.
+ * ### When to use
+ * Use useTableSelection when your Table needs checkbox-based row selection — for example, bulk actions on selected assets.
+ *
+ * ### When not to use
+ * Do not use useTableSelection if your table does not need row selection. For single-row actions, use `onRowClick` on the Table instead.
+ *
+ * @template TData - The type of data in the table. It must extend `SelectableTableData`.
+ * @param {TableSelectionProps} props - Configuration for selection behavior including data, idKey, and defaults
+ * @returns {TableSelectionReturn<TData>} Selection column, state, setters, and props to spread onto useTable
  * @example
  * const {
  *   selectionColumn,