@webitel/ui-datalist 1.1.65 → 1.1.67

package/src/modules/pagination/__tests__/createTablePaginationStore.spec.ts

@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { createApp } from 'vue';
+import { createMemoryHistory, createRouter, type Router } from 'vue-router';
+
+import { tablePaginationStoreBody } from '../createTablePaginationStore';
+
+const routes = [
+	{
+		path: '/cases',
+		name: 'cases',
+		component: {
+			template: '<div />',
+		},
+	},
+];
+
+describe('tablePaginationStoreBody', () => {
+	let router: Router;
+	let runWithRouter: <T>(fn: () => T) => T;
+
+	beforeEach(async () => {
+		router = createRouter({
+			history: createMemoryHistory(),
+			routes,
+		});
+
+		const app = createApp({});
+		app.use(router);
+
+		await router.push('/cases');
+		await router.isReady();
+
+		runWithRouter = (fn) => app.runWithContext(fn);
+	});
+
+	const setUpStore = async () => {
+		const store = tablePaginationStoreBody();
+		await runWithRouter(() => store.setupPersistence());
+		return store;
+	};
+
+	it('starts on the first page with the default size', () => {
+		const store = tablePaginationStoreBody();
+
+		expect(store.page.value).toBe(1);
+		expect(store.size.value).toBe(10);
+	});
+
+	it('updates page and size', () => {
+		const store = tablePaginationStoreBody();
+
+		store.updatePage(3);
+		store.updateSize(20);
+
+		expect(store.page.value).toBe(3);
+		expect(store.size.value).toBe(20);
+	});
+
+	it('resets to the defaults', () => {
+		const store = tablePaginationStoreBody();
+		store.updatePage(3);
+		store.updateSize(20);
+		store.next.value = true;
+
+		store.$reset();
+
+		expect(store.page.value).toBe(1);
+		expect(store.size.value).toBe(10);
+		expect(store.next.value).toBe(false);
+	});
+
+	describe('persistence', () => {
+		it('restores page and size from the route query', async () => {
+			await router.push({
+				name: 'cases',
+				query: {
+					page: '3',
+					size: '20',
+				},
+			});
+
+			const store = await setUpStore();
+
+			expect(store.page.value).toBe(3);
+			expect(store.size.value).toBe(20);
+		});
+
+		it('writes a changed page into the route query', async () => {
+			const store = await setUpStore();
+
+			store.updatePage(3);
+			await new Promise((resolve) => setTimeout(resolve));
+
+			expect(router.currentRoute.value.query.page).toBe('3');
+		});
+	});
+
+	describe('syncPersistence', () => {
+		it('publishes state the user changed', async () => {
+			const store = await setUpStore();
+			store.updatePage(3);
+			await router.push('/cases');
+
+			await runWithRouter(() => store.syncPersistence());
+
+			expect(router.currentRoute.value.query.page).toBe('3');
+		});
+
+		it('publishes nothing while the state is still default', async () => {
+			const store = await setUpStore();
+
+			await runWithRouter(() => store.syncPersistence());
+
+			expect(router.currentRoute.value.query).toEqual({});
+		});
+
+		it('does not overwrite a value already in the query', async () => {
+			const store = await setUpStore();
+			store.updatePage(3);
+			/* let the watcher settle, so its write cannot land after the push below */
+			await new Promise((resolve) => setTimeout(resolve));
+			await router.push({
+				name: 'cases',
+				query: {
+					page: '5',
+				},
+			});
+
+			await runWithRouter(() => store.syncPersistence());
+
+			expect(router.currentRoute.value.query.page).toBe('5');
+		});
+	});
+});

package/src/modules/pagination/createTablePaginationStore.ts

@@ -1,6 +1,7 @@
 import { ref } from 'vue';
 
 import { createDatalistStore } from '../_shared/createDatalistStore';
+import type { PersistedStorageController } from '../persist/PersistedStorage.types';
 import { usePersistedStorage } from '../persist/usePersistedStorage';
 import type { Identifiable } from '../types/createDatalistStore.types';
 import type { useTableStoreConfig } from '../types/tableStore.types';
@@ -24,10 +25,18 @@ export const tablePaginationStoreBody = () => {
 		next.value = false;
 	};
 
+	let persistedStorageControllers: PersistedStorageController[] = [];
+
 	const setupPersistence = () => {
-		const { restore: restorePage } = usePersistedStorage({
+		const pageStorage = usePersistedStorage({
 			name: 'page',
 			value: page,
+			onStore: (save, { name }) => {
+				return save({
+					name,
+					value: `${page.value}`,
+				});
+			},
 			onRestore: async (restore, name) => {
 				const value = await restore(name);
 				const numValue = Number(value);
@@ -35,9 +44,15 @@ export const tablePaginationStoreBody = () => {
 			},
 		});
 
-		const { restore: restoreSize } = usePersistedStorage({
+		const sizeStorage = usePersistedStorage({
 			name: 'size',
 			value: size,
+			onStore: (save, { name }) => {
+				return save({
+					name,
+					value: `${size.value}`,
+				});
+			},
 			onRestore: async (restore, name) => {
 				const value = await restore(name);
 				const numValue = Number(value);
@@ -45,12 +60,24 @@ export const tablePaginationStoreBody = () => {
 			},
 		});
 
+		persistedStorageControllers = [
+			pageStorage,
+			sizeStorage,
+		];
+
 		return Promise.allSettled([
-			restorePage(),
-			restoreSize(),
+			pageStorage.restore(),
+			sizeStorage.restore(),
 		]);
 	};
 
+	/* sequentially: every route write is a router.replace() on top of the current query */
+	const syncPersistence = async () => {
+		for (const controller of persistedStorageControllers) {
+			await controller.sync();
+		}
+	};
+
 	return {
 		page,
 		size,
@@ -60,6 +87,7 @@ export const tablePaginationStoreBody = () => {
 		updateSize,
 
 		setupPersistence,
+		syncPersistence,
 		$reset,
 	};
 };

package/src/modules/persist/PersistedStorage.types.ts

@@ -22,6 +22,10 @@ export interface StorageLike {
 	removeItem(key: string): Promise<void>;
 }
 
+export interface PersistedStorageAdapter extends StorageLike {
+	type: PersistedStorageType;
+}
+
 export interface PersistedPropertyConfig {
 	name: string;
 	// note: createTableHeadersStore passes a computed here, which the default
@@ -55,5 +59,15 @@ export interface PersistedStorageController {
 	watch: () => void;
 	unwatch: () => void;
 	restore: () => Promise<void>;
+	/**
+	 * Publishes the current value to every storage that holds nothing for `name`.
+	 * Storages that already hold a value are left untouched, so an explicit route
+	 * query always wins over in-memory state.
+	 *
+	 * A no-op for state still equal to the defaults: `restore()` captures the
+	 * snapshot a freshly created store serializes, and a controller that never
+	 * restored can only tell empty values apart.
+	 */
+	sync: () => Promise<void>;
 	reset: () => Promise<void>;
 }

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

@@ -0,0 +1,66 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { useLocalStoragePersistedStorage } from '../useLocalStoragePersistedStorage';
+
+describe('useLocalStoragePersistedStorage', () => {
+	beforeEach(() => {
+		localStorage.clear();
+	});
+
+	it('namespaces keys with the storagePath', async () => {
+		const storage = useLocalStoragePersistedStorage({
+			storagePath: 'cases/headers',
+		});
+
+		await storage.setItem('fields', 'name,subject');
+
+		expect(localStorage.getItem('cases/headers/fields')).toBe('name,subject');
+	});
+
+	it('keeps stores with different paths apart', async () => {
+		const cases = useLocalStoragePersistedStorage({
+			storagePath: 'cases',
+		});
+		const contacts = useLocalStoragePersistedStorage({
+			storagePath: 'contacts',
+		});
+
+		await cases.setItem('fields', 'subject');
+		await contacts.setItem('fields', 'name');
+
+		expect(await cases.getItem('fields')).toBe('subject');
+		expect(await contacts.getItem('fields')).toBe('name');
+	});
+
+	it('resolves null for a missing key', async () => {
+		const storage = useLocalStoragePersistedStorage({
+			storagePath: 'cases',
+		});
+
+		expect(await storage.getItem('fields')).toBeNull();
+	});
+
+	it('stores an array as a comma-joined value', async () => {
+		const storage = useLocalStoragePersistedStorage({
+			storagePath: 'cases',
+		});
+
+		await storage.setItem('fields', [
+			'name',
+			'subject',
+		]);
+
+		expect(await storage.getItem('fields')).toBe('name,subject');
+	});
+
+	it('removes a key', async () => {
+		const storage = useLocalStoragePersistedStorage({
+			storagePath: 'cases',
+		});
+		await storage.setItem('fields', 'name');
+
+		await storage.removeItem('fields');
+
+		expect(await storage.getItem('fields')).toBeNull();
+	});
+});

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

@@ -0,0 +1,357 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { nextTick, type Ref, ref } from 'vue';
+
+import {
+	type PersistableValue,
+	PersistedStorageType,
+	type StorageLike,
+} from '../PersistedStorage.types';
+
+const createStorageMock = (): StorageLike & {
+	value: string | null;
+} => {
+	const storage = {
+		value: null as string | null,
+		getItem: vi.fn(async () => storage.value),
+		setItem: vi.fn(async (_key: string, value: string) => {
+			storage.value = value;
+		}),
+		removeItem: vi.fn(async () => {
+			storage.value = null;
+		}),
+	};
+
+	return storage;
+};
+
+const routeStorage = createStorageMock();
+const localStorage = createStorageMock();
+
+/*
+ route storage resolves `undefined` for a missing query param,
+  local storage resolves `null` – both are mocked to keep that difference
+ */
+vi.mock('../useRoutePersistedStorage', () => ({
+	useRoutePersistedStorage: () => ({
+		getItem: (key: string) =>
+			routeStorage.getItem(key).then((value) => value ?? undefined),
+		setItem: routeStorage.setItem,
+		removeItem: routeStorage.removeItem,
+	}),
+}));
+
+vi.mock('../useLocalStoragePersistedStorage', () => ({
+	useLocalStoragePersistedStorage: () => localStorage,
+}));
+
+const { usePersistedStorage } = await import('../usePersistedStorage');
+
+describe('usePersistedStorage', () => {
+	beforeEach(() => {
+		routeStorage.value = null;
+		localStorage.value = null;
+		vi.clearAllMocks();
+	});
+
+	describe('sync', () => {
+		it('publishes the current value to an empty storage', async () => {
+			const value = ref('filtered');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+			}).sync();
+
+			expect(routeStorage.setItem).toHaveBeenCalledWith('filters', 'filtered');
+			expect(routeStorage.value).toBe('filtered');
+		});
+
+		it('does not overwrite a storage that already holds a value', async () => {
+			routeStorage.value = 'from-url';
+			const value = ref('from-memory');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+			}).sync();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+			expect(routeStorage.value).toBe('from-url');
+		});
+
+		it('publishes only to the storages that hold nothing', async () => {
+			localStorage.value = 'from-local-storage';
+			const value = ref('from-memory');
+
+			await usePersistedStorage({
+				name: 'fields',
+				value,
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+			}).sync();
+
+			expect(routeStorage.value).toBe('from-memory');
+			expect(localStorage.setItem).not.toHaveBeenCalled();
+			expect(localStorage.value).toBe('from-local-storage');
+		});
+
+		it('skips empty values', async () => {
+			const value = ref('');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+			}).sync();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+			expect(routeStorage.value).toBeNull();
+		});
+
+		it('skips a value still equal to the default captured by restore', async () => {
+			const value = ref('default-page');
+
+			const storage = usePersistedStorage({
+				name: 'page',
+				value,
+			});
+			await storage.restore();
+			await storage.sync();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+			expect(routeStorage.value).toBeNull();
+		});
+
+		it('publishes a value changed after restore', async () => {
+			const value = ref('default-page');
+
+			const storage = usePersistedStorage({
+				name: 'page',
+				value,
+			});
+			await storage.restore();
+			storage.unwatch();
+			value.value = '3';
+			await storage.sync();
+
+			expect(routeStorage.value).toBe('3');
+		});
+
+		it('captures the default through onStore serialization', async () => {
+			const filters = ref<Record<string, string>>({});
+
+			const storage = usePersistedStorage({
+				name: 'filters',
+				value: filters as unknown as Ref<PersistableValue>,
+				onStore: (save, { name }) =>
+					save({
+						name,
+						value: JSON.stringify(filters.value),
+					}),
+			});
+			await storage.restore();
+			storage.unwatch();
+
+			/* an empty snapshot serializes to "{}" – the default, nothing to publish */
+			await storage.sync();
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+
+			filters.value = {
+				name: 'test',
+			};
+			await storage.sync();
+			expect(routeStorage.value).toBe('{"name":"test"}');
+		});
+
+		it('skips empty values when restore never ran', async () => {
+			const value = ref('');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+			}).sync();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+		});
+
+		it('stores value serialized by onStore', async () => {
+			const value = ref('ignored-raw-value');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+				onStore: (save, { name }) =>
+					save({
+						name,
+						value: 'serialized',
+					}),
+			}).sync();
+
+			expect(routeStorage.value).toBe('serialized');
+		});
+
+		it('does not start watching the value', async () => {
+			const value = ref('filtered');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+			}).sync();
+
+			vi.clearAllMocks();
+			value.value = 'changed';
+			await new Promise((resolve) => setTimeout(resolve));
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('restore', () => {
+		it('falls back to the next storage when the route holds nothing', async () => {
+			localStorage.value = 'from-local-storage';
+			const value = ref('');
+
+			await usePersistedStorage({
+				name: 'fields',
+				value,
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+			}).restore();
+
+			expect(value.value).toBe('from-local-storage');
+		});
+
+		it('prefers the route value over the next storages', async () => {
+			routeStorage.value = 'from-url';
+			localStorage.value = 'from-local-storage';
+			const value = ref('');
+
+			await usePersistedStorage({
+				name: 'fields',
+				value,
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+			}).restore();
+
+			expect(value.value).toBe('from-url');
+		});
+
+		it('leaves the value untouched when no storage holds anything', async () => {
+			const value = ref('in-memory');
+
+			await usePersistedStorage({
+				name: 'fields',
+				value,
+			}).restore();
+
+			expect(value.value).toBe('in-memory');
+		});
+
+		it('hands the first non-null value to onRestore', async () => {
+			localStorage.value = 'from-local-storage';
+			const onRestore = vi.fn();
+
+			await usePersistedStorage({
+				name: 'fields',
+				value: ref(''),
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+				onRestore: async (restore, name) => {
+					onRestore(await restore(name));
+				},
+			}).restore();
+
+			expect(onRestore).toHaveBeenCalledWith('from-local-storage');
+		});
+	});
+
+	describe('watch', () => {
+		it('writes a changed value to every storage', async () => {
+			const value = ref('initial');
+
+			await usePersistedStorage({
+				name: 'fields',
+				value,
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+			}).restore();
+
+			value.value = 'changed';
+			await nextTick();
+
+			expect(routeStorage.value).toBe('changed');
+			expect(localStorage.value).toBe('changed');
+		});
+
+		it('does not write the value restored from a storage back', async () => {
+			routeStorage.value = 'from-url';
+
+			await usePersistedStorage({
+				name: 'filters',
+				value: ref(''),
+			}).restore();
+			await nextTick();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+		});
+
+		it('does not start watching when startWatchManually is set', async () => {
+			const value = ref('initial');
+
+			await usePersistedStorage({
+				name: 'filters',
+				value,
+				startWatchManually: true,
+			}).restore();
+
+			value.value = 'changed';
+			await nextTick();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+		});
+
+		it('stops writing after unwatch', async () => {
+			const value = ref('initial');
+
+			const storage = usePersistedStorage({
+				name: 'filters',
+				value,
+			});
+			await storage.restore();
+			storage.unwatch();
+
+			value.value = 'changed';
+			await nextTick();
+
+			expect(routeStorage.setItem).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('reset', () => {
+		it('removes the value from every storage', async () => {
+			routeStorage.value = 'from-url';
+			localStorage.value = 'from-local-storage';
+
+			await usePersistedStorage({
+				name: 'fields',
+				value: ref('in-memory'),
+				storages: [
+					PersistedStorageType.Route,
+					PersistedStorageType.LocalStorage,
+				],
+			}).reset();
+
+			expect(routeStorage.value).toBeNull();
+			expect(localStorage.value).toBeNull();
+		});
+	});
+});