@trackunit/react-table 2.4.1-alpha-7bd3cf90b54.0 → 2.5.2

package/index.cjs.js

@@ -568,6 +568,12 @@ const validateTableState = (raw) => {
  * the URL, such as `expanded`, still survive reloads. Changes are
  * debounced (300 ms) and synced to both the hash and localStorage.
  *
+ * `onTableStateChange` takes a *partial* state and merges it into whatever
+ * was reported earlier in the session, so a consumer can report a single
+ * slice (e.g. only `expanded`) without the omitted fields falling back to
+ * their mount-time values. A field reported empty is dropped from the stored
+ * state, and once every field is empty the entry is removed altogether.
+ *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
  * @returns {UseTablePersistenceResult} An object containing:
@@ -583,7 +589,7 @@ const useTablePersistence = (persistenceKey) => {
     const { clientSideUserId } = reactCoreHooks.useCurrentUser();
     const localStorageEnabled = clientSideUserId !== undefined;
     const { toUrlValue, fromUrlValue } = useCompactTableUrl();
-    const { initialState, persistState } = reactComponents.usePersistedState({
+    const { initialState, persistState, clearState } = reactComponents.usePersistedState({
         key: `${persistenceKey}Tp`,
         validate: validateTableState,
         toUrlValue,
@@ -602,6 +608,7 @@ const useTablePersistence = (persistenceKey) => {
     });
     const [pendingState, setPendingState] = react.useState(null);
     const debouncedPending = reactComponents.useDebounce(pendingState, { delay: 300 });
+    const hasReportedChange = debouncedPending !== null;
     const currentState = react.useMemo(() => {
         if (!debouncedPending && !initialState) {
             return undefined;
@@ -616,10 +623,10 @@ const useTablePersistence = (persistenceKey) => {
         if (columnOrder && columnOrder.length > 0) {
             state.columnOrder = columnOrder;
         }
-        if (columnSizing && Object.keys(columnSizing).length > 0) {
+        if (columnSizing && sharedUtils.objectKeys(columnSizing).length > 0) {
             state.columnSizing = columnSizing;
         }
-        if (columnVisibility && Object.keys(columnVisibility).length > 0) {
+        if (columnVisibility && sharedUtils.objectKeys(columnVisibility).length > 0) {
             state.columnVisibility = columnVisibility;
         }
         if (sorting && sorting.length > 0) {
@@ -628,23 +635,27 @@ const useTablePersistence = (persistenceKey) => {
         if (columnPinning && ((columnPinning.left?.length ?? 0) > 0 || (columnPinning.right?.length ?? 0) > 0)) {
             state.columnPinning = columnPinning;
         }
-        if (expanded === true || (typeof expanded === "object" && Object.keys(expanded).length > 0)) {
+        if (expanded === true || (typeof expanded === "object" && sharedUtils.objectKeys(expanded).length > 0)) {
             state.expanded = expanded;
         }
-        return Object.keys(state).length > 0 ? state : undefined;
-    }, [debouncedPending, initialState]);
+        return sharedUtils.objectKeys(state).length > 0 || hasReportedChange ? state : undefined;
+    }, [debouncedPending, hasReportedChange, initialState]);
     const onTableStateChange = react.useCallback((newTableState) => {
         if (!newTableState) {
             return;
         }
-        setPendingState(newTableState);
+        setPendingState(previousState => ({ ...previousState, ...newTableState }));
     }, []);
     react.useEffect(() => {
         if (!currentState) {
             return;
         }
+        if (sharedUtils.objectKeys(currentState).length === 0) {
+            clearState();
+            return;
+        }
         persistState(currentState);
-    }, [currentState, persistState]);
+    }, [clearState, currentState, persistState]);
     return react.useMemo(() => ({
         onTableStateChange,
         initialState,
@@ -1708,6 +1719,13 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
  *   orchestration that the raw hook does not provide.
  *
+ * Row expansion is managed like the column state: it starts from `initialState.expanded`, and
+ * expand/collapse changes are reported to `onTableStateChange` so they can be persisted — unless
+ * the consumer passes `state.expanded`, in which case it owns what is worth storing.
+ *
+ * `onTableStateChange` is called with the field that changed, not the whole state, so anything
+ * storing it has to merge each report into what it already holds. `useTablePersistence` does.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
  * @returns {object} An object containing the React Table instance and associated state management functions.
@@ -1732,7 +1750,7 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  *     data,
  *     columns,
  *     initialState: { sorting: [{ id: "name", desc: false }] },
- *     onTableStateChange: state => saveTablePreferences(state),
+ *     onTableStateChange: changedField => setPreferences(previous => ({ ...previous, ...changedField })),
  *   });
  *
  *   return <Table table={table} />;
@@ -1828,20 +1846,27 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
     const columnPinning = react.useMemo(() => userEdits.columnPinning ?? computeMergedPinning(initialState?.columnPinning, stableUpdatedInitialColumnPinning), [userEdits.columnPinning, initialState?.columnPinning, stableUpdatedInitialColumnPinning]);
     const sorting = react.useMemo(() => userEdits.sorting ?? initialState?.sorting ?? [], [userEdits.sorting, initialState?.sorting]);
     const columnSizing = react.useMemo(() => userEdits.columnSizing ?? initialState?.columnSizing ?? {}, [userEdits.columnSizing, initialState?.columnSizing]);
-    const baseState = react.useMemo(() => ({ columnVisibility, columnOrder, sorting, columnSizing, columnPinning }), [columnVisibility, columnOrder, sorting, columnSizing, columnPinning]);
+    const expanded = react.useMemo(() => userEdits.expanded ?? initialState?.expanded ?? {}, [userEdits.expanded, initialState?.expanded]);
+    const baseState = react.useMemo(() => ({ columnVisibility, columnOrder, sorting, columnSizing, columnPinning, expanded }), [columnVisibility, columnOrder, sorting, columnSizing, columnPinning, expanded]);
     const state = react.useMemo(() => ({ ...baseState, ...reactTableProps.state }), [baseState, reactTableProps.state]);
     // A ref exposes the latest derived state to the change callbacks without making them depend on
-    // it (callbacks run on user events, outside render). Every column-state key on `state` is always
+    // it (callbacks run on user events, outside render). Every managed key on `state` is always
     // defined — it originates from `baseState` — so the callbacks read it directly.
     const stateRef = react.useRef(state);
     stateRef.current = state;
-    // Persist on user actions only (not on mount or prop-driven recomputation): drop column sizes
-    // that match their default so only meaningful overrides are stored.
+    // Reports only the field that changed — `useTablePersistence` merges partial reports — so a
+    // change can never store another field's unsettled or transient value. Column sizes matching
+    // their default are dropped so only meaningful overrides are stored.
     const persistTableState = react.useCallback((nextState) => {
         if (!onTableStateChange) {
             return;
         }
-        const columnSizingToPersist = Object.fromEntries(Object.entries(nextState.columnSizing ?? {}).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
+        const nextColumnSizing = nextState.columnSizing;
+        if (!nextColumnSizing) {
+            onTableStateChange(nextState);
+            return;
+        }
+        const columnSizingToPersist = Object.fromEntries(sharedUtils.objectEntries(nextColumnSizing).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
         onTableStateChange({ ...nextState, columnSizing: columnSizingToPersist });
     }, [onTableStateChange, defaultColumnSizingById]);
     const table = reactTable.useReactTable({
@@ -1855,37 +1880,46 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
             const current = stateRef.current.columnVisibility;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnVisibility: next }));
-            persistTableState({ ...stateRef.current, columnVisibility: next });
+            persistTableState({ columnVisibility: next });
             reactTableProps.onColumnVisibilityChange?.(value);
         },
         onColumnSizingChange: value => {
             const current = stateRef.current.columnSizing;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnSizing: next }));
-            persistTableState({ ...stateRef.current, columnSizing: next });
+            persistTableState({ columnSizing: next });
             reactTableProps.onColumnSizingChange?.(value);
         },
         onColumnOrderChange: value => {
             const current = stateRef.current.columnOrder;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnOrder: next }));
-            persistTableState({ ...stateRef.current, columnOrder: next });
+            persistTableState({ columnOrder: next });
             reactTableProps.onColumnOrderChange?.(value);
         },
         onSortingChange: value => {
             const current = stateRef.current.sorting;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, sorting: next }));
-            persistTableState({ ...stateRef.current, sorting: next });
+            persistTableState({ sorting: next });
             reactTableProps.onSortingChange?.(value);
         },
         onColumnPinningChange: value => {
             const current = stateRef.current.columnPinning;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnPinning: next }));
-            persistTableState({ ...stateRef.current, columnPinning: next });
+            persistTableState({ columnPinning: next });
             reactTableProps.onColumnPinningChange?.(value);
         },
+        onExpandedChange: value => {
+            const current = stateRef.current.expanded;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, expanded: next }));
+            if (reactTableProps.state?.expanded === undefined) {
+                persistTableState({ expanded: next });
+            }
+            reactTableProps.onExpandedChange?.(value);
+        },
         columns,
         state,
     });

package/index.esm.js

@@ -1,7 +1,7 @@
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation, NamespaceTrans } from '@trackunit/i18n-library-translation';
 import { Icon, MenuItem, Button, Tooltip, useOverflowItems, MoreMenu, MenuList, Spacer, usePersistedState, useDebounce, Text, cvaInteractableItem, Popover, PopoverTrigger, IconButton, PopoverContent, useBidirectionalScroll, noPagination, Card, Spinner, EmptyState } from '@trackunit/react-components';
-import { objectValues, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, nonNullable, objectKeys, objectEntries } from '@trackunit/shared-utils';
+import { objectValues, VISIBLE_ONLY_COLUMN_VISIBILITY_KEY, objectKeys, nonNullable, objectEntries } from '@trackunit/shared-utils';
 import { useMemo, Children, cloneElement, useCallback, useState, useEffect, useRef, createElement } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { Link } from '@tanstack/react-router';
@@ -567,6 +567,12 @@ const validateTableState = (raw) => {
  * the URL, such as `expanded`, still survive reloads. Changes are
  * debounced (300 ms) and synced to both the hash and localStorage.
  *
+ * `onTableStateChange` takes a *partial* state and merges it into whatever
+ * was reported earlier in the session, so a consumer can report a single
+ * slice (e.g. only `expanded`) without the omitted fields falling back to
+ * their mount-time values. A field reported empty is dropped from the stored
+ * state, and once every field is empty the entry is removed altogether.
+ *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
  * @returns {UseTablePersistenceResult} An object containing:
@@ -582,7 +588,7 @@ const useTablePersistence = (persistenceKey) => {
     const { clientSideUserId } = useCurrentUser();
     const localStorageEnabled = clientSideUserId !== undefined;
     const { toUrlValue, fromUrlValue } = useCompactTableUrl();
-    const { initialState, persistState } = usePersistedState({
+    const { initialState, persistState, clearState } = usePersistedState({
         key: `${persistenceKey}Tp`,
         validate: validateTableState,
         toUrlValue,
@@ -601,6 +607,7 @@ const useTablePersistence = (persistenceKey) => {
     });
     const [pendingState, setPendingState] = useState(null);
     const debouncedPending = useDebounce(pendingState, { delay: 300 });
+    const hasReportedChange = debouncedPending !== null;
     const currentState = useMemo(() => {
         if (!debouncedPending && !initialState) {
             return undefined;
@@ -615,10 +622,10 @@ const useTablePersistence = (persistenceKey) => {
         if (columnOrder && columnOrder.length > 0) {
             state.columnOrder = columnOrder;
         }
-        if (columnSizing && Object.keys(columnSizing).length > 0) {
+        if (columnSizing && objectKeys(columnSizing).length > 0) {
             state.columnSizing = columnSizing;
         }
-        if (columnVisibility && Object.keys(columnVisibility).length > 0) {
+        if (columnVisibility && objectKeys(columnVisibility).length > 0) {
             state.columnVisibility = columnVisibility;
         }
         if (sorting && sorting.length > 0) {
@@ -627,23 +634,27 @@ const useTablePersistence = (persistenceKey) => {
         if (columnPinning && ((columnPinning.left?.length ?? 0) > 0 || (columnPinning.right?.length ?? 0) > 0)) {
             state.columnPinning = columnPinning;
         }
-        if (expanded === true || (typeof expanded === "object" && Object.keys(expanded).length > 0)) {
+        if (expanded === true || (typeof expanded === "object" && objectKeys(expanded).length > 0)) {
             state.expanded = expanded;
         }
-        return Object.keys(state).length > 0 ? state : undefined;
-    }, [debouncedPending, initialState]);
+        return objectKeys(state).length > 0 || hasReportedChange ? state : undefined;
+    }, [debouncedPending, hasReportedChange, initialState]);
     const onTableStateChange = useCallback((newTableState) => {
         if (!newTableState) {
             return;
         }
-        setPendingState(newTableState);
+        setPendingState(previousState => ({ ...previousState, ...newTableState }));
     }, []);
     useEffect(() => {
         if (!currentState) {
             return;
         }
+        if (objectKeys(currentState).length === 0) {
+            clearState();
+            return;
+        }
         persistState(currentState);
-    }, [currentState, persistState]);
+    }, [clearState, currentState, persistState]);
     return useMemo(() => ({
         onTableStateChange,
         initialState,
@@ -1707,6 +1718,13 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
  *   orchestration that the raw hook does not provide.
  *
+ * Row expansion is managed like the column state: it starts from `initialState.expanded`, and
+ * expand/collapse changes are reported to `onTableStateChange` so they can be persisted — unless
+ * the consumer passes `state.expanded`, in which case it owns what is worth storing.
+ *
+ * `onTableStateChange` is called with the field that changed, not the whole state, so anything
+ * storing it has to merge each report into what it already holds. `useTablePersistence` does.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
  * @returns {object} An object containing the React Table instance and associated state management functions.
@@ -1731,7 +1749,7 @@ const computeMergedPinning = (initialPinning, columnConfigPinning) => {
  *     data,
  *     columns,
  *     initialState: { sorting: [{ id: "name", desc: false }] },
- *     onTableStateChange: state => saveTablePreferences(state),
+ *     onTableStateChange: changedField => setPreferences(previous => ({ ...previous, ...changedField })),
  *   });
  *
  *   return <Table table={table} />;
@@ -1827,20 +1845,27 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
     const columnPinning = useMemo(() => userEdits.columnPinning ?? computeMergedPinning(initialState?.columnPinning, stableUpdatedInitialColumnPinning), [userEdits.columnPinning, initialState?.columnPinning, stableUpdatedInitialColumnPinning]);
     const sorting = useMemo(() => userEdits.sorting ?? initialState?.sorting ?? [], [userEdits.sorting, initialState?.sorting]);
     const columnSizing = useMemo(() => userEdits.columnSizing ?? initialState?.columnSizing ?? {}, [userEdits.columnSizing, initialState?.columnSizing]);
-    const baseState = useMemo(() => ({ columnVisibility, columnOrder, sorting, columnSizing, columnPinning }), [columnVisibility, columnOrder, sorting, columnSizing, columnPinning]);
+    const expanded = useMemo(() => userEdits.expanded ?? initialState?.expanded ?? {}, [userEdits.expanded, initialState?.expanded]);
+    const baseState = useMemo(() => ({ columnVisibility, columnOrder, sorting, columnSizing, columnPinning, expanded }), [columnVisibility, columnOrder, sorting, columnSizing, columnPinning, expanded]);
     const state = useMemo(() => ({ ...baseState, ...reactTableProps.state }), [baseState, reactTableProps.state]);
     // A ref exposes the latest derived state to the change callbacks without making them depend on
-    // it (callbacks run on user events, outside render). Every column-state key on `state` is always
+    // it (callbacks run on user events, outside render). Every managed key on `state` is always
     // defined — it originates from `baseState` — so the callbacks read it directly.
     const stateRef = useRef(state);
     stateRef.current = state;
-    // Persist on user actions only (not on mount or prop-driven recomputation): drop column sizes
-    // that match their default so only meaningful overrides are stored.
+    // Reports only the field that changed — `useTablePersistence` merges partial reports — so a
+    // change can never store another field's unsettled or transient value. Column sizes matching
+    // their default are dropped so only meaningful overrides are stored.
     const persistTableState = useCallback((nextState) => {
         if (!onTableStateChange) {
             return;
         }
-        const columnSizingToPersist = Object.fromEntries(Object.entries(nextState.columnSizing ?? {}).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
+        const nextColumnSizing = nextState.columnSizing;
+        if (!nextColumnSizing) {
+            onTableStateChange(nextState);
+            return;
+        }
+        const columnSizingToPersist = Object.fromEntries(objectEntries(nextColumnSizing).filter(([columnId, size]) => defaultColumnSizingById[columnId] !== size));
         onTableStateChange({ ...nextState, columnSizing: columnSizingToPersist });
     }, [onTableStateChange, defaultColumnSizingById]);
     const table = useReactTable({
@@ -1854,37 +1879,46 @@ const useTable = ({ onTableStateChange, initialState, columns, ...reactTableProp
             const current = stateRef.current.columnVisibility;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnVisibility: next }));
-            persistTableState({ ...stateRef.current, columnVisibility: next });
+            persistTableState({ columnVisibility: next });
             reactTableProps.onColumnVisibilityChange?.(value);
         },
         onColumnSizingChange: value => {
             const current = stateRef.current.columnSizing;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnSizing: next }));
-            persistTableState({ ...stateRef.current, columnSizing: next });
+            persistTableState({ columnSizing: next });
             reactTableProps.onColumnSizingChange?.(value);
         },
         onColumnOrderChange: value => {
             const current = stateRef.current.columnOrder;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnOrder: next }));
-            persistTableState({ ...stateRef.current, columnOrder: next });
+            persistTableState({ columnOrder: next });
             reactTableProps.onColumnOrderChange?.(value);
         },
         onSortingChange: value => {
             const current = stateRef.current.sorting;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, sorting: next }));
-            persistTableState({ ...stateRef.current, sorting: next });
+            persistTableState({ sorting: next });
             reactTableProps.onSortingChange?.(value);
         },
         onColumnPinningChange: value => {
             const current = stateRef.current.columnPinning;
             const next = typeof value === "function" ? value(current) : value;
             setUserEdits(prev => ({ ...prev, columnPinning: next }));
-            persistTableState({ ...stateRef.current, columnPinning: next });
+            persistTableState({ columnPinning: next });
             reactTableProps.onColumnPinningChange?.(value);
         },
+        onExpandedChange: value => {
+            const current = stateRef.current.expanded;
+            const next = typeof value === "function" ? value(current) : value;
+            setUserEdits(prev => ({ ...prev, expanded: next }));
+            if (reactTableProps.state?.expanded === undefined) {
+                persistTableState({ expanded: next });
+            }
+            reactTableProps.onExpandedChange?.(value);
+        },
         columns,
         state,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-table",
-  "version": "2.4.1-alpha-7bd3cf90b54.0",
+  "version": "2.5.2",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -11,15 +11,15 @@
     "react-dnd": "16.0.1",
     "react-dnd-html5-backend": "16.0.1",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/react-components": "2.5.1-alpha-7bd3cf90b54.0",
-    "@trackunit/react-core-hooks": "1.20.1-alpha-7bd3cf90b54.0",
-    "@trackunit/shared-utils": "1.16.1-alpha-7bd3cf90b54.0",
-    "@trackunit/css-class-variance-utilities": "1.14.1-alpha-7bd3cf90b54.0",
-    "@trackunit/ui-icons": "1.14.1-alpha-7bd3cf90b54.0",
-    "@trackunit/react-table-base-components": "2.4.1-alpha-7bd3cf90b54.0",
-    "@trackunit/react-form-components": "2.4.1-alpha-7bd3cf90b54.0",
-    "@trackunit/i18n-library-translation": "2.3.1-alpha-7bd3cf90b54.0",
-    "@trackunit/iris-app-runtime-core-api": "1.17.1-alpha-7bd3cf90b54.0",
+    "@trackunit/react-components": "2.5.4",
+    "@trackunit/react-core-hooks": "1.20.1",
+    "@trackunit/shared-utils": "1.16.1",
+    "@trackunit/css-class-variance-utilities": "1.14.1",
+    "@trackunit/ui-icons": "1.14.1",
+    "@trackunit/react-table-base-components": "2.4.4",
+    "@trackunit/react-form-components": "2.4.4",
+    "@trackunit/i18n-library-translation": "2.3.1",
+    "@trackunit/iris-app-runtime-core-api": "1.17.1",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/hooks/useTablePersistence/useTablePersistence.d.ts

@@ -84,6 +84,12 @@ type UseTablePersistenceResult = {
  * the URL, such as `expanded`, still survive reloads. Changes are
  * debounced (300 ms) and synced to both the hash and localStorage.
  *
+ * `onTableStateChange` takes a *partial* state and merges it into whatever
+ * was reported earlier in the session, so a consumer can report a single
+ * slice (e.g. only `expanded`) without the omitted fields falling back to
+ * their mount-time values. A field reported empty is dropped from the stored
+ * state, and once every field is empty the entry is removed altogether.
+ *
  * @param persistenceKey - Unique key used to store and retrieve the table state.
  *   Must be camelCase and at most 15 characters (e.g. "userTable", "assetList").
  * @returns {UseTablePersistenceResult} An object containing:

package/src/useTable.d.ts

@@ -16,6 +16,13 @@ export interface TableOptionsProps<TData extends object> extends Omit<TableOptio
  * - Do **not** call `useReactTable` directly — `useTable` adds required column-state
  *   orchestration that the raw hook does not provide.
  *
+ * Row expansion is managed like the column state: it starts from `initialState.expanded`, and
+ * expand/collapse changes are reported to `onTableStateChange` so they can be persisted — unless
+ * the consumer passes `state.expanded`, in which case it owns what is worth storing.
+ *
+ * `onTableStateChange` is called with the field that changed, not the whole state, so anything
+ * storing it has to merge each report into what it already holds. `useTablePersistence` does.
+ *
  * @template TData - The type representing the data model associated with the table.
  * @param {TableOptionsProps<TData>} props - The props object containing configuration options.
  * @returns {object} An object containing the React Table instance and associated state management functions.
@@ -40,7 +47,7 @@ export interface TableOptionsProps<TData extends object> extends Omit<TableOptio
  *     data,
  *     columns,
  *     initialState: { sorting: [{ id: "name", desc: false }] },
- *     onTableStateChange: state => saveTablePreferences(state),
+ *     onTableStateChange: changedField => setPreferences(previous => ({ ...previous, ...changedField })),
  *   });
  *
  *   return <Table table={table} />;