@trackunit/react-table-helpers 1.19.8 → 1.19.9-alpha-58b6b568fca.0

package/index.cjs.js

@@ -11,6 +11,8 @@ var reactTableBaseComponents = require('@trackunit/react-table-base-components')
 var customFieldComponents = require('@trackunit/custom-field-components');
 var filtersGraphqlHook = require('@trackunit/filters-graphql-hook');
 var reactTable = require('@trackunit/react-table');
+var dequal = require('dequal');
+var zod = require('zod');
 
 var defaultTranslations = {
 	"export.table.button": "Export"
@@ -494,6 +496,132 @@ const useColumnDefinitionsFromCustomFieldDefinition = ({ customFieldDefinitions,
     }, [filterBarDefinition, customFieldDefinitions, unitTranslation, unitPreference, language]);
 };
 
+const expandedStateSchema = zod.z.union([zod.z.literal(true), zod.z.record(zod.z.string(), zod.z.boolean())]);
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+const tableStateSchema = zod.z.object({
+    columnOrder: zod.z.array(zod.z.string()).optional(),
+    sorting: zod.z.array(zod.z.object({ id: zod.z.string(), desc: zod.z.boolean() })).optional(),
+    columnVisibility: zod.z.record(zod.z.string(), zod.z.boolean()).optional(),
+    columnSizing: zod.z.record(zod.z.string(), zod.z.number()).optional(),
+    columnPinning: zod.z
+        .object({
+        left: zod.z.array(zod.z.string()).optional(),
+        right: zod.z.array(zod.z.string()).optional(),
+    })
+        .optional(),
+    expanded: expandedStateSchema.optional(),
+});
+/**
+ * Type guard that checks whether a string is a recognised sorting property.
+ *
+ * @param sortingState - Array of valid sort property names.
+ * @param value - The value to check.
+ * @returns {boolean} `true` when {@link value} matches one of the entries in {@link sortingState}.
+ */
+const isSortByProperty = (sortingState, value) => {
+    const sortByPropertyValidated = sortingState.find(validName => validName === value);
+    return !!sortByPropertyValidated;
+};
+const MAX_URL_LENGTH = 5000;
+const getStorageKey = (persistenceKey, userId) => `table-${persistenceKey}-${userId}`;
+const safeParse = (raw) => {
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const result = tableStateSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * URL search parameters and localStorage.
+ *
+ * On mount the state is loaded from the URL (if present) or from localStorage.
+ * Changes are debounced (300 ms) and synced to both the URL and localStorage.
+ *
+ * URL updates use `window.history.replaceState` directly rather than the application router,
+ * so table state changes never interfere with other URL-persisting hooks (e.g. filter bar).
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ */
+const useTablePersistence = (persistenceKey) => {
+    const { clientSideUserId } = reactCoreHooks.useCurrentUser();
+    const { encode, decode } = reactComponents.useCustomEncoding();
+    const storageKey = getStorageKey(persistenceKey, clientSideUserId);
+    const [initialState] = react.useState(() => {
+        const urlParams = new URLSearchParams(window.location.search);
+        const fromUrl = urlParams.get(persistenceKey);
+        if (fromUrl) {
+            try {
+                const decoded = decode(fromUrl);
+                const result = tableStateSchema.safeParse(decoded);
+                if (result.success) {
+                    return result.data;
+                }
+            }
+            catch {
+                // fall through to localStorage
+            }
+        }
+        const fromStorage = localStorage.getItem(storageKey);
+        return safeParse(fromStorage);
+    });
+    const [pendingState, setPendingState] = react.useState(null);
+    const debouncedPending = reactComponents.useDebounce(pendingState, { delay: 300 });
+    const lastSavedRef = react.useRef(initialState);
+    const currentState = react.useMemo(() => {
+        if (!debouncedPending && !initialState) {
+            return undefined;
+        }
+        return {
+            columnOrder: debouncedPending?.columnOrder ?? initialState?.columnOrder ?? [],
+            columnSizing: debouncedPending?.columnSizing ?? initialState?.columnSizing ?? {},
+            columnVisibility: debouncedPending?.columnVisibility ?? initialState?.columnVisibility ?? {},
+            sorting: debouncedPending?.sorting ?? initialState?.sorting ?? [],
+            columnPinning: debouncedPending?.columnPinning ?? initialState?.columnPinning ?? {},
+            expanded: debouncedPending?.expanded ?? initialState?.expanded ?? {},
+        };
+    }, [debouncedPending, initialState]);
+    const onTableStateChange = react.useCallback((newTableState) => {
+        if (!newTableState) {
+            return;
+        }
+        setPendingState(newTableState);
+    }, []);
+    react.useEffect(() => {
+        const stateChanged = Boolean(currentState) && !dequal.dequal(lastSavedRef.current, currentState);
+        if (!stateChanged || !currentState) {
+            return;
+        }
+        lastSavedRef.current = currentState;
+        localStorage.setItem(storageKey, JSON.stringify(currentState));
+        const encoded = encode(currentState);
+        void requestAnimationFrame(() => {
+            const url = new URL(window.location.href);
+            url.searchParams.set(persistenceKey, encoded);
+            if (url.href.length <= MAX_URL_LENGTH) {
+                window.history.replaceState(window.history.state, "", url.href);
+            }
+            else {
+                url.searchParams.delete(persistenceKey);
+                window.history.replaceState(window.history.state, "", url.href);
+            }
+        });
+    }, [currentState, storageKey, encode, persistenceKey]);
+    return react.useMemo(() => ({
+        onTableStateChange,
+        initialState,
+    }), [initialState, onTableStateChange]);
+};
+
 /*
  * ----------------------------
  * | SETUP TRANSLATIONS START |
@@ -506,4 +634,6 @@ setupLibraryTranslations();
 exports.ExportTableButton = ExportTableButton;
 exports.customFieldToCell = customFieldToCell;
 exports.customFieldToExportString = customFieldToExportString;
+exports.isSortByProperty = isSortByProperty;
 exports.useColumnDefinitionsFromCustomFieldDefinition = useColumnDefinitionsFromCustomFieldDefinition;
+exports.useTablePersistence = useTablePersistence;

package/index.esm.js

@@ -1,14 +1,16 @@
 import { jsx } from 'react/jsx-runtime';
 import { registerTranslations, useNamespaceTranslation } from '@trackunit/i18n-library-translation';
-import { Button, ExternalLink } from '@trackunit/react-components';
-import { useExportDataContext } from '@trackunit/react-core-hooks';
-import { useMemo } from 'react';
+import { Button, ExternalLink, useCustomEncoding, useDebounce } from '@trackunit/react-components';
+import { useExportDataContext, useCurrentUser } from '@trackunit/react-core-hooks';
+import { useMemo, useState, useRef, useCallback, useEffect } from 'react';
 import { Temporal } from '@trackunit/date-and-time-utils';
 import { getCustomFieldValueForDisplayInUI } from '@trackunit/iris-app-runtime-core';
 import { TextCell, NumberCell, TagsCell, PlainDateCell, LinkCell, CheckboxCell } from '@trackunit/react-table-base-components';
 import { useUnitTranslation } from '@trackunit/custom-field-components';
 import { CustomFieldPrefix } from '@trackunit/filters-graphql-hook';
 import { createColumnHelper } from '@trackunit/react-table';
+import { dequal } from 'dequal';
+import { z } from 'zod';
 
 var defaultTranslations = {
 	"export.table.button": "Export"
@@ -492,6 +494,132 @@ const useColumnDefinitionsFromCustomFieldDefinition = ({ customFieldDefinitions,
     }, [filterBarDefinition, customFieldDefinitions, unitTranslation, unitPreference, language]);
 };
 
+const expandedStateSchema = z.union([z.literal(true), z.record(z.string(), z.boolean())]);
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+const tableStateSchema = z.object({
+    columnOrder: z.array(z.string()).optional(),
+    sorting: z.array(z.object({ id: z.string(), desc: z.boolean() })).optional(),
+    columnVisibility: z.record(z.string(), z.boolean()).optional(),
+    columnSizing: z.record(z.string(), z.number()).optional(),
+    columnPinning: z
+        .object({
+        left: z.array(z.string()).optional(),
+        right: z.array(z.string()).optional(),
+    })
+        .optional(),
+    expanded: expandedStateSchema.optional(),
+});
+/**
+ * Type guard that checks whether a string is a recognised sorting property.
+ *
+ * @param sortingState - Array of valid sort property names.
+ * @param value - The value to check.
+ * @returns {boolean} `true` when {@link value} matches one of the entries in {@link sortingState}.
+ */
+const isSortByProperty = (sortingState, value) => {
+    const sortByPropertyValidated = sortingState.find(validName => validName === value);
+    return !!sortByPropertyValidated;
+};
+const MAX_URL_LENGTH = 5000;
+const getStorageKey = (persistenceKey, userId) => `table-${persistenceKey}-${userId}`;
+const safeParse = (raw) => {
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const result = tableStateSchema.safeParse(parsed);
+        return result.success ? result.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * URL search parameters and localStorage.
+ *
+ * On mount the state is loaded from the URL (if present) or from localStorage.
+ * Changes are debounced (300 ms) and synced to both the URL and localStorage.
+ *
+ * URL updates use `window.history.replaceState` directly rather than the application router,
+ * so table state changes never interfere with other URL-persisting hooks (e.g. filter bar).
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ */
+const useTablePersistence = (persistenceKey) => {
+    const { clientSideUserId } = useCurrentUser();
+    const { encode, decode } = useCustomEncoding();
+    const storageKey = getStorageKey(persistenceKey, clientSideUserId);
+    const [initialState] = useState(() => {
+        const urlParams = new URLSearchParams(window.location.search);
+        const fromUrl = urlParams.get(persistenceKey);
+        if (fromUrl) {
+            try {
+                const decoded = decode(fromUrl);
+                const result = tableStateSchema.safeParse(decoded);
+                if (result.success) {
+                    return result.data;
+                }
+            }
+            catch {
+                // fall through to localStorage
+            }
+        }
+        const fromStorage = localStorage.getItem(storageKey);
+        return safeParse(fromStorage);
+    });
+    const [pendingState, setPendingState] = useState(null);
+    const debouncedPending = useDebounce(pendingState, { delay: 300 });
+    const lastSavedRef = useRef(initialState);
+    const currentState = useMemo(() => {
+        if (!debouncedPending && !initialState) {
+            return undefined;
+        }
+        return {
+            columnOrder: debouncedPending?.columnOrder ?? initialState?.columnOrder ?? [],
+            columnSizing: debouncedPending?.columnSizing ?? initialState?.columnSizing ?? {},
+            columnVisibility: debouncedPending?.columnVisibility ?? initialState?.columnVisibility ?? {},
+            sorting: debouncedPending?.sorting ?? initialState?.sorting ?? [],
+            columnPinning: debouncedPending?.columnPinning ?? initialState?.columnPinning ?? {},
+            expanded: debouncedPending?.expanded ?? initialState?.expanded ?? {},
+        };
+    }, [debouncedPending, initialState]);
+    const onTableStateChange = useCallback((newTableState) => {
+        if (!newTableState) {
+            return;
+        }
+        setPendingState(newTableState);
+    }, []);
+    useEffect(() => {
+        const stateChanged = Boolean(currentState) && !dequal(lastSavedRef.current, currentState);
+        if (!stateChanged || !currentState) {
+            return;
+        }
+        lastSavedRef.current = currentState;
+        localStorage.setItem(storageKey, JSON.stringify(currentState));
+        const encoded = encode(currentState);
+        void requestAnimationFrame(() => {
+            const url = new URL(window.location.href);
+            url.searchParams.set(persistenceKey, encoded);
+            if (url.href.length <= MAX_URL_LENGTH) {
+                window.history.replaceState(window.history.state, "", url.href);
+            }
+            else {
+                url.searchParams.delete(persistenceKey);
+                window.history.replaceState(window.history.state, "", url.href);
+            }
+        });
+    }, [currentState, storageKey, encode, persistenceKey]);
+    return useMemo(() => ({
+        onTableStateChange,
+        initialState,
+    }), [initialState, onTableStateChange]);
+};
+
 /*
  * ----------------------------
  * | SETUP TRANSLATIONS START |
@@ -501,4 +629,4 @@ const useColumnDefinitionsFromCustomFieldDefinition = ({ customFieldDefinitions,
  */
 setupLibraryTranslations();
 
-export { ExportTableButton, customFieldToCell, customFieldToExportString, useColumnDefinitionsFromCustomFieldDefinition };
+export { ExportTableButton, customFieldToCell, customFieldToExportString, isSortByProperty, useColumnDefinitionsFromCustomFieldDefinition, useTablePersistence };

package/package.json

@@ -1,27 +1,29 @@
 {
   "name": "@trackunit/react-table-helpers",
-  "version": "1.19.8",
+  "version": "1.19.9-alpha-58b6b568fca.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/date-and-time-utils": "1.11.80",
-    "@trackunit/filters-filter-bar": "1.18.7",
-    "@trackunit/filters-graphql-hook": "1.21.8",
-    "@trackunit/i18n-library-translation": "1.15.5",
-    "@trackunit/custom-field-components": "1.17.5",
-    "@trackunit/iris-app-runtime-core": "1.14.3",
-    "@trackunit/iris-app-runtime-core-api": "1.13.3",
-    "@trackunit/react-table-base-components": "1.17.5",
-    "@trackunit/react-table": "1.17.6",
-    "@trackunit/react-components": "1.20.5",
-    "@trackunit/react-core-hooks": "1.14.4",
-    "@trackunit/react-graphql-hooks": "1.18.5",
-    "@trackunit/iris-app-api": "1.15.10",
+    "@trackunit/date-and-time-utils": "1.11.81-alpha-58b6b568fca.0",
+    "@trackunit/filters-filter-bar": "1.18.8-alpha-58b6b568fca.0",
+    "@trackunit/filters-graphql-hook": "1.21.9-alpha-58b6b568fca.0",
+    "@trackunit/i18n-library-translation": "1.15.6-alpha-58b6b568fca.0",
+    "@trackunit/custom-field-components": "1.17.6-alpha-58b6b568fca.0",
+    "@trackunit/iris-app-runtime-core": "1.14.4-alpha-58b6b568fca.0",
+    "@trackunit/iris-app-runtime-core-api": "1.13.4-alpha-58b6b568fca.0",
+    "@trackunit/react-table-base-components": "1.17.6-alpha-58b6b568fca.0",
+    "@trackunit/react-table": "1.17.7-alpha-58b6b568fca.0",
+    "@trackunit/react-components": "1.20.6-alpha-58b6b568fca.0",
+    "@trackunit/react-core-hooks": "1.14.5-alpha-58b6b568fca.0",
+    "@trackunit/react-graphql-hooks": "1.18.6-alpha-58b6b568fca.0",
+    "@trackunit/iris-app-api": "1.15.11-alpha-58b6b568fca.0",
     "@graphql-codegen/cli": "^5.0.3",
-    "@graphql-typed-document-node/core": "^3.2.0"
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "dequal": "^2.0.3",
+    "zod": "^3.23.8"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/index.d.ts

@@ -3,3 +3,4 @@ export * from "./useColumnDefinitionsFromCustomFieldDefinition/customFieldToCell
 export * from "./useColumnDefinitionsFromCustomFieldDefinition/customFieldToExportString";
 export type { CustomFieldData, DataWithCustomFields } from "./useColumnDefinitionsFromCustomFieldDefinition/types";
 export * from "./useColumnDefinitionsFromCustomFieldDefinition/useColumnDefinitionsFromCustomFieldDefinition";
+export * from "./useTablePersistence/useTablePersistence";

package/src/useTablePersistence/useTablePersistence.d.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+/** Zod schema describing the persisted subset of table state (column order, sizing, visibility, sorting, pinning, and expanded). */
+declare const tableStateSchema: z.ZodObject<{
+    columnOrder: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    sorting: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        desc: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        desc: boolean;
+    }, {
+        id: string;
+        desc: boolean;
+    }>, "many">>;
+    columnVisibility: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+    columnSizing: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    columnPinning: z.ZodOptional<z.ZodObject<{
+        left: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        right: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        left?: string[] | undefined;
+        right?: string[] | undefined;
+    }, {
+        left?: string[] | undefined;
+        right?: string[] | undefined;
+    }>>;
+    expanded: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<true>, z.ZodRecord<z.ZodString, z.ZodBoolean>]>>;
+}, "strip", z.ZodTypeAny, {
+    columnOrder?: string[] | undefined;
+    sorting?: {
+        id: string;
+        desc: boolean;
+    }[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    columnSizing?: Record<string, number> | undefined;
+    columnPinning?: {
+        left?: string[] | undefined;
+        right?: string[] | undefined;
+    } | undefined;
+    expanded?: true | Record<string, boolean> | undefined;
+}, {
+    columnOrder?: string[] | undefined;
+    sorting?: {
+        id: string;
+        desc: boolean;
+    }[] | undefined;
+    columnVisibility?: Record<string, boolean> | undefined;
+    columnSizing?: Record<string, number> | undefined;
+    columnPinning?: {
+        left?: string[] | undefined;
+        right?: string[] | undefined;
+    } | undefined;
+    expanded?: true | Record<string, boolean> | undefined;
+}>;
+export type TableColumnOptions = z.infer<typeof tableStateSchema>;
+/**
+ * Type guard that checks whether a string is a recognised sorting property.
+ *
+ * @param sortingState - Array of valid sort property names.
+ * @param value - The value to check.
+ * @returns {boolean} `true` when {@link value} matches one of the entries in {@link sortingState}.
+ */
+export declare const isSortByProperty: <TSortByType extends string>(sortingState: Array<TSortByType>, value?: string) => value is TSortByType;
+type UseTablePersistenceResult = {
+    readonly onTableStateChange: (newTableState: Partial<TableColumnOptions> | null) => void;
+    readonly initialState: TableColumnOptions | undefined;
+};
+/**
+ * Persists and restores table column state (order, sizing, visibility, sorting, pinning, expanded) using
+ * URL search parameters and localStorage.
+ *
+ * On mount the state is loaded from the URL (if present) or from localStorage.
+ * Changes are debounced (300 ms) and synced to both the URL and localStorage.
+ *
+ * URL updates use `window.history.replaceState` directly rather than the application router,
+ * so table state changes never interfere with other URL-persisting hooks (e.g. filter bar).
+ *
+ * @param persistenceKey - Unique key used to store and retrieve the table state.
+ * @returns {UseTablePersistenceResult} An object containing:
+ *  - `onTableStateChange` — callback to invoke when the table state changes.
+ *  - `initialState` — the previously persisted {@link TableColumnOptions}, or `undefined` if none exists.
+ */
+export declare const useTablePersistence: (persistenceKey: string) => UseTablePersistenceResult;
+export {};