@webitel/ui-datalist 26.8.4 → 26.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webitel/ui-datalist",
-	"version": "26.8.4",
+	"version": "26.8.6",
 	"description": "Toolkit for building data lists in webitel ui system",
 	"scripts": {
 		"build:types": "vue-tsc -b tsconfig.build.json",

package/src/index.ts

@@ -1,5 +1,6 @@
+import { useNestedTableList } from './modules/table/composables/useNestedTableList';
 import { createTableStore } from './modules/table/createTableStore.store';
 import type { DatalistTableHeader } from './modules/types/tableStore.types';
 
 export type { DatalistTableHeader };
-export { createTableStore };
+export { createTableStore, useNestedTableList };

package/src/modules/card/composables/useCardComponent.ts

@@ -7,6 +7,10 @@ import { useCardAnyFieldEditedWatcher } from './useCardAnyFieldEditedWatcher';
 import { useCardIsNew } from './useCardIsNew';
 import { useCardRouting } from './useCardRouting';
 import { useCardSaveAction } from './useCardSaveAction';
+import {
+	type NestedListsOwner,
+	provideCardStore,
+} from './useCardStoreProvider';
 import { useCardValidation } from './useCardValidation';
 import { useItemCardSaveText } from './useItemCardSaveText';
 
@@ -31,6 +35,11 @@ export const useCardComponent = <
 }) => {
 	const cardStore = useCardStore();
 
+	// the nested tabs register their lists here, and the card empties them.
+	// `useCardStore` is a bare StoreDefinition, as everywhere else in here, so
+	// the store's own shape has to be asserted rather than inferred
+	provideCardStore(cardStore as unknown as NestedListsOwner);
+
 	const {
 		itemId,
 		originalItemInstance,

package/src/modules/card/composables/useCardStoreProvider.ts

@@ -0,0 +1,26 @@
+import { type InjectionKey, inject, provide } from 'vue';
+
+import type { CardItemId, NestedList } from '../types/CardStore.types';
+
+/**
+ * What a nested tab needs from the card page it lives in: the record it is a
+ * tab of, and somewhere to register its list so the card can empty it.
+ */
+export interface NestedListsOwner {
+	itemId: CardItemId;
+	registerNestedList: (list: NestedList) => void;
+}
+
+export const CardStoreKey: InjectionKey<NestedListsOwner> =
+	Symbol('datalistCardStore');
+
+/**
+ * `useCardComponent` provides the card's own store, so the tabs below it need
+ * no wiring of their own — see `useNestedTableList`.
+ */
+export const provideCardStore = (store: NestedListsOwner) => {
+	provide(CardStoreKey, store);
+};
+
+/** `null` outside a card page, where a list has no owner to reset it */
+export const useInjectedCardStore = () => inject(CardStoreKey, null);

package/src/modules/card/index.ts

@@ -1,6 +1,7 @@
 export * from './composables/useCardAnyFieldEditedWatcher';
 export * from './composables/useCardComponent';
 export * from './composables/useCardListNavigation';
+export * from './composables/useCardStoreProvider';
 export * from './composables/useCardTabs';
 export * from './composables/useNestedCardComponent';
 export * from './stores/createCardStore';

package/src/modules/card/stores/__tests__/createCardStore.spec.ts

@@ -0,0 +1,73 @@
+import { createPinia, setActivePinia } from 'pinia';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod/v4';
+
+import { createCardStore } from '../createCardStore';
+
+const cardStoreOf = (namespace: string) =>
+	createCardStore({
+		namespace,
+		apiModule: {
+			get: vi.fn(),
+			add: vi.fn(),
+			update: vi.fn(),
+		},
+		standardValidationSchema: z.object({
+			name: z.string().optional(),
+		}),
+	});
+
+/*
+ The lists of a card's nested tabs live in stores shared by every card of their
+ kind, so the card that filled them is the one that has to empty them.
+
+ [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+ */
+describe('createCardStore nested lists', () => {
+	beforeEach(() => {
+		setActivePinia(createPinia());
+	});
+
+	it('empties every registered list on reset', () => {
+		const store = cardStoreOf('cases/card')();
+		const lists = [
+			{
+				$reset: vi.fn(),
+			},
+			{
+				$reset: vi.fn(),
+			},
+		];
+
+		for (const list of lists) store.registerNestedList(list);
+		store.$reset();
+
+		for (const list of lists) expect(list.$reset).toHaveBeenCalledOnce();
+	});
+
+	it('forgets them, so the next card resets only its own', () => {
+		const store = cardStoreOf('contacts/card')();
+		const list = {
+			$reset: vi.fn(),
+		};
+
+		store.registerNestedList(list);
+		store.$reset();
+		store.$reset();
+
+		expect(list.$reset).toHaveBeenCalledOnce();
+	});
+
+	it('registers a list once, however many times its tab is mounted', () => {
+		const store = cardStoreOf('queues/card')();
+		const list = {
+			$reset: vi.fn(),
+		};
+
+		store.registerNestedList(list);
+		store.registerNestedList(list);
+		store.$reset();
+
+		expect(list.$reset).toHaveBeenCalledOnce();
+	});
+});

package/src/modules/card/stores/createCardStore.ts

@@ -10,7 +10,11 @@ import type { MaybeRef } from 'vue';
 import { effectScope, ref, toRaw, toValue, watch } from 'vue';
 import type { z } from 'zod/v4';
 
-import type { CardItemId, CardParentId } from '../types/CardStore.types';
+import type {
+	CardItemId,
+	CardParentId,
+	NestedList,
+} from '../types/CardStore.types';
 
 const defaultRegleValidationOptions: RegleSchemaBehaviourOptions &
 	RegleBehaviourOptions = {
@@ -167,6 +171,19 @@ export const createCardStore = <
 			}
 		};
 
+		/**
+		 * The lists of the card's nested tabs. They live in stores of their own,
+		 * shared by every card of this kind and outliving all of them, so the card
+		 * that filled them is the one that has to empty them.
+		 *
+		 * [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+		 */
+		const nestedLists = new Set<NestedList>();
+
+		const registerNestedList = (list: NestedList) => {
+			nestedLists.add(list);
+		};
+
 		const initialize = ({
 			itemId: initialItemId,
 			parentId: initialParentId,
@@ -186,6 +203,9 @@ export const createCardStore = <
 		};
 
 		const $reset = () => {
+			for (const list of nestedLists) list.$reset();
+			nestedLists.clear();
+
 			itemId.value = null;
 			parentId.value = null;
 			createValidationSchema();
@@ -212,6 +232,7 @@ export const createCardStore = <
 			initialize,
 			saveItem,
 			$reset,
+			registerNestedList,
 		};
 	});
 };

package/src/modules/card/types/CardStore.types.ts

@@ -1,2 +1,10 @@
 export type CardItemId = string | number | null;
 export type CardParentId = CardItemId;
+
+/**
+ * What a card store needs from the list of one of its nested tabs: the ability
+ * to empty it when the card page goes away.
+ */
+export interface NestedList {
+	$reset: () => void;
+}

package/src/modules/table/__tests__/createTableStore.spec.ts

@@ -183,4 +183,80 @@ describe('tableStoreBody', () => {
 			expect(getList).toHaveBeenCalled();
 		});
 	});
+	/*
+   A nested list is emptied by the card store it is registered with, and until
+   it has a parent again it must not load: the store keeps the parent it was
+   initialized with, so a reload in between queried the previous card's record.
+
+   [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+  */
+	describe('$reset of a nested list', () => {
+		let useStore: ReturnType<typeof createTableStore>;
+
+		beforeEach(async () => {
+			useStore = createTableStore('cases-reset/datalist', {
+				apiModule: {
+					getList,
+				},
+				headers,
+				disablePersistence: true,
+			});
+
+			mountTab(useStore);
+			await flush();
+			getList.mockClear();
+		});
+
+		it('drops the rows, the parent and the pagination', async () => {
+			const store = useStore();
+			store.updatePage(3);
+			await flush();
+
+			store.$reset();
+
+			expect(store.dataList).toEqual([]);
+			expect(store.selected).toEqual([]);
+			expect(store.error).toBeNull();
+			expect(store.page).toBe(1);
+		});
+
+		it('keeps the headers, which are the user column choice', async () => {
+			const store = useStore();
+			store.updateShownHeaders(
+				store.headers.map((header, index) => ({
+					...header,
+					show: index === 0,
+				})),
+			);
+			await flush();
+			const shown = store.headers.map((header) => header.show);
+
+			store.$reset();
+
+			expect(store.headers.map((header) => header.show)).toEqual(shown);
+		});
+
+		it('loads nothing until it has a parent again', async () => {
+			const store = useStore();
+			store.$reset();
+			getList.mockClear();
+
+			await store.loadDataList();
+			store.updatePage(2);
+			await flush();
+
+			expect(getList).not.toHaveBeenCalled();
+
+			store.initialize({
+				parentId: '43',
+			});
+			await flush();
+
+			expect(getList).toHaveBeenCalledWith(
+				expect.objectContaining({
+					parentId: '43',
+				}),
+			);
+		});
+	});
 });

package/src/modules/table/__tests__/useNestedTableList.spec.ts

@@ -0,0 +1,218 @@
+import { mount } from '@vue/test-utils';
+import { createPinia, setActivePinia } from 'pinia';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, ref } from 'vue';
+import { createMemoryHistory, createRouter, type Router } from 'vue-router';
+
+import { provideCardStore } from '../../card/composables/useCardStoreProvider';
+import type { CardItemId } from '../../card/types/CardStore.types';
+import type { DatalistTableHeader } from '../../types/tableStore.types';
+import { useNestedTableList } from '../composables/useNestedTableList';
+import { createTableStore } from '../createTableStore.store';
+
+const routes = [
+	{
+		path: '/queues',
+		name: 'queues',
+		component: {
+			template: '<div />',
+		},
+	},
+];
+
+const headers = [
+	{
+		value: 'name',
+		field: 'name',
+		show: true,
+		sort: null,
+	},
+] as DatalistTableHeader[];
+
+const flush = async () => {
+	for (let i = 0; i < 5; i += 1) {
+		await new Promise((resolve) => setTimeout(resolve));
+	}
+};
+
+/*
+ A nested list store is shared by every card of its kind and outlives all of
+ them, so a tab that read it directly showed the rows of whichever record was
+ opened before — and a card for an unsaved record showed them until saved.
+
+ [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+ */
+describe('useNestedTableList', () => {
+	let router: Router;
+	let getList: ReturnType<typeof vi.fn>;
+	let useStore: ReturnType<typeof createTableStore>;
+	let namespace = 0;
+
+	beforeEach(async () => {
+		localStorage.clear();
+		sessionStorage.clear();
+		setActivePinia(createPinia());
+
+		router = createRouter({
+			history: createMemoryHistory(),
+			routes,
+		});
+		await router.push('/queues');
+		await router.isReady();
+
+		getList = vi.fn().mockImplementation(({ parentId }) =>
+			Promise.resolve({
+				items: [
+					{
+						id: 1,
+						name: `row of ${parentId}`,
+					},
+				],
+				next: false,
+			}),
+		);
+
+		namespace += 1;
+		useStore = createTableStore(`queue-buckets-${namespace}/datalist`, {
+			apiModule: {
+				getList,
+			},
+			headers,
+			disablePersistence: true,
+		});
+	});
+
+	/** a card page with one nested tab in it */
+	const openCard = (itemId: CardItemId) => {
+		const cardItemId = ref<CardItemId>(itemId);
+		const nestedLists = new Set<{
+			$reset: () => void;
+		}>();
+
+		const Tab = defineComponent({
+			setup() {
+				useNestedTableList({
+					useTableStore: useStore,
+				});
+				return () => h('div');
+			},
+		});
+
+		const Card = defineComponent({
+			setup() {
+				provideCardStore({
+					get itemId() {
+						return cardItemId.value;
+					},
+					registerNestedList: (list) => nestedLists.add(list),
+				});
+
+				return () => h(Tab);
+			},
+		});
+
+		const card = mount(Card, {
+			global: {
+				plugins: [
+					router,
+				],
+			},
+		});
+
+		/** what the card page does on unmount */
+		const close = () => {
+			for (const list of nestedLists) list.$reset();
+			nestedLists.clear();
+			card.unmount();
+		};
+
+		return {
+			card,
+			close,
+			cardItemId,
+			nestedLists,
+		};
+	};
+
+	it('loads the list of the card it is opened in', async () => {
+		openCard('42');
+		await flush();
+
+		expect(getList).toHaveBeenCalledWith(
+			expect.objectContaining({
+				parentId: '42',
+			}),
+		);
+		expect(useStore().dataList).toEqual([
+			{
+				id: 1,
+				name: 'row of 42',
+			},
+		]);
+	});
+
+	it('registers itself with the card, which empties it on close', async () => {
+		const first = openCard('42');
+		await flush();
+		expect(first.nestedLists.size).toBe(1);
+
+		first.close();
+		await flush();
+
+		expect(useStore().dataList).toEqual([]);
+		expect(first.nestedLists.size).toBe(0);
+	});
+
+	it('shows no rows of the previously opened card', async () => {
+		const first = openCard('42');
+		await flush();
+		first.close();
+		await flush();
+
+		getList.mockClear();
+		const second = openCard(null); // a record that is not saved yet
+		await flush();
+
+		expect(getList).not.toHaveBeenCalled();
+		expect(useStore().dataList).toEqual([]);
+		second.close();
+	});
+
+	it('loads once the unsaved record gets its id', async () => {
+		const card = openCard(null);
+		await flush();
+		expect(getList).not.toHaveBeenCalled();
+
+		card.cardItemId.value = '43';
+		await flush();
+
+		expect(getList).toHaveBeenCalledWith(
+			expect.objectContaining({
+				parentId: '43',
+			}),
+		);
+		expect(useStore().dataList).toEqual([
+			{
+				id: 1,
+				name: 'row of 43',
+			},
+		]);
+	});
+
+	it('does not reload the previous parent when the store reloads itself', async () => {
+		const first = openCard('42');
+		await flush();
+		first.close();
+		await flush();
+
+		getList.mockClear();
+		const store = useStore();
+
+		// what a pagination change does, with no card to belong to
+		store.updatePage(2);
+		await flush();
+
+		expect(getList).not.toHaveBeenCalled();
+		expect(store.dataList).toEqual([]);
+	});
+});

package/src/modules/table/composables/useNestedTableList.ts

@@ -0,0 +1,61 @@
+import { computed, type MaybeRefOrGetter, toValue, watch } from 'vue';
+
+import { useInjectedCardStore } from '../../card/composables/useCardStoreProvider';
+import type { CardItemId, NestedList } from '../../card/types/CardStore.types';
+
+/** what this needs of a table store, which `createTableStore` satisfies */
+interface NestedTableListStore extends NestedList {
+	initialize: (options: { parentId: string | number }) => unknown;
+}
+
+/**
+ * The list of a card page's nested tab.
+ *
+ * The store is shared by every card of its kind and outlives all of them, so a
+ * tab that read it directly showed the rows of whichever record was opened
+ * before — and a card for an unsaved record, having no id to initialize with,
+ * showed them until it was saved.
+ *
+ * Registering the list with the card store makes the card responsible for
+ * emptying it, and the parent to load comes from the card's own `itemId`: it
+ * arrives late for a record created from a nested tab, and the list follows.
+ *
+ * ```ts
+ * const tableStore = useNestedTableList({ useTableStore: useQueueBucketsStore });
+ * const { dataList, isLoading } = storeToRefs(tableStore);
+ * ```
+ *
+ * [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+ */
+export const useNestedTableList = <Store extends NestedTableListStore>({
+	useTableStore,
+	parentId,
+}: {
+	useTableStore: () => Store;
+	/** only where the parent is not the card's own record */
+	parentId?: MaybeRefOrGetter<CardItemId>;
+}) => {
+	const tableStore = useTableStore();
+	const cardStore = useInjectedCardStore();
+
+	cardStore?.registerNestedList(tableStore);
+
+	const parent = computed<CardItemId>(
+		() => toValue(parentId) ?? cardStore?.itemId ?? null,
+	);
+
+	watch(
+		parent,
+		(id) => {
+			if (id)
+				tableStore.initialize({
+					parentId: id,
+				});
+		},
+		{
+			immediate: true,
+		},
+	);
+
+	return tableStore;
+};

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

@@ -34,6 +34,13 @@ export const tableStoreBody = <Entity extends Identifiable>(
 	const useFiltersStore = createTableFiltersStore(namespace, config);
 
 	const parentId = ref();
+	/**
+	 * A list initialized with a `parentId` is nested in a card page, and stays
+	 * nested for the store's lifetime — the api module addresses its parent.
+	 * `parentId` is dropped on `$reset`, this is not: it is what tells a reset
+	 * store apart from a registry one that never had a parent.
+	 */
+	const isNested = ref(false);
 
 	const paginationStore = usePaginationStore();
 	const { page, size, next } = makeThisToRefs<typeof paginationStore>(
@@ -129,6 +136,15 @@ export const tableStoreBody = <Entity extends Identifiable>(
 	const loadDataList = async ({
 		withLoading = true,
 	}: LoadDataListOptions = {}) => {
+		/*
+     a nested list with no parent has nothing to address: either its card was
+     left (the card store reset it) or the record is not saved yet. Loading
+     here would query whatever parent the store held before.
+
+     [WTEL-10350](https://webitel.atlassian.net/browse/WTEL-10350)
+    */
+		if (isNested.value && !parentId.value) return;
+
 		if (withLoading) {
 			isLoading.value = true;
 		}
@@ -344,6 +360,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 	} = {}) => {
 		if (storeParentId) {
 			parentId.value = storeParentId;
+			isNested.value = true;
 		}
 
 		const isStoreAlreadySetUp = isStoreSetUp.value;
@@ -365,6 +382,24 @@ export const tableStoreBody = <Entity extends Identifiable>(
 		return loadDataList();
 	};
 
+	/**
+	 * Drops everything that belonged to one parent record. Called by the card
+	 * store this list is registered with, when the card page goes away.
+	 *
+	 * Headers are left alone — they are the user's column choice, restored once
+	 * per app lifetime — and so is `isStoreSetUp`, for the same reason.
+	 */
+	const $reset = () => {
+		dataList.value = [];
+		selected.value = [];
+		error.value = null;
+		isLoading.value = false;
+		parentId.value = undefined;
+
+		paginationStore.$reset();
+		filtersManager.value.reset();
+	};
+
 	const resetInfiniteScrollTableParamsToDefaults = () => {
 		paginationStore.$reset();
 		filtersManager.value.reset();
@@ -373,6 +408,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 
 	return {
 		isStoreSetUp, // internal export for pinia devtools
+		isNested, // internal export for pinia devtools
 
 		dataList,
 		selected,
@@ -395,6 +431,7 @@ export const tableStoreBody = <Entity extends Identifiable>(
 
 		setupStore, // only setup, no data loading
 		initialize, // setup + load data
+		$reset, // drop the data and the parent binding
 		syncPersistence, // republish store state into the route query
 
 		loadDataList,