@trackunit/react-table 1.21.21 → 1.21.23

package/index.cjs.js

@@ -1400,9 +1400,47 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
 /**
  * Hook for managing and controlling a table's state and behavior.
  *
+ * Wraps `@tanstack/react-table` with built-in state management for column visibility,
+ * ordering, sorting, sizing, and pinning. Reads `meta.hiddenByDefault` and `meta.pinned`
+ * from column definitions so the table is correctly configured from a single source of truth.
+ *
+ * **When to use:**
+ * - Use `useTable` whenever you render a `<Table>` component — it is the standard way to
+ *   initialise and manage table state in this codebase.
+ * - Use `useTableSelection` on top of `useTable` when you need row selection checkboxes.
+ * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
+ *   orchestration that the raw hook does not provide.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
- * @returns {TableOptionsProps<TData>} An object containing the React Table instance and associated state management functions.
+ * @returns {object} An object containing the React Table instance and associated state management functions.
+ * @example
+ * ```tsx
+ * import { createColumnHelper } from "@tanstack/react-table";
+ * import { Table, useTable } from "@trackunit/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("name", { header: "Name" }),
+ *   columnHelper.accessor("brand", { header: "Brand" }),
+ *   columnHelper.accessor("hours", {
+ *     header: "Hours",
+ *     meta: { hiddenByDefault: true },
+ *   }),
+ * ];
+ *
+ * const AssetsTable = ({ data }: { data: Asset[] }) => {
+ *   const { table } = useTable({
+ *     data,
+ *     columns,
+ *     initialState: { sorting: [{ id: "name", desc: false }] },
+ *     onTableStateChange: state => saveTablePreferences(state),
+ *   });
+ *
+ *   return <Table table={table} />;
+ * };
+ * ```
  */
 const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProps }) => {
     const stableColumns = react.useMemo(() => JSON.stringify(columns), [columns]);

package/index.esm.js

@@ -1399,9 +1399,47 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
 /**
  * Hook for managing and controlling a table's state and behavior.
  *
+ * Wraps `@tanstack/react-table` with built-in state management for column visibility,
+ * ordering, sorting, sizing, and pinning. Reads `meta.hiddenByDefault` and `meta.pinned`
+ * from column definitions so the table is correctly configured from a single source of truth.
+ *
+ * **When to use:**
+ * - Use `useTable` whenever you render a `<Table>` component — it is the standard way to
+ *   initialise and manage table state in this codebase.
+ * - Use `useTableSelection` on top of `useTable` when you need row selection checkboxes.
+ * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
+ *   orchestration that the raw hook does not provide.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
- * @returns {TableOptionsProps<TData>} An object containing the React Table instance and associated state management functions.
+ * @returns {object} An object containing the React Table instance and associated state management functions.
+ * @example
+ * ```tsx
+ * import { createColumnHelper } from "@tanstack/react-table";
+ * import { Table, useTable } from "@trackunit/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("name", { header: "Name" }),
+ *   columnHelper.accessor("brand", { header: "Brand" }),
+ *   columnHelper.accessor("hours", {
+ *     header: "Hours",
+ *     meta: { hiddenByDefault: true },
+ *   }),
+ * ];
+ *
+ * const AssetsTable = ({ data }: { data: Asset[] }) => {
+ *   const { table } = useTable({
+ *     data,
+ *     columns,
+ *     initialState: { sorting: [{ id: "name", desc: false }] },
+ *     onTableStateChange: state => saveTablePreferences(state),
+ *   });
+ *
+ *   return <Table table={table} />;
+ * };
+ * ```
  */
 const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProps }) => {
     const stableColumns = useMemo(() => JSON.stringify(columns), [columns]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "1.21.21",
+  "version": "1.21.23",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -11,14 +11,14 @@
     "react-dnd": "16.0.1",
     "react-dnd-html5-backend": "16.0.1",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "1.22.17",
-    "@trackunit/shared-utils": "1.13.111",
-    "@trackunit/css-class-variance-utilities": "1.11.111",
-    "@trackunit/ui-icons": "1.11.107",
-    "@trackunit/react-table-base-components": "1.21.21",
-    "@trackunit/react-form-components": "1.22.21",
-    "@trackunit/i18n-library-translation": "1.18.17",
-    "@trackunit/iris-app-runtime-core-api": "1.14.25"
+    "@trackunit/react-components": "1.22.19",
+    "@trackunit/shared-utils": "1.13.113",
+    "@trackunit/css-class-variance-utilities": "1.11.113",
+    "@trackunit/ui-icons": "1.11.109",
+    "@trackunit/react-table-base-components": "1.21.23",
+    "@trackunit/react-form-components": "1.22.23",
+    "@trackunit/i18n-library-translation": "1.18.19",
+    "@trackunit/iris-app-runtime-core-api": "1.14.27"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.114.29",

package/src/useTable.d.ts

@@ -5,9 +5,47 @@ export interface TableOptionsProps<TData extends object> extends Omit<TableOptio
 /**
  * Hook for managing and controlling a table's state and behavior.
  *
+ * Wraps `@tanstack/react-table` with built-in state management for column visibility,
+ * ordering, sorting, sizing, and pinning. Reads `meta.hiddenByDefault` and `meta.pinned`
+ * from column definitions so the table is correctly configured from a single source of truth.
+ *
+ * **When to use:**
+ * - Use `useTable` whenever you render a `<Table>` component — it is the standard way to
+ *   initialise and manage table state in this codebase.
+ * - Use `useTableSelection` on top of `useTable` when you need row selection checkboxes.
+ * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
+ *   orchestration that the raw hook does not provide.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
- * @returns {TableOptionsProps<TData>} An object containing the React Table instance and associated state management functions.
+ * @returns {object} An object containing the React Table instance and associated state management functions.
+ * @example
+ * ```tsx
+ * import { createColumnHelper } from "@tanstack/react-table";
+ * import { Table, useTable } from "@trackunit/react-table";
+ *
+ * const columnHelper = createColumnHelper<Asset>();
+ *
+ * const columns = [
+ *   columnHelper.accessor("name", { header: "Name" }),
+ *   columnHelper.accessor("brand", { header: "Brand" }),
+ *   columnHelper.accessor("hours", {
+ *     header: "Hours",
+ *     meta: { hiddenByDefault: true },
+ *   }),
+ * ];
+ *
+ * const AssetsTable = ({ data }: { data: Asset[] }) => {
+ *   const { table } = useTable({
+ *     data,
+ *     columns,
+ *     initialState: { sorting: [{ id: "name", desc: false }] },
+ *     onTableStateChange: state => saveTablePreferences(state),
+ *   });
+ *
+ *   return <Table table={table} />;
+ * };
+ * ```
  */
 export declare const useTable: <TData extends object>({ onTableStateChange, initialState, columns, ...reactTableProps }: TableOptionsProps<TData>) => {
     table: import("@tanstack/react-table").Table<TData>;