@trackunit/react-table 2.4.2-alpha-3b19e5fe058.0 → 2.5.5-alpha-770d9994af7.0

package/index.cjs.js

@@ -108,6 +108,18 @@ const setupLibraryTranslations = () => {
     i18nLibraryTranslation.registerTranslations(translations);
 };
 
+/**
+ * Renders the icon for an action button.
+ * Should not be used outside the ActionSheet component.
+ *
+ * @param {ActionIconProps} props - The properties for the action icon.
+ * @param {ActionModel} props.action - The action model defining what action to perform.
+ * @returns {ReactElement | null} - The icon for the action button, or null if no icon is defined.
+ */
+const ActionIcon = ({ action }) => {
+    return action.icon ? (jsxRuntime.jsx(reactComponents.Icon, { color: "white", "data-testid": "action-icon", name: action.icon, ref: action.ref, size: "small", style: action.style })) : null;
+};
+
 const cvaActionSheet = cssClassVarianceUtilities.cvaMerge([
     "w-[760px]",
     "max-w-[80%]",
@@ -165,18 +177,6 @@ const cvaMoreContainer = cssClassVarianceUtilities.cvaMerge([
     },
 });
 
-/**
- * Renders the icon for an action button.
- * Should not be used outside the ActionSheet component.
- *
- * @param {ActionIconProps} props - The properties for the action icon.
- * @param {ActionModel} props.action - The action model defining what action to perform.
- * @returns {ReactElement | null} - The icon for the action button, or null if no icon is defined.
- */
-const ActionIcon = ({ action }) => {
-    return action.icon ? (jsxRuntime.jsx(reactComponents.Icon, { color: "white", "data-testid": "action-icon", name: action.icon, ref: action.ref, size: "small", style: action.style })) : null;
-};
-
 /**
  * The button to show in the ActionSheet.
  * Should not be used outside the ActionSheet component.
@@ -258,7 +258,7 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
                         ? dropdownActions.map(action => {
                             return (jsxRuntime.jsx(reactComponents.MoreMenu, { customButton: jsxRuntime.jsx(reactComponents.Button, { "data-testid": action["data-testid"], id: action.id, loading: action.loading, onClick: action.method, prefix: jsxRuntime.jsx(ActionIcon, { action: action }), children: action.label }), "data-testid": `${dataTestId}-dropdown-more-menu`, popoverProps: { placement: "top-end" }, children: !action.loading ? action.dropdown : null }, action.id));
                         })
-                        : null, react.Children.count(moreActions) > 0 || overflowItemCount ? (jsxRuntime.jsx(reactComponents.MoreMenu, { "data-testid": `${dataTestId}-more-menu`, iconButtonProps: { variant: "primary" }, iconProps: { color: "white" }, popoverProps: { placement: "top-end" }, children: close => (jsxRuntime.jsxs(reactComponents.MenuList, { className: "relative -right-2", onClick: close, children: [moreActions ? moreActions : null, actions.map(action => {
+                        : null, react.Children.count(moreActions) > 0 || overflowItemCount ? (jsxRuntime.jsx(reactComponents.MoreMenu, { "data-testid": `${dataTestId}-more-menu`, iconButtonProps: { variant: "primary" }, iconProps: { color: "white" }, popoverProps: { placement: "top-end" }, children: close => (jsxRuntime.jsxs(reactComponents.MenuContent, { className: "relative -right-2", onClick: close, children: [moreActions ? moreActions : null, actions.map(action => {
                                     return itemOverflowMap[action.id] ? actionDataToMenuItem(action, dataTestId) : null;
                                 })] })) })) : null] })] }));
 };
@@ -343,7 +343,7 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
  * @example With dropdown actions
  * ```tsx
  * import { ActionSheet } from "@trackunit/react-table";
- * import { MenuList, MenuItem } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem } from "@trackunit/react-components";
  *
  * <ActionSheet
  *   selections={selectedIds}
@@ -356,10 +356,10 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
  *       label: "Change Status",
  *       iconName: "Flag",
  *       dropdownContent: (close) => (
- *         <MenuList>
+ *         <MenuContent>
  *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
  *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
- *         </MenuList>
+ *         </MenuContent>
  *       ),
  *     },
  *   ]}
@@ -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,
@@ -781,7 +792,7 @@ const ColumnFilter = ({ columns, setColumnOrder, defaultColumnOrder = [], column
                 setSearchText("");
             }
         }, placement: "bottom-start", children: () => {
-            return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(reactComponents.PopoverTrigger, { children: jsxRuntime.jsx(reactComponents.IconButton, { icon: jsxRuntime.jsx(reactComponents.Icon, { name: "Cog6Tooth", size: "small" }), size: "small", title: t("table.columnFilters.tooltip"), variant: "secondary" }) }), jsxRuntime.jsx(reactComponents.PopoverContent, { children: () => (jsxRuntime.jsx(reactDnd.DndProvider, { backend: reactDndHtml5Backend.HTML5Backend, children: jsxRuntime.jsxs(reactComponents.MenuList, { className: "relative max-h-[55vh] w-72 overflow-y-auto", children: [jsxRuntime.jsxs("div", { className: "mb-2 flex items-center gap-1", children: [jsxRuntime.jsx(reactFormComponents.Search, { autoFocus: true, className: "flex-1", fieldSize: "small", id: "column-search", onChange: e => setSearchText(e.currentTarget.value.toLowerCase()), onClear: () => setSearchText(""), placeholder: t("table.search.placeholder"), value: searchText }), jsxRuntime.jsx(reactComponents.Button, { "data-testid": "resetColumnState", onClick: resetColumnState, size: "small", variant: "ghost-neutral", children: t("layout.actions.reset") })] }), jsxRuntime.jsx(ColumnFiltersDragAndDrop, { columns: sortedColumns, isSortDisabled: !!searchText, onUserEvent: onUserEvent, setColumnOrder: setColumnOrder, visibleColumnsCount: visibleColumnsCount })] }) })) })] }));
+            return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx(reactComponents.PopoverTrigger, { children: jsxRuntime.jsx(reactComponents.IconButton, { icon: jsxRuntime.jsx(reactComponents.Icon, { name: "Cog6Tooth", size: "small" }), size: "small", title: t("table.columnFilters.tooltip"), variant: "secondary" }) }), jsxRuntime.jsx(reactComponents.PopoverContent, { children: () => (jsxRuntime.jsx(reactDnd.DndProvider, { backend: reactDndHtml5Backend.HTML5Backend, children: jsxRuntime.jsxs(reactComponents.MenuContent, { className: "relative max-h-[55vh] w-72 overflow-y-auto", children: [jsxRuntime.jsxs("div", { className: "mb-2 flex items-center gap-1", children: [jsxRuntime.jsx(reactFormComponents.Search, { autoFocus: true, className: "flex-1", fieldSize: "small", id: "column-search", onChange: e => setSearchText(e.currentTarget.value.toLowerCase()), onClear: () => setSearchText(""), placeholder: t("table.search.placeholder"), value: searchText }), jsxRuntime.jsx(reactComponents.Button, { "data-testid": "resetColumnState", onClick: resetColumnState, size: "small", variant: "ghost-neutral", children: t("layout.actions.reset") })] }), jsxRuntime.jsx(ColumnFiltersDragAndDrop, { columns: sortedColumns, isSortDisabled: !!searchText, onUserEvent: onUserEvent, setColumnOrder: setColumnOrder, visibleColumnsCount: visibleColumnsCount })] }) })) })] }));
         } }));
 };
 const ColumnFiltersDragAndDrop = ({ columns, setColumnOrder, onUserEvent, isSortDisabled, visibleColumnsCount, }) => {
@@ -860,7 +871,7 @@ const Sorting = ({ columns, }) => {
         const chosenColumn = sortableColumns.find(column => column.id === currentSortValue);
         chosenColumn?.toggleSorting(selectedValue === "desc");
     };
-    return (jsxRuntime.jsx(reactComponents.Tooltip, { label: t("table.sorting.toolip"), placement: "bottom", children: jsxRuntime.jsxs(reactComponents.Popover, { placement: "bottom-start", children: [jsxRuntime.jsx(reactComponents.PopoverTrigger, { children: jsxRuntime.jsx(reactComponents.Button, { prefix: currentSortDirection === "asc" ? (jsxRuntime.jsx(reactComponents.Icon, { name: "BarsArrowUp", size: "small" })) : (jsxRuntime.jsx(reactComponents.Icon, { name: "BarsArrowDown", size: "small" })), size: "small", variant: "ghost-neutral", children: jsxRuntime.jsx("span", { className: "hidden sm:block", children: t("table.sorting.label") }) }) }), jsxRuntime.jsx(reactComponents.PopoverContent, { children: jsxRuntime.jsxs(reactComponents.MenuList, { className: "max-h-[55vh] overflow-y-auto", children: [jsxRuntime.jsx(reactFormComponents.RadioGroup, { id: "sortProperty", onChange: handleSelectionChange, value: currentSortValue ?? "", children: sortableColumns.map(column => (jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: column.columnDef.header?.toString() ?? "", value: column.id }, column.id))) }), jsxRuntime.jsxs(reactFormComponents.RadioGroup, { id: "sortOrder", onChange: onSelectOrder, value: currentSortDirection, children: [jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: t("table.sorting.ascending"), value: "asc" }), jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: t("table.sorting.descending"), value: "desc" })] })] }) })] }) }));
+    return (jsxRuntime.jsx(reactComponents.Tooltip, { label: t("table.sorting.toolip"), placement: "bottom", children: jsxRuntime.jsxs(reactComponents.Popover, { placement: "bottom-start", children: [jsxRuntime.jsx(reactComponents.PopoverTrigger, { children: jsxRuntime.jsx(reactComponents.Button, { prefix: currentSortDirection === "asc" ? (jsxRuntime.jsx(reactComponents.Icon, { name: "BarsArrowUp", size: "small" })) : (jsxRuntime.jsx(reactComponents.Icon, { name: "BarsArrowDown", size: "small" })), size: "small", variant: "ghost-neutral", children: jsxRuntime.jsx("span", { className: "hidden sm:block", children: t("table.sorting.label") }) }) }), jsxRuntime.jsx(reactComponents.PopoverContent, { children: jsxRuntime.jsx("div", { className: reactComponents.cvaMenu({ className: "max-h-[55vh] overflow-y-auto", limitWidth: true }), children: jsxRuntime.jsxs("div", { className: reactComponents.cvaMenuList(), children: [jsxRuntime.jsx(reactFormComponents.RadioGroup, { id: "sortProperty", onChange: handleSelectionChange, value: currentSortValue ?? "", children: sortableColumns.map(column => (jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: column.columnDef.header?.toString() ?? "", value: column.id }, column.id))) }), jsxRuntime.jsxs(reactFormComponents.RadioGroup, { id: "sortOrder", onChange: onSelectOrder, value: currentSortDirection, children: [jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: t("table.sorting.ascending"), value: "asc" }), jsxRuntime.jsx(reactFormComponents.RadioItem, { className: "w-full", label: t("table.sorting.descending"), value: "desc" })] })] }) }) })] }) }));
 };
 
 /**
@@ -1276,7 +1287,7 @@ const ColumnActions = ({ header, visibleColumnsCount, setSorting, getColumn }) =
     if (!isAnyActionAvailable) {
         return null;
     }
-    return (jsxRuntime.jsx(reactComponents.MoreMenu, { customButton: jsxRuntime.jsx(reactComponents.IconButton, { className: "h-8 w-5 p-0", icon: jsxRuntime.jsx(reactComponents.Icon, { name: "EllipsisVertical", size: "small" }), onClick: event => event.stopPropagation(), title: t("table.columnActions.moreActions"), variant: "ghost-neutral" }), children: close => (jsxRuntime.jsxs(reactComponents.MenuList, { children: [showSortAscending ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.sortAscending"), onClick: handleSortAscending, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowUp", size: "medium" }) })) : null, showSortDescending ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.sortDescending"), onClick: handleSortDescending, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowDown", size: "medium" }) })) : null, showClearSorting !== false && showClearSorting !== undefined ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.clearSorting"), onClick: handleClearSorting, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowsUpDown", size: "medium" }) })) : null, showHideColumn ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.hideColumn"), onClick: () => header.column.toggleVisibility(false), prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "EyeSlash", size: "medium" }) })) : null, canPin ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t(isPinned !== false ? "table.columnActions.unPinColumn" : "table.columnActions.pinColumn"), onClick: () => {
+    return (jsxRuntime.jsx(reactComponents.MoreMenu, { customButton: jsxRuntime.jsx(reactComponents.IconButton, { className: "h-8 w-5 p-0", icon: jsxRuntime.jsx(reactComponents.Icon, { name: "EllipsisVertical", size: "small" }), onClick: event => event.stopPropagation(), title: t("table.columnActions.moreActions"), variant: "ghost-neutral" }), children: close => (jsxRuntime.jsxs(reactComponents.MenuContent, { children: [showSortAscending ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.sortAscending"), onClick: handleSortAscending, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowUp", size: "medium" }) })) : null, showSortDescending ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.sortDescending"), onClick: handleSortDescending, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowDown", size: "medium" }) })) : null, showClearSorting !== false && showClearSorting !== undefined ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.clearSorting"), onClick: handleClearSorting, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "ArrowsUpDown", size: "medium" }) })) : null, showHideColumn ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t("table.columnActions.hideColumn"), onClick: () => header.column.toggleVisibility(false), prefix: jsxRuntime.jsx(reactComponents.Icon, { name: "EyeSlash", size: "medium" }) })) : null, canPin ? (jsxRuntime.jsx(reactComponents.MenuItem, { label: t(isPinned !== false ? "table.columnActions.unPinColumn" : "table.columnActions.pinColumn"), onClick: () => {
                         header.column.pin(isPinned !== false ? false : "left");
                         close();
                     }, prefix: jsxRuntime.jsx(reactComponents.Icon, { name: isPinned !== false ? "Unpin" : "Pin", size: "medium" }) })) : null] })) }));
@@ -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 { Icon, MenuItem, Button, Tooltip, useOverflowItems, MoreMenu, MenuContent, Spacer, usePersistedState, useDebounce, Text, cvaInteractableItem, Popover, PopoverTrigger, IconButton, PopoverContent, cvaMenuList, cvaMenu, useBidirectionalScroll, noPagination, Card, Spinner, EmptyState } from '@trackunit/react-components';
+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';
@@ -107,6 +107,18 @@ const setupLibraryTranslations = () => {
     registerTranslations(translations);
 };
 
+/**
+ * Renders the icon for an action button.
+ * Should not be used outside the ActionSheet component.
+ *
+ * @param {ActionIconProps} props - The properties for the action icon.
+ * @param {ActionModel} props.action - The action model defining what action to perform.
+ * @returns {ReactElement | null} - The icon for the action button, or null if no icon is defined.
+ */
+const ActionIcon = ({ action }) => {
+    return action.icon ? (jsx(Icon, { color: "white", "data-testid": "action-icon", name: action.icon, ref: action.ref, size: "small", style: action.style })) : null;
+};
+
 const cvaActionSheet = cvaMerge([
     "w-[760px]",
     "max-w-[80%]",
@@ -164,18 +176,6 @@ const cvaMoreContainer = cvaMerge([
     },
 });
 
-/**
- * Renders the icon for an action button.
- * Should not be used outside the ActionSheet component.
- *
- * @param {ActionIconProps} props - The properties for the action icon.
- * @param {ActionModel} props.action - The action model defining what action to perform.
- * @returns {ReactElement | null} - The icon for the action button, or null if no icon is defined.
- */
-const ActionIcon = ({ action }) => {
-    return action.icon ? (jsx(Icon, { color: "white", "data-testid": "action-icon", name: action.icon, ref: action.ref, size: "small", style: action.style })) : null;
-};
-
 /**
  * The button to show in the ActionSheet.
  * Should not be used outside the ActionSheet component.
@@ -257,7 +257,7 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
                         ? dropdownActions.map(action => {
                             return (jsx(MoreMenu, { customButton: jsx(Button, { "data-testid": action["data-testid"], id: action.id, loading: action.loading, onClick: action.method, prefix: jsx(ActionIcon, { action: action }), children: action.label }), "data-testid": `${dataTestId}-dropdown-more-menu`, popoverProps: { placement: "top-end" }, children: !action.loading ? action.dropdown : null }, action.id));
                         })
-                        : null, Children.count(moreActions) > 0 || overflowItemCount ? (jsx(MoreMenu, { "data-testid": `${dataTestId}-more-menu`, iconButtonProps: { variant: "primary" }, iconProps: { color: "white" }, popoverProps: { placement: "top-end" }, children: close => (jsxs(MenuList, { className: "relative -right-2", onClick: close, children: [moreActions ? moreActions : null, actions.map(action => {
+                        : null, Children.count(moreActions) > 0 || overflowItemCount ? (jsx(MoreMenu, { "data-testid": `${dataTestId}-more-menu`, iconButtonProps: { variant: "primary" }, iconProps: { color: "white" }, popoverProps: { placement: "top-end" }, children: close => (jsxs(MenuContent, { className: "relative -right-2", onClick: close, children: [moreActions ? moreActions : null, actions.map(action => {
                                     return itemOverflowMap[action.id] ? actionDataToMenuItem(action, dataTestId) : null;
                                 })] })) })) : null] })] }));
 };
@@ -342,7 +342,7 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
  * @example With dropdown actions
  * ```tsx
  * import { ActionSheet } from "@trackunit/react-table";
- * import { MenuList, MenuItem } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem } from "@trackunit/react-components";
  *
  * <ActionSheet
  *   selections={selectedIds}
@@ -355,10 +355,10 @@ const ActionContainerAndOverflow = ({ actions, dropdownActions, moreActions, "da
  *       label: "Change Status",
  *       iconName: "Flag",
  *       dropdownContent: (close) => (
- *         <MenuList>
+ *         <MenuContent>
  *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
  *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
- *         </MenuList>
+ *         </MenuContent>
  *       ),
  *     },
  *   ]}
@@ -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,
@@ -780,7 +791,7 @@ const ColumnFilter = ({ columns, setColumnOrder, defaultColumnOrder = [], column
                 setSearchText("");
             }
         }, placement: "bottom-start", children: () => {
-            return (jsxs(Fragment, { children: [jsx(PopoverTrigger, { children: jsx(IconButton, { icon: jsx(Icon, { name: "Cog6Tooth", size: "small" }), size: "small", title: t("table.columnFilters.tooltip"), variant: "secondary" }) }), jsx(PopoverContent, { children: () => (jsx(DndProvider, { backend: HTML5Backend, children: jsxs(MenuList, { className: "relative max-h-[55vh] w-72 overflow-y-auto", children: [jsxs("div", { className: "mb-2 flex items-center gap-1", children: [jsx(Search, { autoFocus: true, className: "flex-1", fieldSize: "small", id: "column-search", onChange: e => setSearchText(e.currentTarget.value.toLowerCase()), onClear: () => setSearchText(""), placeholder: t("table.search.placeholder"), value: searchText }), jsx(Button, { "data-testid": "resetColumnState", onClick: resetColumnState, size: "small", variant: "ghost-neutral", children: t("layout.actions.reset") })] }), jsx(ColumnFiltersDragAndDrop, { columns: sortedColumns, isSortDisabled: !!searchText, onUserEvent: onUserEvent, setColumnOrder: setColumnOrder, visibleColumnsCount: visibleColumnsCount })] }) })) })] }));
+            return (jsxs(Fragment, { children: [jsx(PopoverTrigger, { children: jsx(IconButton, { icon: jsx(Icon, { name: "Cog6Tooth", size: "small" }), size: "small", title: t("table.columnFilters.tooltip"), variant: "secondary" }) }), jsx(PopoverContent, { children: () => (jsx(DndProvider, { backend: HTML5Backend, children: jsxs(MenuContent, { className: "relative max-h-[55vh] w-72 overflow-y-auto", children: [jsxs("div", { className: "mb-2 flex items-center gap-1", children: [jsx(Search, { autoFocus: true, className: "flex-1", fieldSize: "small", id: "column-search", onChange: e => setSearchText(e.currentTarget.value.toLowerCase()), onClear: () => setSearchText(""), placeholder: t("table.search.placeholder"), value: searchText }), jsx(Button, { "data-testid": "resetColumnState", onClick: resetColumnState, size: "small", variant: "ghost-neutral", children: t("layout.actions.reset") })] }), jsx(ColumnFiltersDragAndDrop, { columns: sortedColumns, isSortDisabled: !!searchText, onUserEvent: onUserEvent, setColumnOrder: setColumnOrder, visibleColumnsCount: visibleColumnsCount })] }) })) })] }));
         } }));
 };
 const ColumnFiltersDragAndDrop = ({ columns, setColumnOrder, onUserEvent, isSortDisabled, visibleColumnsCount, }) => {
@@ -859,7 +870,7 @@ const Sorting = ({ columns, }) => {
         const chosenColumn = sortableColumns.find(column => column.id === currentSortValue);
         chosenColumn?.toggleSorting(selectedValue === "desc");
     };
-    return (jsx(Tooltip, { label: t("table.sorting.toolip"), placement: "bottom", children: jsxs(Popover, { placement: "bottom-start", children: [jsx(PopoverTrigger, { children: jsx(Button, { prefix: currentSortDirection === "asc" ? (jsx(Icon, { name: "BarsArrowUp", size: "small" })) : (jsx(Icon, { name: "BarsArrowDown", size: "small" })), size: "small", variant: "ghost-neutral", children: jsx("span", { className: "hidden sm:block", children: t("table.sorting.label") }) }) }), jsx(PopoverContent, { children: jsxs(MenuList, { className: "max-h-[55vh] overflow-y-auto", children: [jsx(RadioGroup, { id: "sortProperty", onChange: handleSelectionChange, value: currentSortValue ?? "", children: sortableColumns.map(column => (jsx(RadioItem, { className: "w-full", label: column.columnDef.header?.toString() ?? "", value: column.id }, column.id))) }), jsxs(RadioGroup, { id: "sortOrder", onChange: onSelectOrder, value: currentSortDirection, children: [jsx(RadioItem, { className: "w-full", label: t("table.sorting.ascending"), value: "asc" }), jsx(RadioItem, { className: "w-full", label: t("table.sorting.descending"), value: "desc" })] })] }) })] }) }));
+    return (jsx(Tooltip, { label: t("table.sorting.toolip"), placement: "bottom", children: jsxs(Popover, { placement: "bottom-start", children: [jsx(PopoverTrigger, { children: jsx(Button, { prefix: currentSortDirection === "asc" ? (jsx(Icon, { name: "BarsArrowUp", size: "small" })) : (jsx(Icon, { name: "BarsArrowDown", size: "small" })), size: "small", variant: "ghost-neutral", children: jsx("span", { className: "hidden sm:block", children: t("table.sorting.label") }) }) }), jsx(PopoverContent, { children: jsx("div", { className: cvaMenu({ className: "max-h-[55vh] overflow-y-auto", limitWidth: true }), children: jsxs("div", { className: cvaMenuList(), children: [jsx(RadioGroup, { id: "sortProperty", onChange: handleSelectionChange, value: currentSortValue ?? "", children: sortableColumns.map(column => (jsx(RadioItem, { className: "w-full", label: column.columnDef.header?.toString() ?? "", value: column.id }, column.id))) }), jsxs(RadioGroup, { id: "sortOrder", onChange: onSelectOrder, value: currentSortDirection, children: [jsx(RadioItem, { className: "w-full", label: t("table.sorting.ascending"), value: "asc" }), jsx(RadioItem, { className: "w-full", label: t("table.sorting.descending"), value: "desc" })] })] }) }) })] }) }));
 };
 
 /**
@@ -1275,7 +1286,7 @@ const ColumnActions = ({ header, visibleColumnsCount, setSorting, getColumn }) =
     if (!isAnyActionAvailable) {
         return null;
     }
-    return (jsx(MoreMenu, { customButton: jsx(IconButton, { className: "h-8 w-5 p-0", icon: jsx(Icon, { name: "EllipsisVertical", size: "small" }), onClick: event => event.stopPropagation(), title: t("table.columnActions.moreActions"), variant: "ghost-neutral" }), children: close => (jsxs(MenuList, { children: [showSortAscending ? (jsx(MenuItem, { label: t("table.columnActions.sortAscending"), onClick: handleSortAscending, prefix: jsx(Icon, { name: "ArrowUp", size: "medium" }) })) : null, showSortDescending ? (jsx(MenuItem, { label: t("table.columnActions.sortDescending"), onClick: handleSortDescending, prefix: jsx(Icon, { name: "ArrowDown", size: "medium" }) })) : null, showClearSorting !== false && showClearSorting !== undefined ? (jsx(MenuItem, { label: t("table.columnActions.clearSorting"), onClick: handleClearSorting, prefix: jsx(Icon, { name: "ArrowsUpDown", size: "medium" }) })) : null, showHideColumn ? (jsx(MenuItem, { label: t("table.columnActions.hideColumn"), onClick: () => header.column.toggleVisibility(false), prefix: jsx(Icon, { name: "EyeSlash", size: "medium" }) })) : null, canPin ? (jsx(MenuItem, { label: t(isPinned !== false ? "table.columnActions.unPinColumn" : "table.columnActions.pinColumn"), onClick: () => {
+    return (jsx(MoreMenu, { customButton: jsx(IconButton, { className: "h-8 w-5 p-0", icon: jsx(Icon, { name: "EllipsisVertical", size: "small" }), onClick: event => event.stopPropagation(), title: t("table.columnActions.moreActions"), variant: "ghost-neutral" }), children: close => (jsxs(MenuContent, { children: [showSortAscending ? (jsx(MenuItem, { label: t("table.columnActions.sortAscending"), onClick: handleSortAscending, prefix: jsx(Icon, { name: "ArrowUp", size: "medium" }) })) : null, showSortDescending ? (jsx(MenuItem, { label: t("table.columnActions.sortDescending"), onClick: handleSortDescending, prefix: jsx(Icon, { name: "ArrowDown", size: "medium" }) })) : null, showClearSorting !== false && showClearSorting !== undefined ? (jsx(MenuItem, { label: t("table.columnActions.clearSorting"), onClick: handleClearSorting, prefix: jsx(Icon, { name: "ArrowsUpDown", size: "medium" }) })) : null, showHideColumn ? (jsx(MenuItem, { label: t("table.columnActions.hideColumn"), onClick: () => header.column.toggleVisibility(false), prefix: jsx(Icon, { name: "EyeSlash", size: "medium" }) })) : null, canPin ? (jsx(MenuItem, { label: t(isPinned !== false ? "table.columnActions.unPinColumn" : "table.columnActions.pinColumn"), onClick: () => {
                         header.column.pin(isPinned !== false ? false : "left");
                         close();
                     }, prefix: jsx(Icon, { name: isPinned !== false ? "Unpin" : "Pin", size: "medium" }) })) : null] })) }));
@@ -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.2-alpha-3b19e5fe058.0",
+  "version": "2.5.5-alpha-770d9994af7.0",
   "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.2-alpha-3b19e5fe058.0",
-    "@trackunit/react-core-hooks": "1.20.1-alpha-3b19e5fe058.0",
-    "@trackunit/shared-utils": "1.16.1-alpha-3b19e5fe058.0",
-    "@trackunit/css-class-variance-utilities": "1.14.1-alpha-3b19e5fe058.0",
-    "@trackunit/ui-icons": "1.14.1-alpha-3b19e5fe058.0",
-    "@trackunit/react-table-base-components": "2.4.2-alpha-3b19e5fe058.0",
-    "@trackunit/react-form-components": "2.4.2-alpha-3b19e5fe058.0",
-    "@trackunit/i18n-library-translation": "2.3.1-alpha-3b19e5fe058.0",
-    "@trackunit/iris-app-runtime-core-api": "1.17.1-alpha-3b19e5fe058.0",
+    "@trackunit/react-components": "2.6.2-alpha-770d9994af7.0",
+    "@trackunit/react-core-hooks": "1.20.4-alpha-770d9994af7.0",
+    "@trackunit/shared-utils": "1.16.3-alpha-770d9994af7.0",
+    "@trackunit/css-class-variance-utilities": "1.14.3-alpha-770d9994af7.0",
+    "@trackunit/ui-icons": "1.14.3-alpha-770d9994af7.0",
+    "@trackunit/react-table-base-components": "2.4.7-alpha-770d9994af7.0",
+    "@trackunit/react-form-components": "2.4.7-alpha-770d9994af7.0",
+    "@trackunit/i18n-library-translation": "2.3.4-alpha-770d9994af7.0",
+    "@trackunit/iris-app-runtime-core-api": "1.17.3-alpha-770d9994af7.0",
     "zod": "^3.25.76"
   },
   "peerDependencies": {

package/src/ActionSheet/ActionSheet.d.ts

@@ -10,7 +10,7 @@ export interface ActionSheetProps extends CommonProps, Styleable {
      */
     moreActions?: Array<ActionModel>;
     /**
-     * Actions to be displayed as primary actions with capability to pass MenuList as dropdown
+     * Actions to be displayed as primary actions with capability to pass MenuContent as dropdown
      */
     dropdownActions?: Array<DropdownModel>;
     /**
@@ -102,7 +102,7 @@ export interface ActionSheetProps extends CommonProps, Styleable {
  * @example With dropdown actions
  * ```tsx
  * import { ActionSheet } from "@trackunit/react-table";
- * import { MenuList, MenuItem } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem } from "@trackunit/react-components";
  *
  * <ActionSheet
  *   selections={selectedIds}
@@ -115,10 +115,10 @@ export interface ActionSheetProps extends CommonProps, Styleable {
  *       label: "Change Status",
  *       iconName: "Flag",
  *       dropdownContent: (close) => (
- *         <MenuList>
+ *         <MenuContent>
  *           <MenuItem label="Active" onClick={() => { setStatus("active"); close(); }} />
  *           <MenuItem label="Inactive" onClick={() => { setStatus("inactive"); close(); }} />
- *         </MenuList>
+ *         </MenuContent>
  *       ),
  *     },
  *   ]}

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/menus/Sorting.d.ts

@@ -1,7 +1,8 @@
 import { Column } from "@tanstack/react-table";
 import { ReactElement } from "react";
+type SortableColumn<TSorting extends object, TSortingValue> = Pick<Column<TSorting, TSortingValue>, "id" | "getCanSort" | "getIsSorted" | "toggleSorting" | "columnDef">;
 interface SortingProps<TSorting extends object, TSortingValue> {
-    columns: Array<Column<TSorting, TSortingValue>>;
+    columns: Array<SortableColumn<TSorting, TSortingValue>>;
 }
 /**
  * Sorting component for managing table column sorting.

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} />;