@keenthemes/ktui 1.2.5 → 1.2.7

package/src/components/datatable/__tests__/locked-layout.test.ts

@@ -0,0 +1,257 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { KTDataTable } from '../datatable';
+
+type DataRow = {
+	id: string;
+	name: string;
+	status: string;
+};
+
+const rows: DataRow[] = [
+	{ id: '1', name: 'Alpha', status: 'Active' },
+	{ id: '2', name: 'Beta', status: 'Pending' },
+	{ id: '3', name: 'Gamma', status: 'Disabled' },
+];
+
+const createDatatableFixture = () => {
+	const wrapper = document.createElement('div');
+	wrapper.className = 'kt-table-wrapper';
+
+	const container = document.createElement('div');
+	container.id = 'kt_datatable_locked_layout';
+	container.setAttribute('data-kt-datatable', 'true');
+
+	const table = document.createElement('table');
+	table.setAttribute('data-kt-datatable-table', 'true');
+
+	const thead = document.createElement('thead');
+	thead.innerHTML = `
+		<tr>
+			<th data-kt-datatable-column="id">ID</th>
+			<th data-kt-datatable-column="name">Name</th>
+			<th data-kt-datatable-column="status">Status</th>
+		</tr>
+	`;
+	table.appendChild(thead);
+
+	const tbody = document.createElement('tbody');
+	rows.forEach((row) => {
+		const tr = document.createElement('tr');
+		tr.innerHTML = `<td>${row.id}</td><td>${row.name}</td><td>${row.status}</td>`;
+		tbody.appendChild(tr);
+	});
+	table.appendChild(tbody);
+
+	wrapper.appendChild(table);
+	container.appendChild(wrapper);
+
+	const info = document.createElement('span');
+	info.setAttribute('data-kt-datatable-info', 'true');
+	const size = document.createElement('select');
+	size.setAttribute('data-kt-datatable-size', 'true');
+	const pagination = document.createElement('div');
+	pagination.setAttribute('data-kt-datatable-pagination', 'true');
+
+	container.appendChild(info);
+	container.appendChild(size);
+	container.appendChild(pagination);
+	document.body.appendChild(container);
+
+	const sizedCells = table.querySelectorAll<HTMLTableCellElement>('th, td');
+	sizedCells.forEach((cell) => {
+		Object.defineProperty(cell, 'getBoundingClientRect', {
+			value: () =>
+				({
+					width: 120,
+					height: 40,
+					top: 0,
+					left: 0,
+					right: 0,
+					bottom: 0,
+					x: 0,
+					y: 0,
+					toJSON: () => ({}),
+				}) as DOMRect,
+		});
+	});
+
+	return { container, table };
+};
+
+describe('KTDataTable locked layout plugin', () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+	});
+
+	it('applies locked header, rows and columns in local mode and keeps them after sorting', async () => {
+		const { container, table } = createDatatableFixture();
+
+		const datatable = new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			columns: {
+				id: { title: 'ID' },
+				name: { title: 'Name' },
+				status: { title: 'Status' },
+			},
+			lockedLayout: {
+				stickyHeader: true,
+				stickyRows: { top: 1, bottom: 1 },
+				stickyColumns: { left: ['id'], right: ['status'] },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-header').length,
+		).toBeGreaterThan(0);
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-top-row').length,
+		).toBeGreaterThan(0);
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-bottom-row').length,
+		).toBeGreaterThan(0);
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-left').length,
+		).toBeGreaterThan(0);
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-right').length,
+		).toBeGreaterThan(0);
+
+		datatable.sort('name');
+		await vi.runAllTimersAsync();
+
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-cell').length,
+		).toBeGreaterThan(0);
+	});
+
+	it('reapplies locked layout after remote fetch redraw', async () => {
+		const { container, table } = createDatatableFixture();
+		const fetchMock = vi.spyOn(globalThis, 'fetch').mockResolvedValue(
+			new Response(JSON.stringify({ data: rows, totalCount: rows.length }), {
+				status: 200,
+				headers: { 'Content-Type': 'application/json' },
+			}),
+		);
+
+		new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			apiEndpoint: 'https://example.test/datatable',
+			requestMethod: 'GET',
+			mapResponse: (data) => data,
+			lockedLayout: {
+				stickyHeader: true,
+				stickyColumns: { left: ['id'] },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+
+		expect(fetchMock).toHaveBeenCalled();
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-header').length,
+		).toBeGreaterThan(0);
+		expect(
+			table.querySelectorAll('.kt-datatable-locked-left').length,
+		).toBeGreaterThan(0);
+	});
+
+	it('keeps pagination state when using locked columns in local mode', async () => {
+		const { container } = createDatatableFixture();
+
+		const datatable = new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			pageSize: 2,
+			columns: {
+				id: { title: 'ID' },
+				name: { title: 'Name' },
+				status: { title: 'Status' },
+			},
+			lockedLayout: {
+				stickyHeader: true,
+				stickyColumns: { left: ['id'] },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+		expect(datatable.getState().totalPages).toBe(2);
+
+		datatable.goPage(2);
+		await vi.runAllTimersAsync();
+		expect(datatable.getState().page).toBe(2);
+		expect(datatable.getState().totalPages).toBe(2);
+		expect(datatable.getState().totalItems).toBe(rows.length);
+	});
+
+	it('uses collapsed table borders for row-only locked layout', async () => {
+		const { container, table } = createDatatableFixture();
+
+		new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			lockedLayout: {
+				stickyHeader: true,
+				stickyRows: { top: 1, bottom: 1 },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+
+		expect(table.classList.contains('kt-datatable-locked-layout')).toBe(true);
+		expect(
+			table.classList.contains('kt-datatable-locked-layout-separate'),
+		).toBe(false);
+		expect(table.style.borderCollapse).not.toBe('separate');
+		expect(
+			table.tHead?.classList.contains('kt-datatable-locked-header-section'),
+		).toBe(true);
+		const stickyHeaderCell = table.querySelector(
+			'th.kt-datatable-locked-header',
+		) as HTMLTableCellElement | null;
+		expect(stickyHeaderCell?.style.position).not.toBe('sticky');
+	});
+
+	it('uses separate table borders when sticky columns are enabled', async () => {
+		const { container, table } = createDatatableFixture();
+
+		new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			lockedLayout: {
+				stickyHeader: true,
+				stickyColumns: { left: ['id'] },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+
+		expect(
+			table.classList.contains('kt-datatable-locked-layout-separate'),
+		).toBe(true);
+		expect(table.style.borderCollapse).toBe('separate');
+	});
+
+	it('does not set inline background color for locked header columns', async () => {
+		const { container, table } = createDatatableFixture();
+
+		new KTDataTable<DataRow>(container, {
+			stateSave: false,
+			columns: {
+				id: { title: 'ID' },
+				name: { title: 'Name' },
+				status: { title: 'Status' },
+			},
+			lockedLayout: {
+				stickyHeader: true,
+				stickyColumns: { left: ['id'] },
+			},
+		});
+
+		await vi.runAllTimersAsync();
+
+		const lockedHeaderCell = table.querySelector(
+			'th.kt-datatable-locked-left',
+		) as HTMLTableCellElement | null;
+		expect(lockedHeaderCell).not.toBeNull();
+		expect(lockedHeaderCell?.style.backgroundColor).toBe('');
+	});
+});

package/src/components/datatable/__tests__/multi-row-headers.test.ts

@@ -30,23 +30,23 @@ describe('KTDataTable - Multi-row header column count', () => {
 		const thead = document.createElement('thead');
 		const row1 = document.createElement('tr');
 		row1.innerHTML = `
-			<th rowspan="2">Person</th>
+			<th rowspan="2" data-kt-datatable-column="person">Person</th>
 			<th colspan="3">Backlog</th>
 			<th colspan="3">Floater (2) 2025</th>
 			<th colspan="3">Floater (1) 2025</th>
 			<th colspan="3">CL2025</th>
 			<th colspan="3">LWP</th>
-			<th rowspan="2">Action</th>
+			<th rowspan="2" data-kt-datatable-column="action">Action</th>
 		`;
 		thead.appendChild(row1);
 
 		const row2 = document.createElement('tr');
 		row2.innerHTML = `
-			<th>Assigned</th><th>Used</th><th>Balance</th>
-			<th>Assigned</th><th>Used</th><th>Balance</th>
-			<th>Assigned</th><th>Used</th><th>Balance</th>
-			<th>Assigned</th><th>Used</th><th>Balance</th>
-			<th>Assigned</th><th>Used</th><th>Balance</th>
+			<th data-kt-datatable-column="assigned1">Assigned</th><th data-kt-datatable-column="used1">Used</th><th data-kt-datatable-column="balance1">Balance</th>
+			<th data-kt-datatable-column="assigned2">Assigned</th><th data-kt-datatable-column="used2">Used</th><th data-kt-datatable-column="balance2">Balance</th>
+			<th data-kt-datatable-column="assigned3">Assigned</th><th data-kt-datatable-column="used3">Used</th><th data-kt-datatable-column="balance3">Balance</th>
+			<th data-kt-datatable-column="assigned4">Assigned</th><th data-kt-datatable-column="used4">Used</th><th data-kt-datatable-column="balance4">Balance</th>
+			<th data-kt-datatable-column="assigned5">Assigned</th><th data-kt-datatable-column="used5">Used</th><th data-kt-datatable-column="balance5">Balance</th>
 		`;
 		thead.appendChild(row2);
 		tableElement.appendChild(thead);

package/src/components/datatable/__tests__/pagination-reset.test.ts

@@ -98,6 +98,10 @@ describe('KTDataTable - Pagination Reset', () => {
 	};
 
 	beforeEach(() => {
+		// Dispose previous test's datatable to cancel in-flight async operations
+		if (datatable) {
+			try { datatable.dispose(); } catch { /* already disposed */ }
+		}
 		// Clear any existing elements
 		document.body.innerHTML = '';
 		vi.clearAllMocks();
@@ -313,7 +317,7 @@ describe('KTDataTable - Pagination Reset', () => {
 			expect(datatable.getState().page).toBe(1);
 
 			// Apply third filter (page should stay at 1)
-			datatable.setFilter({ column: 'id', type: 'numeric', value: '10' });
+			datatable.setFilter({ column: 'id', type: 'numeric', value: 10 });
 			expect(datatable.getState().page).toBe(1);
 		});
 
@@ -438,7 +442,17 @@ describe('KTDataTable - Pagination Reset', () => {
 	});
 
 	describe('Scenario: State persistence respects pagination reset', () => {
+		const isLocalStorageAvailable = (): boolean => {
+			try {
+				localStorage.getItem('test');
+				return true;
+			} catch {
+				return false;
+			}
+		};
+
 		it('should save page 1 to state when search resets pagination', async () => {
+			if (!isLocalStorageAvailable()) return;
 			const { container } = createMockDataTable(25);
 
 			// Enable state saving with unique namespace
@@ -476,6 +490,7 @@ describe('KTDataTable - Pagination Reset', () => {
 		});
 
 		it('should save page 1 to state when filter resets pagination', () => {
+			if (!isLocalStorageAvailable()) return;
 			const { container } = createMockDataTable(25);
 
 			datatable = new KTDataTable(container, {
@@ -503,6 +518,7 @@ describe('KTDataTable - Pagination Reset', () => {
 		});
 
 		it('should restore to page 1 with active search on reload', async () => {
+			if (!isLocalStorageAvailable()) return;
 			const { container } = createMockDataTable(25);
 			const namespace = 'test-datatable-restore';
 
@@ -552,6 +568,131 @@ describe('KTDataTable - Pagination Reset', () => {
 	});
 
 	describe('Edge Cases', () => {
+		it('keeps total pages stable when navigating to page 2 in local mode', () => {
+			const { container } = createMockDataTable(6);
+			datatable = new KTDataTable(container, {
+				pageSize: 5,
+				stateSave: false,
+			});
+
+			expect(datatable.getState().totalPages).toBe(2);
+			datatable.goPage(2);
+			expect(datatable.getState().page).toBe(2);
+			expect(datatable.getState().totalPages).toBe(2);
+
+			// Trigger another redraw cycle to ensure local mode does not shrink original data.
+			datatable.reload();
+			expect(datatable.getState().page).toBe(2);
+			expect(datatable.getState().totalPages).toBe(2);
+		});
+
+		it('does not shrink originalData when tbody checksum mismatches after pagination', async () => {
+			const { container } = createMockDataTable(18);
+			datatable = new KTDataTable(container, {
+				pageSize: 5,
+				stateSave: false,
+			});
+
+			await new Promise((resolve) => setTimeout(resolve, 50));
+			expect(datatable.getState().totalPages).toBe(4);
+
+			// Simulate a fetch before _contentChecksum was aligned with the paginated tbody.
+			datatable.getState()._contentChecksum = 'stale-checksum';
+			datatable.reload();
+
+			await new Promise((resolve) => setTimeout(resolve, 50));
+			expect(datatable.getState().totalPages).toBe(4);
+		});
+
+		it('keeps 4 pages when thead has checkbox and actions columns (bulk-actions demo)', async () => {
+			const container = document.createElement('div');
+			container.id = 'test-bulk-actions-datatable';
+
+			const table = document.createElement('table');
+			table.setAttribute('data-kt-datatable-table', 'true');
+
+			const thead = document.createElement('thead');
+			thead.innerHTML = `
+				<tr>
+					<th><input type="checkbox" data-kt-datatable-check="true" /></th>
+					<th data-kt-datatable-column="label">Label</th>
+					<th data-kt-datatable-column="method">Method</th>
+					<th data-kt-datatable-column="status">Status</th>
+					<th data-kt-datatable-column="lastSession">Last Session</th>
+					<th data-kt-datatable-column="actions"></th>
+				</tr>
+			`;
+
+			const tbody = document.createElement('tbody');
+			for (let i = 1; i <= 18; i++) {
+				const row = document.createElement('tr');
+				row.innerHTML = `
+					<td><input type="checkbox" data-kt-datatable-row-check="true" value="${i - 1}" /></td>
+					<td>User ${i}</td>
+					<td>Web</td>
+					<td>active</td>
+					<td>22 Jul 2024</td>
+					<td><button type="button">Edit</button></td>
+				`;
+				tbody.appendChild(row);
+			}
+
+			table.appendChild(thead);
+			table.appendChild(tbody);
+
+			const infoElement = document.createElement('div');
+			infoElement.setAttribute('data-kt-datatable-info', 'true');
+			const sizeElement = document.createElement('select');
+			sizeElement.setAttribute('data-kt-datatable-size', 'true');
+			const paginationElement = document.createElement('div');
+			paginationElement.setAttribute('data-kt-datatable-pagination', 'true');
+
+			container.appendChild(table);
+			container.appendChild(infoElement);
+			container.appendChild(sizeElement);
+			container.appendChild(paginationElement);
+			document.body.appendChild(container);
+
+			datatable = new KTDataTable(container, {
+				pageSize: 5,
+				stateSave: false,
+			});
+
+			await new Promise((resolve) => setTimeout(resolve, 50));
+
+			expect(datatable.getState().totalPages).toBe(4);
+			datatable.goPage(2);
+			await new Promise((resolve) => setTimeout(resolve, 50));
+			expect(datatable.getState().page).toBe(2);
+			expect(datatable.getState().totalPages).toBe(4);
+		});
+
+		it('shows page 2 rows with tableLayout fixed and columns config (docs column-widths demo)', async () => {
+			const { container } = createMockDataTable(18);
+			datatable = new KTDataTable(container, {
+				pageSize: 5,
+				stateSave: false,
+				tableLayout: 'fixed',
+				columns: {
+					id: { width: '60px' },
+					name: { width: '140px' },
+					status: { width: '100px' },
+				},
+			});
+
+			await new Promise((resolve) => setTimeout(resolve, 50));
+
+			datatable.goPage(2);
+			await new Promise((resolve) => setTimeout(resolve, 50));
+
+			expect(datatable.getState().page).toBe(2);
+
+			const rows = container.querySelectorAll('tbody tr');
+			expect(rows.length).toBe(5);
+			expect(rows[0].cells[0].textContent).toBe('6');
+			expect(datatable.getState().totalPages).toBe(4);
+		});
+
 		it('should handle search reset on page 1 (no-op)', () => {
 			const { container } = createMockDataTable(25);
 			datatable = new KTDataTable(container, {
@@ -651,9 +792,9 @@ describe('KTDataTable - Pagination Reset', () => {
 				stateSave: false,
 			});
 
-			const reloadSpy = vi.fn();
-			// Listen for 'reload' event directly (CustomEvent)
-			container.addEventListener('reload', reloadSpy);
+			const updateSpy = vi.fn();
+			// Listen for 'kt.datatable.update' event directly (CustomEvent)
+			container.addEventListener('kt.datatable.update', updateSpy);
 
 			datatable.goPage(2);
 			datatable.search('test');
@@ -661,8 +802,8 @@ describe('KTDataTable - Pagination Reset', () => {
 			// Wait for async reload to complete
 			await new Promise((resolve) => setTimeout(resolve, 50));
 
-			// reload event should still fire
-			expect(reloadSpy).toHaveBeenCalled();
+			// update event should still fire
+			expect(updateSpy).toHaveBeenCalled();
 		});
 	});
 });

package/src/components/datatable/__tests__/race-conditions.test.ts

@@ -407,13 +407,13 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 	describe('Event Handling During Race Conditions', () => {
 		it('should fire fetch event for successful requests', async () => {
-			const fetchEvents: Event[] = [];
+			const updateEvents: Event[] = [];
 
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
 			) as HTMLElement;
-			element.addEventListener('fetch', (e) => {
-				fetchEvents.push(e);
+			element.addEventListener('kt.datatable.update', (e) => {
+				updateEvents.push(e);
 			});
 
 			const datatable = new KTDataTable(element, {
@@ -425,18 +425,18 @@ describe('KTDataTable Race Condition Fixes', () => {
 			datatable.search('test');
 			await waitFor(150); // Complete search
 
-			// Should fire fetch for initial and search
-			expect(fetchEvents.length).toBeGreaterThanOrEqual(2);
+			// Should fire update for initial and search
+			expect(updateEvents.length).toBeGreaterThanOrEqual(2);
 		});
 
 		it('should fire fetched event after successful data load', async () => {
-			const fetchedEvents: Event[] = [];
+			const updateEvents: Event[] = [];
 
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
 			) as HTMLElement;
-			element.addEventListener('fetched', (e) => {
-				fetchedEvents.push(e);
+			element.addEventListener('kt.datatable.update', (e) => {
+				updateEvents.push(e);
 			});
 
 			new KTDataTable(element, {
@@ -445,8 +445,8 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 			await waitFor(150);
 
-			// Should fire fetched for initial request
-			expect(fetchedEvents.length).toBeGreaterThanOrEqual(1);
+			// Should fire update for initial request
+			expect(updateEvents.length).toBeGreaterThanOrEqual(1);
 		});
 
 		it('should not fire error events for AbortError', async () => {
@@ -455,7 +455,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
 			) as HTMLElement;
-			element.addEventListener('error.kt.datatable', (e) => {
+			element.addEventListener('kt.datatable.error', (e) => {
 				errorEvents.push(e);
 			});
 

package/src/components/datatable/__tests__/setup.ts

@@ -17,8 +17,12 @@ vi.mock('../../../index', () => ({
 
 // Setup DOM environment before each test
 beforeEach(() => {
-	// Clear localStorage
-	localStorage.clear();
+	// Clear localStorage (may be unavailable in Node.js without --localstorage-file)
+	try {
+		localStorage.clear();
+	} catch {
+		// localStorage not available
+	}
 
 	// Reset document body
 	document.body.innerHTML = '';
@@ -29,8 +33,12 @@ beforeEach(() => {
 
 // Cleanup after each test
 afterEach(() => {
-	// Clear localStorage
-	localStorage.clear();
+	// Clear localStorage (may be unavailable in Node.js without --localstorage-file)
+	try {
+		localStorage.clear();
+	} catch {
+		// localStorage not available
+	}
 
 	// Reset document body
 	document.body.innerHTML = '';