@webitel/ui-datalist 1.1.65 → 1.1.67

package/src/modules/persist/__tests__/useRoutePersistedStorage.spec.ts

@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createApp } from 'vue';
+import {
+	createMemoryHistory,
+	createRouter,
+	type Router,
+	useRoute,
+} from 'vue-router';
+
+import type { StorageLike } from '../PersistedStorage.types';
+import { useRoutePersistedStorage } from '../useRoutePersistedStorage';
+
+const routes = [
+	{
+		path: '/',
+		name: 'root',
+		component: {
+			template: '<div />',
+		},
+	},
+	{
+		path: '/cases/:id?',
+		name: 'cases',
+		component: {
+			template: '<div />',
+		},
+	},
+];
+
+describe('useRoutePersistedStorage', () => {
+	let router: Router;
+	let storage: StorageLike;
+	let currentQuery: () => Record<string, unknown>;
+
+	beforeEach(async () => {
+		router = createRouter({
+			history: createMemoryHistory(),
+			routes,
+		});
+
+		const app = createApp({});
+		app.use(router);
+
+		await router.push('/');
+		await router.isReady();
+
+		app.runWithContext(() => {
+			storage = useRoutePersistedStorage();
+			const route = useRoute();
+			currentQuery = () => route.query;
+		});
+	});
+
+	it('reads a value from the route query', async () => {
+		await router.push({
+			name: 'cases',
+			query: {
+				page: '3',
+			},
+		});
+
+		expect(await storage.getItem('page')).toBe('3');
+	});
+
+	it('resolves undefined for a missing query param', async () => {
+		expect(await storage.getItem('page')).toBeUndefined();
+	});
+
+	it('writes a value keeping the rest of the query', async () => {
+		await router.push({
+			name: 'cases',
+			query: {
+				filters: '{"name":"test"}',
+			},
+		});
+
+		await storage.setItem('page', '3');
+
+		expect(currentQuery()).toEqual({
+			filters: '{"name":"test"}',
+			page: '3',
+		});
+	});
+
+	it('writes without leaving the current route', async () => {
+		await router.push({
+			name: 'cases',
+			params: {
+				id: '42',
+			},
+			hash: '#tab',
+		});
+
+		await storage.setItem('page', '3');
+
+		expect(router.currentRoute.value.name).toBe('cases');
+		expect(router.currentRoute.value.params.id).toBe('42');
+		expect(router.currentRoute.value.hash).toBe('#tab');
+	});
+
+	it('does not add a history entry', async () => {
+		await router.push({
+			name: 'cases',
+		});
+		const positionBefore = window.history.length;
+
+		await storage.setItem('page', '3');
+
+		expect(window.history.length).toBe(positionBefore);
+	});
+
+	it('keeps every key when writes are issued concurrently', async () => {
+		await router.push({
+			name: 'cases',
+		});
+
+		await Promise.all([
+			storage.setItem('page', '3'),
+			storage.setItem('sort', '-createdAt'),
+			storage.setItem('fields', 'name,subject'),
+		]);
+
+		expect(currentQuery()).toEqual({
+			page: '3',
+			sort: '-createdAt',
+			fields: 'name,subject',
+		});
+	});
+
+	it('removes a value keeping the rest of the query', async () => {
+		await router.push({
+			name: 'cases',
+			query: {
+				page: '3',
+				size: '20',
+			},
+		});
+
+		await storage.removeItem('page');
+
+		expect(currentQuery()).toEqual({
+			size: '20',
+		});
+	});
+});

package/src/modules/persist/usePersistedStorage.ts

@@ -1,15 +1,21 @@
+import { isEmpty } from '@webitel/ui-sdk/scripts';
 import { type WatchHandle, watch } from 'vue';
 
 import {
 	type PersistableValue,
 	type PersistedPropertyConfig,
+	type PersistedStorageAdapter,
 	type PersistedStorageController,
 	PersistedStorageType,
-	type StorageLike,
+	type PersistStorableValue,
 } from './PersistedStorage.types';
 import { useLocalStoragePersistedStorage } from './useLocalStoragePersistedStorage';
 import { useRoutePersistedStorage } from './useRoutePersistedStorage';
 
+const toStorableValue = (value: PersistableValue): PersistStorableValue => {
+	return typeof value === 'string' ? value : (value?.toString() ?? '');
+};
+
 export const usePersistedStorage = ({
 	name,
 	value,
@@ -22,10 +28,9 @@ export const usePersistedStorage = ({
 	onRestore,
 }: PersistedPropertyConfig): PersistedStorageController => {
 	let unwatch: WatchHandle | null = null;
+	let defaultSnapshot: PersistStorableValue | undefined;
 
-	const setItemFns: StorageLike['setItem'][] = [];
-	const getItemFns: StorageLike['getItem'][] = [];
-	const removeItemFns: StorageLike['removeItem'][] = [];
+	const adapters: PersistedStorageAdapter[] = [];
 
 	// `null` entries are kept: callers below pick the first non-null value, so the
 	// per-storage misses have to stay in the list to preserve priority order.
@@ -33,7 +38,7 @@ export const usePersistedStorage = ({
 		name: string,
 	): Promise<Array<PersistableValue | null>> => {
 		const settledResults = await Promise.allSettled(
-			getItemFns.map((getter) => getter(name)),
+			adapters.map(({ getItem }) => getItem(name)),
 		);
 
 		return settledResults.reduce(
@@ -57,58 +62,67 @@ export const usePersistedStorage = ({
   order matters, as the first storage in the list has the highest priority
    */
 	if (storages.includes(PersistedStorageType.Route)) {
-		const { setItem, getItem, removeItem } = useRoutePersistedStorage();
-		setItemFns.push(setItem);
-		getItemFns.push(getItem);
-		removeItemFns.push(removeItem);
+		adapters.push({
+			type: PersistedStorageType.Route,
+			...useRoutePersistedStorage(),
+		});
 	}
 
 	if (storages.includes(PersistedStorageType.LocalStorage)) {
-		const { setItem, getItem, removeItem } = useLocalStoragePersistedStorage({
-			storagePath,
+		adapters.push({
+			type: PersistedStorageType.LocalStorage,
+			...useLocalStoragePersistedStorage({
+				storagePath,
+			}),
 		});
-		setItemFns.push(setItem);
-		getItemFns.push(getItem);
-		removeItemFns.push(removeItem);
 	}
 
+	/*
+   runs the storing path with a `save` doing whatever the caller needs:
+    writing to the storages, or merely capturing the serialized value
+   */
+	const runStoringPath = async (
+		save: (params: { name: string; value: PersistableValue }) => Promise<void>,
+	) => {
+		if (onStore) {
+			/* save is wrapped in one callback, so that onStore is called only once */
+			return onStore(save, {
+				name,
+				value: value.value ?? '',
+			});
+		}
+
+		return save({
+			name,
+			value: value.value ?? '',
+		});
+	};
+
+	const serialize = async () => {
+		let serializedValue: PersistStorableValue = '';
+
+		await runStoringPath(async ({ value: storedValue }) => {
+			serializedValue = toStorableValue(storedValue);
+		});
+
+		return serializedValue;
+	};
+
+	const store = (targets: PersistedStorageAdapter[]) => {
+		if (!targets.length) return Promise.resolve();
+
+		return runStoringPath(async ({ name, value: storedValue }) => {
+			await Promise.all(
+				targets.map((adapter) => adapter.setItem(name, storedValue)),
+			);
+		});
+	};
+
 	const startWatch = () => {
 		unwatch = watch(
 			value,
-			async () => {
-				/*
-       if onStore callback is provided,
-        call custom logic for storing value
-       */
-				if (onStore) {
-					/*
-         wrap all setItemFns in one callback
-          so that onStore is called only once on each value change
-         */
-					const save = async ({
-						name,
-						value: storedValue,
-					}: {
-						name: string;
-						value: PersistableValue;
-					}) => {
-						setItemFns.forEach((setter) => {
-							setter(name, storedValue);
-						});
-					};
-					await onStore(save, {
-						name,
-						value: value.value ?? '',
-					});
-				} else {
-					/*
-       else, perform default storing logic
-       */
-					const storedValue = value.value ?? '';
-					setItemFns.forEach((setter) => {
-						setter(name, storedValue);
-					});
-				}
+			() => {
+				store(adapters);
 			},
 			{
 				deep: true,
@@ -118,14 +132,13 @@ export const usePersistedStorage = ({
 
 	const restore = async () => {
 		/*
-       if onRestore callback is provided,
-        call custom logic for restoring value
-       */
+     nothing has mutated the value yet, so this is what a freshly created store
+      serializes – sync() uses it to tell untouched state from a real one
+     */
+		defaultSnapshot = await serialize();
+
 		if (onRestore) {
-			/*
-         wrap all getItemFns in one callback
-          so that onRestore is called only once on each value change
-         */
+			/* every getter is wrapped in one callback, so that onRestore is called only once */
 			const restore = async (name: string) => {
 				const restoredValues = await composedValueGetter(name);
 				/*
@@ -138,13 +151,15 @@ export const usePersistedStorage = ({
 			};
 			await onRestore(restore, name);
 		} else {
+			const restoredValues = await composedValueGetter(name);
 			/*
-       else, perform default restoring logic
+       loose check on purpose: useRoutePersistedStorage resolves `undefined`
+        for a missing query param, so a storage listed after the route one
+        would never win with a strict `!== null`
        */
-			const restoredValues = await composedValueGetter(name);
-			const restoredValue = restoredValues.find((value) => value !== null);
+			const restoredValue = restoredValues.find((value) => value != null);
 
-			if (restoredValue !== undefined) {
+			if (restoredValue != null) {
 				value.value = restoredValue;
 			}
 		}
@@ -157,8 +172,25 @@ export const usePersistedStorage = ({
 		}
 	};
 
+	const sync = async () => {
+		const serializedValue = await serialize();
+
+		if (isEmpty(serializedValue) || serializedValue === defaultSnapshot) return;
+
+		const settledResults = await Promise.allSettled(
+			adapters.map(({ getItem }) => getItem(name)),
+		);
+
+		const emptyStorages = adapters.filter((_, index) => {
+			const result = settledResults[index];
+			return result.status === 'fulfilled' && result.value == null;
+		});
+
+		return store(emptyStorages);
+	};
+
 	const reset = async () => {
-		await Promise.all(removeItemFns.map((removeItem) => removeItem(name)));
+		await Promise.all(adapters.map(({ removeItem }) => removeItem(name)));
 	};
 
 	const endWatch = () => unwatch?.();
@@ -167,6 +199,7 @@ export const usePersistedStorage = ({
 		watch: startWatch,
 		unwatch: endWatch,
 		restore,
+		sync,
 		reset,
 	};
 };

package/src/modules/persist/useRoutePersistedStorage.ts

@@ -2,6 +2,23 @@ import { useRoute, useRouter } from 'vue-router';
 
 import type { StorageLike } from './PersistedStorage.types.ts';
 
+/*
+ every write is a router.replace() built on top of the current query, and the
+  query only changes once the navigation resolves – so concurrent writes would
+  all start from the same snapshot and drop each other's keys. they are queued
+  process-wide: a table store writes several properties at once (a new sort
+  makes both `sort` and `fields` emit), and all of them target the same router
+ */
+let pendingWrite: Promise<unknown> = Promise.resolve();
+
+const enqueueWrite = <T>(write: () => Promise<T>): Promise<T> => {
+	const result = pendingWrite.then(write, write);
+
+	pendingWrite = result.catch(() => {});
+
+	return result;
+};
+
 export const useRoutePersistedStorage = (): StorageLike => {
 	const router = useRouter();
 	const route = useRoute();
@@ -11,27 +28,32 @@ export const useRoutePersistedStorage = (): StorageLike => {
 	};
 
 	const setItem = async (key: string, value: string | string[]) => {
-		await router.replace({
-			name: route.name,
-			params: route.params,
-			hash: route.hash,
-			query: {
-				...route.query,
-				[key]: value,
-			},
-		});
+		await enqueueWrite(() =>
+			router.replace({
+				name: route.name,
+				params: route.params,
+				hash: route.hash,
+				query: {
+					...route.query,
+					[key]: value,
+				},
+			}),
+		);
 	};
 
 	const removeItem = async (key: string) => {
-		const query = {
-			...route.query,
-		};
-		delete query[key];
-		await router.replace({
-			name: route.name,
-			params: route.params,
-			hash: route.hash,
-			query,
+		await enqueueWrite(() => {
+			const query = {
+				...route.query,
+			};
+			delete query[key];
+
+			return router.replace({
+				name: route.name,
+				params: route.params,
+				hash: route.hash,
+				query,
+			});
 		});
 	};
 

package/src/modules/table/createTableStore.store.ts

@@ -46,6 +46,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 		// $reset: $resetPaginationStore,
 		$patch: $patchPaginationStore,
 		setupPersistence: setupPaginationPersistence,
+		syncPersistence: syncPaginationPersistence,
 	} = paginationStore;
 
 	const headersStore = useHeadersStore();
@@ -63,6 +64,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 		columnReorder,
 		updateShownHeaders,
 		setupPersistence: setupHeadersPersistence,
+		syncPersistence: syncHeadersPersistence,
 	} = headersStore;
 
 	const filtersStore = useFiltersStore();
@@ -77,6 +79,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 		updateFilter,
 		deleteFilter,
 		setupPersistence: setupFiltersPersistence,
+		syncPersistence: syncFiltersPersistence,
 		updateSearchMode,
 	} = filtersStore;
 
@@ -285,6 +288,25 @@ export const tableStoreBody = <Entity extends Identifiable>(
 		isStoreSetUp.value = true;
 	};
 
+	/**
+	 * @description
+	 * Republishes the current store state into the storages that hold nothing
+	 * for it – in practice, into the route query.
+	 *
+	 * Persistence is restored only once per app lifetime (see `setupStore`),
+	 * and afterwards the query is written by watchers only, i.e. on change.
+	 * So a registry re-opened with state still in memory (closing a card back to
+	 * it, or reaching it from the menu) used to render filtered data behind a
+	 * bare url, losing filters on reload or on copying the link.
+	 *
+	 * [WTEL-10093](https://webitel.atlassian.net/browse/WTEL-10093)
+	 */
+	const syncPersistence = async () => {
+		await syncPaginationPersistence();
+		await syncFiltersPersistence();
+		await syncHeadersPersistence();
+	};
+
 	const initialize = async ({
 		parentId: storeParentId,
 	}: {
@@ -294,8 +316,22 @@ export const tableStoreBody = <Entity extends Identifiable>(
 			parentId.value = storeParentId;
 		}
 
+		const isStoreAlreadySetUp = isStoreSetUp.value;
+
 		await setupStore();
 
+		/*
+     on the first setup the restore path is authoritative.
+
+     a store initialized with a parentId is a list nested in a card page, not a
+      registry: it shares the query param names with the registry stores, and
+      the url it would publish into is the card one – so it keeps writing on
+      change only, and syncs merely on demand
+     */
+		if (isStoreAlreadySetUp && !disablePersistence && !storeParentId) {
+			await syncPersistence();
+		}
+
 		return loadDataList();
 	};
 
@@ -329,6 +365,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 
 		setupStore, // only setup, no data loading
 		initialize, // setup + load data
+		syncPersistence, // republish store state into the route query
 
 		loadDataList,
 		appendToDataList,