@keenthemes/ktui 1.2.3 → 1.2.5

package/src/components/datatable/__tests__/architecture-boundaries.test.ts

@@ -0,0 +1,259 @@
+/**
+ * Tests for datatable architecture boundaries introduced during internal refactor.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { KTDataTable } from '../datatable';
+import { createDataTableEventAdapter } from '../datatable-event-adapter';
+import { KTDataTableLocalDataProvider } from '../datatable-local-provider';
+import { KTDataTableDomPaginationRenderer } from '../datatable-pagination-renderer';
+import { KTDataTableRemoteDataProvider } from '../datatable-remote-provider';
+import { KTDataTableConfigStateStore } from '../datatable-state-store';
+import { KTDataTableDomTableRenderer } from '../datatable-table-renderer';
+import { KTDataTableConfigInterface } from '../types';
+import { waitFor } from './setup';
+
+function createConfig(
+	overrides: Partial<KTDataTableConfigInterface> = {},
+): KTDataTableConfigInterface {
+	return {
+		pageSize: 10,
+		pageSizes: [10, 20],
+		pageMore: true,
+		pageMoreLimit: 3,
+		info: '{start}-{end} of {total}',
+		infoEmpty: 'No records found',
+		requestMethod: 'GET',
+		requestHeaders: {},
+		pagination: {
+			number: { class: 'number', text: '{page}' },
+			previous: { class: 'previous', text: 'Previous' },
+			next: { class: 'next', text: 'Next' },
+			more: { class: 'more', text: '...' },
+		},
+		search: {
+			delay: 0,
+			callback: (data, search) =>
+				data.filter((item) => String(item.name).includes(search)),
+		},
+		sort: {
+			callback: (data) => data,
+		},
+		attributes: {
+			table: '[data-kt-datatable-table="true"]',
+			info: '[data-kt-datatable-info="true"]',
+			size: '[data-kt-datatable-size="true"]',
+			pagination: '[data-kt-datatable-pagination="true"]',
+			spinner: '[data-kt-datatable-spinner="true"]',
+			check: '[data-kt-datatable-check="true"]',
+			checkbox: '[data-kt-datatable-row-check="true"]',
+		},
+		_state: {},
+		...overrides,
+	} as KTDataTableConfigInterface;
+}
+
+describe('KTDataTable architecture boundaries', () => {
+	it('routes state transitions through the state store', () => {
+		const config = createConfig();
+		const store = new KTDataTableConfigStateStore(config);
+
+		store.setPage(3);
+		store.setPageSize(20);
+		store.setSort('name', 'asc');
+		store.setSearch('Ada');
+		store.setFilter({ column: 'status', type: 'text', value: 'active' });
+
+		expect(store.getState()).toMatchObject({
+			page: 1,
+			pageSize: 20,
+			sortField: 'name',
+			sortOrder: 'asc',
+			search: 'Ada',
+		});
+		expect(store.getState().filters).toEqual([
+			{ column: 'status', type: 'text', value: 'active' },
+		]);
+		expect(config._state.page).toBe(1);
+	});
+
+	it('emits through both legacy event channels from one adapter', () => {
+		const fireEvent = vi.fn();
+		const dispatchEvent = vi.fn();
+		const adapter = createDataTableEventAdapter(fireEvent, dispatchEvent);
+
+		adapter.emit('reload', { page: 1 });
+
+		expect(fireEvent).toHaveBeenCalledWith('reload', { page: 1 });
+		expect(dispatchEvent).toHaveBeenCalledWith('reload', { page: 1 });
+	});
+
+	it('extracts and pages local table data through the local provider', () => {
+		const config = createConfig({ pageSize: 1 });
+		const stateStore = new KTDataTableConfigStateStore(config);
+		const table = document.createElement('table');
+		const thead = table.createTHead();
+		thead.innerHTML = `
+			<tr>
+				<th data-kt-datatable-column="id">ID</th>
+				<th data-kt-datatable-column="name">Name</th>
+			</tr>
+		`;
+		const tbody = table.createTBody();
+		tbody.innerHTML = `
+			<tr><td>1</td><td>Ada</td></tr>
+			<tr><td>2</td><td>Grace</td></tr>
+		`;
+
+		const provider = new KTDataTableLocalDataProvider({
+			config,
+			elements: () => ({
+				tableElement: table,
+				tbodyElement: tbody,
+				theadElement: thead,
+			}),
+			getLogicalColumnCount: () => 2,
+			storeOriginalClasses: vi.fn(),
+			stateStore,
+		});
+
+		const result = provider.fetchSync();
+
+		expect(result.totalItems).toBe(2);
+		expect(result.data).toEqual([{ id: '1', name: 'Ada' }]);
+		expect(stateStore.getState().originalData).toHaveLength(2);
+	});
+
+	it('normalizes remote provider fetch results and emits response event', async () => {
+		const config = createConfig({ apiEndpoint: '/api/users' });
+		const stateStore = new KTDataTableConfigStateStore(config);
+		const emit = vi.fn();
+		global.fetch = vi.fn().mockResolvedValue(
+			new Response(
+				JSON.stringify({
+					data: [{ id: 1, name: 'Ada' }],
+					totalCount: 1,
+				}),
+			),
+		);
+
+		const provider = new KTDataTableRemoteDataProvider({
+			config,
+			createUrl: (pathOrUrl: string) =>
+				new URL(pathOrUrl, window.location.origin),
+			eventAdapter: { emit },
+			noticeOnTable: vi.fn(),
+			stateStore,
+		});
+
+		const result = await provider.fetch();
+
+		expect(result.data).toEqual([{ id: 1, name: 'Ada' }]);
+		expect(result.totalItems).toBe(1);
+		expect(emit).toHaveBeenCalledWith('fetched', {
+			response: { data: [{ id: 1, name: 'Ada' }], totalCount: 1 },
+		});
+	});
+
+	it('renders table body output through the table renderer', () => {
+		const config = createConfig();
+		const stateStore = new KTDataTableConfigStateStore(config);
+		stateStore.setOriginalData([{ id: '1', name: 'Ada' }], []);
+		const table = document.createElement('table');
+		const thead = table.createTHead();
+		thead.innerHTML = `
+			<tr>
+				<th data-kt-datatable-column="id">ID</th>
+				<th data-kt-datatable-column="name">Name</th>
+			</tr>
+		`;
+		table.createTBody();
+
+		new KTDataTableDomTableRenderer().render({
+			config,
+			context: {} as KTDataTable,
+			data: [{ id: '1', name: 'Ada' }],
+			getLogicalColumnCount: () => 2,
+			getState: () => stateStore.getState(),
+			originalTbodyClass: 'body-class',
+			originalTrClasses: ['row-class'],
+			originalTdClasses: [['id-cell', 'name-cell']],
+			tableElement: table,
+			theadElement: thead,
+		});
+
+		expect(table.tBodies[0].className).toBe('body-class');
+		expect(table.tBodies[0].querySelector('tr')?.className).toBe('row-class');
+		expect(table.tBodies[0].querySelectorAll('td')[1].textContent).toBe('Ada');
+	});
+
+	it('renders pagination controls through the pagination renderer', async () => {
+		const renderer = new KTDataTableDomPaginationRenderer();
+		const config = createConfig();
+		const sizeElement = document.createElement('select');
+		const infoElement = document.createElement('div');
+		const paginationElement = document.createElement('div');
+		const paginateData = vi.fn();
+
+		renderer.render({
+			config,
+			dataLength: 10,
+			infoElement,
+			paginateData,
+			paginationElement,
+			reloadPageSize: vi.fn(),
+			sizeElement,
+			state: {
+				page: 2,
+				pageSize: 10,
+				totalItems: 25,
+				totalPages: 3,
+				filters: [],
+			} as never,
+		});
+
+		await waitFor(120);
+
+		expect(infoElement.textContent).toBe('11-20 of 25');
+		expect(sizeElement.querySelectorAll('option')).toHaveLength(2);
+		expect(paginationElement.querySelectorAll('button')).toHaveLength(5);
+		paginationElement.querySelectorAll('button')[1].click();
+		expect(paginateData).toHaveBeenCalledWith(1);
+	});
+
+	it('keeps local and remote provider selection compatible through KTDataTable', async () => {
+		const element = document.createElement('div');
+		element.innerHTML = `
+			<table data-kt-datatable-table="true">
+				<thead><tr><th data-kt-datatable-column="name">Name</th></tr></thead>
+				<tbody><tr><td>Ada</td></tr></tbody>
+			</table>
+			<div data-kt-datatable-info="true"></div>
+			<select data-kt-datatable-size="true"></select>
+			<div data-kt-datatable-pagination="true"></div>
+		`;
+		document.body.appendChild(element);
+
+		const fetchSpy = vi
+			.fn()
+			.mockResolvedValue(
+				new Response(
+					JSON.stringify({ data: [{ name: 'Ada' }], totalCount: 1 }),
+				),
+			);
+		global.fetch = fetchSpy;
+
+		new KTDataTable(element, { stateSave: false });
+		expect(fetchSpy).not.toHaveBeenCalled();
+
+		const remoteElement = element.cloneNode(true) as HTMLElement;
+		document.body.appendChild(remoteElement);
+		new KTDataTable(remoteElement, {
+			apiEndpoint: '/api/users',
+			stateSave: false,
+		});
+		await waitFor(0);
+
+		expect(fetchSpy).toHaveBeenCalledTimes(1);
+	});
+});

package/src/components/datatable/datatable-checkbox.ts

@@ -8,8 +8,10 @@
 import {
 	KTDataTableConfigInterface,
 	KTDataTableCheckChangePayloadInterface,
+	KTDataTableStateInterface,
 } from './types';
 import KTEventHandler from '../../helpers/event-handler';
+import { KTCallableType } from '../../types';
 
 export interface KTDataTableCheckboxAPI {
 	init(): void;
@@ -29,25 +31,31 @@ export function createCheckboxHandler(
 ): KTDataTableCheckboxAPI {
 	let headerChecked = false;
 	let headerCheckElement: HTMLInputElement | null = null;
-	let targetElements: NodeListOf<HTMLInputElement> = null;
+	let targetElements: NodeListOf<HTMLInputElement> | null = null;
 
 	// Default: preserve selection across all pages
 	const preserveSelection = config.checkbox?.preserveSelection !== false;
 
+	function ensureState(): KTDataTableStateInterface {
+		let state = config._state;
+		if (!state) {
+			state = {} as KTDataTableStateInterface;
+			config._state = state;
+		}
+		return state;
+	}
+
 	// Helper: get selectedRows from state, always as string[]
 	function getSelectedRows(): string[] {
-		if (!config._state)
-			config._state = {} as unknown as KTDataTableConfigInterface['_state'];
-		if (!Array.isArray(config._state.selectedRows))
-			config._state.selectedRows = [];
-		return config._state.selectedRows.map(String);
+		const state = ensureState();
+		if (!Array.isArray(state.selectedRows)) state.selectedRows = [];
+		return state.selectedRows.map(String);
 	}
 
 	// Helper: set selectedRows in state
 	function setSelectedRows(rows: string[]) {
-		if (!config._state)
-			config._state = {} as unknown as KTDataTableConfigInterface['_state'];
-		config._state.selectedRows = Array.from(new Set(rows.map(String)));
+		const state = ensureState();
+		state.selectedRows = Array.from(new Set(rows.map(String)));
 	}
 
 	// Helper: get all visible row IDs (values)
@@ -64,14 +72,14 @@ export function createCheckboxHandler(
 	};
 
 	function init() {
-		headerCheckElement = element.querySelector<HTMLInputElement>(
-			config.attributes.check,
-		);
+		const attrs = config.attributes;
+		if (!attrs?.check || !attrs.checkbox) {
+			return;
+		}
+		headerCheckElement = element.querySelector<HTMLInputElement>(attrs.check);
 		if (!headerCheckElement) return;
 		headerChecked = headerCheckElement.checked;
-		targetElements = element.querySelectorAll(
-			config.attributes.checkbox,
-		) as NodeListOf<HTMLInputElement>;
+		targetElements = element.querySelectorAll<HTMLInputElement>(attrs.checkbox);
 		checkboxHandler();
 		reapplyCheckedStates();
 		updateHeaderCheckboxState();
@@ -79,14 +87,16 @@ export function createCheckboxHandler(
 
 	function checkboxHandler() {
 		if (!headerCheckElement) return;
+		const rowCheckboxSelector = config.attributes?.checkbox;
+		if (!rowCheckboxSelector) return;
 		headerCheckElement.addEventListener('click', checkboxListener);
 		KTEventHandler.on(
 			document.body,
-			config.attributes.checkbox,
+			rowCheckboxSelector,
 			'input',
-			(event: Event) => {
-				handleRowCheckboxChange(event as InputEvent);
-			},
+			((event?: Event) => {
+				if (event) handleRowCheckboxChange(event);
+			}) as KTCallableType,
 		);
 	}
 
@@ -233,10 +243,11 @@ export function createCheckboxHandler(
 	}
 
 	function updateState() {
-		// Called after redraw/pagination
-		targetElements = element.querySelectorAll(
-			config.attributes.checkbox,
-		) as NodeListOf<HTMLInputElement>;
+		const rowCheckSel = config.attributes?.checkbox;
+		if (!rowCheckSel) {
+			return;
+		}
+		targetElements = element.querySelectorAll<HTMLInputElement>(rowCheckSel);
 		reapplyCheckedStates();
 		updateHeaderCheckboxState();
 	}

package/src/components/datatable/datatable-contracts.ts

@@ -0,0 +1,96 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableAttributeInterface,
+	KTDataTableColumnFilterInterface,
+	KTDataTableConfigInterface,
+	KTDataTableDataInterface,
+	KTDataTableInterface,
+	KTDataTableSortOrderInterface,
+	KTDataTableStateInterface,
+} from './types';
+
+export type KTDataTableEmit = (eventName: string, eventData?: object) => void;
+export type KTDataTableCleanup = () => void;
+
+export interface KTDataTableEventAdapter {
+	emit(eventName: string, eventData?: object): void;
+}
+
+export interface KTDataTableStateStore {
+	getState(): KTDataTableStateInterface;
+	replaceState(state: KTDataTableStateInterface): void;
+	patchState(state: Partial<KTDataTableStateInterface>): void;
+	setPage(page: number): void;
+	setPageSize(pageSize: number, page?: number): void;
+	setSort(
+		field: keyof KTDataTableDataInterface | number,
+		order: KTDataTableSortOrderInterface,
+	): void;
+	setSearch(search: string | object): void;
+	setFilter(filter: KTDataTableColumnFilterInterface): void;
+	setOriginalData(
+		originalData: KTDataTableDataInterface[],
+		originalDataAttributes: KTDataTableAttributeInterface[],
+	): void;
+}
+
+export interface KTDataTableProviderResult<T extends KTDataTableDataInterface> {
+	data: T[];
+	totalItems: number;
+	response?: unknown;
+	skipped?: boolean;
+}
+
+export interface KTDataTableDataProvider<T extends KTDataTableDataInterface> {
+	fetch(): Promise<KTDataTableProviderResult<T>>;
+	dispose?(): void;
+}
+
+export interface KTDataTableLocalProviderElements {
+	tableElement: HTMLTableElement;
+	tbodyElement: HTMLTableSectionElement;
+	theadElement: HTMLTableSectionElement;
+}
+
+export interface KTDataTableTableRendererInput<
+	T extends KTDataTableDataInterface,
+> {
+	config: KTDataTableConfigInterface;
+	context: KTDataTableInterface;
+	data: T[];
+	getLogicalColumnCount: () => number;
+	getState: () => KTDataTableStateInterface;
+	originalTbodyClass: string;
+	originalTrClasses: string[];
+	originalTdClasses: string[][];
+	tableElement: HTMLTableElement;
+	theadElement: HTMLTableSectionElement;
+}
+
+export interface KTDataTableTableRenderer<T extends KTDataTableDataInterface> {
+	render(input: KTDataTableTableRendererInput<T>): HTMLTableSectionElement;
+	notice(
+		tableElement: HTMLTableElement,
+		getLogicalColumnCount: () => number,
+		message?: string,
+	): void;
+}
+
+export interface KTDataTablePaginationRendererInput {
+	config: KTDataTableConfigInterface;
+	dataLength: number;
+	infoElement?: HTMLElement | null;
+	paginateData: (page: number) => void;
+	paginationElement?: HTMLElement | null;
+	reloadPageSize: (pageSize: number, page?: number) => void;
+	sizeElement?: HTMLSelectElement | null;
+	state: KTDataTableStateInterface;
+}
+
+export interface KTDataTablePaginationRenderer {
+	render(input: KTDataTablePaginationRendererInput): KTDataTableCleanup | void;
+}

package/src/components/datatable/datatable-event-adapter.ts

@@ -0,0 +1,21 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableEmit,
+	KTDataTableEventAdapter,
+} from './datatable-contracts';
+
+export function createDataTableEventAdapter(
+	fireEvent: KTDataTableEmit,
+	dispatchEvent: KTDataTableEmit,
+): KTDataTableEventAdapter {
+	return {
+		emit(eventName: string, eventData?: object): void {
+			fireEvent(eventName, eventData);
+			dispatchEvent(eventName, eventData);
+		},
+	};
+}

package/src/components/datatable/datatable-local-provider.ts

@@ -0,0 +1,193 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import KTUtils from '../../helpers/utils';
+import {
+	KTDataTableAttributeInterface,
+	KTDataTableConfigInterface,
+	KTDataTableDataInterface,
+	KTDataTableStateInterface,
+} from './types';
+import {
+	KTDataTableDataProvider,
+	KTDataTableLocalProviderElements,
+	KTDataTableProviderResult,
+	KTDataTableStateStore,
+} from './datatable-contracts';
+
+interface KTDataTableLocalProviderOptions<T extends KTDataTableDataInterface> {
+	config: KTDataTableConfigInterface;
+	elements: () => KTDataTableLocalProviderElements;
+	getLogicalColumnCount: () => number;
+	storeOriginalClasses: () => void;
+	stateStore: KTDataTableStateStore;
+}
+
+export class KTDataTableLocalDataProvider<
+	T extends KTDataTableDataInterface,
+> implements KTDataTableDataProvider<T> {
+	constructor(private readonly options: KTDataTableLocalProviderOptions<T>) {}
+
+	public async fetch(): Promise<KTDataTableProviderResult<T>> {
+		return this.fetchSync();
+	}
+
+	public fetchSync(): KTDataTableProviderResult<T> {
+		const state = this.options.stateStore.getState();
+		let { originalData } = state;
+
+		if (
+			!this.options.elements().tableElement ||
+			originalData === undefined ||
+			this.tableConfigInvalidate() ||
+			this.localTableHeaderInvalidate() ||
+			this.localTableContentInvalidate()
+		) {
+			const { originalData, originalDataAttributes } =
+				this.localExtractTableContent();
+
+			this.options.stateStore.setOriginalData(
+				originalData,
+				originalDataAttributes,
+			);
+		}
+
+		originalData = this.options.stateStore.getState().originalData;
+		let data = [...originalData] as T[];
+		let filteredData = data;
+
+		const { sortField, sortOrder, page, pageSize, search } =
+			this.options.stateStore.getState();
+
+		if (search) {
+			const searchTerm = typeof search === 'string' ? search : '';
+			const searchCallback = this.options.config.search?.callback;
+			if (searchCallback) {
+				filteredData = data = searchCallback.call(
+					this,
+					data,
+					searchTerm,
+				) as T[];
+			}
+		}
+
+		const sortCallback = this.options.config.sort?.callback;
+		if (
+			sortField !== undefined &&
+			sortOrder !== undefined &&
+			sortOrder !== '' &&
+			typeof sortCallback === 'function'
+		) {
+			data = sortCallback.call(this, data, sortField as string, sortOrder) as T[];
+		}
+
+		if (data?.length > 0) {
+			const startIndex = (page - 1) * pageSize;
+			const endIndex = startIndex + pageSize;
+			data = data.slice(startIndex, endIndex) as T[];
+		}
+
+		return {
+			data,
+			totalItems: filteredData.length,
+		};
+	}
+
+	private localTableContentInvalidate(): boolean {
+		const { tbodyElement } = this.options.elements();
+		const checksum: string = KTUtils.checksum(
+			JSON.stringify(tbodyElement.innerHTML),
+		);
+
+		if (this.options.stateStore.getState()._contentChecksum !== checksum) {
+			this.options.stateStore.patchState({ _contentChecksum: checksum });
+			return true;
+		}
+
+		return false;
+	}
+
+	private tableConfigInvalidate(): boolean {
+		const { _state, ...restConfig } = this.options.config;
+		const checksum: string = KTUtils.checksum(JSON.stringify(restConfig));
+
+		if ((_state?._configChecksum ?? '') !== checksum) {
+			this.options.stateStore.patchState({ _configChecksum: checksum });
+			return true;
+		}
+
+		return false;
+	}
+
+	private localExtractTableContent(): {
+		originalData: T[];
+		originalDataAttributes: KTDataTableAttributeInterface[];
+	} {
+		const originalData: T[] = [];
+		const originalDataAttributes: KTDataTableAttributeInterface[] = [];
+		const { tbodyElement, theadElement } = this.options.elements();
+
+		this.options.storeOriginalClasses();
+
+		const rows = tbodyElement.querySelectorAll<HTMLTableRowElement>('tr');
+		const allThs: NodeListOf<HTMLTableCellElement> = theadElement
+			? theadElement.querySelectorAll('th')
+			: ([] as unknown as NodeListOf<HTMLTableCellElement>);
+
+		const ths: HTMLTableCellElement[] = Array.from(allThs).filter((th) =>
+			th.hasAttribute('data-kt-datatable-column'),
+		);
+		const columnsByIndex: HTMLTableCellElement[] =
+			ths.length > 0 && ths.length !== allThs.length ? Array.from(allThs) : ths;
+
+		rows.forEach((row: HTMLTableRowElement) => {
+			const dataRow: T = {} as T;
+			const dataRowAttribute: KTDataTableAttributeInterface =
+				{} as KTDataTableAttributeInterface;
+
+			row.querySelectorAll<HTMLTableCellElement>('td').forEach((td, index) => {
+				const colName = columnsByIndex[index]?.getAttribute(
+					'data-kt-datatable-column',
+				);
+				if (colName) {
+					dataRow[colName as keyof T] = td.innerHTML?.trim() as T[keyof T];
+				} else {
+					dataRow[index as keyof T] = td.innerHTML?.trim() as T[keyof T];
+				}
+			});
+
+			if (Object.keys(dataRow).length > 0) {
+				originalData.push(dataRow);
+				originalDataAttributes.push(dataRowAttribute);
+			}
+		});
+
+		return { originalData, originalDataAttributes };
+	}
+
+	private localTableHeaderInvalidate(): boolean {
+		const { originalData } = this.options.stateStore.getState();
+		const { theadElement } = this.options.elements();
+
+		const totalColumns = originalData.length
+			? Object.keys(originalData[0]).length
+			: 0;
+
+		const allThs: NodeListOf<HTMLTableCellElement> = theadElement
+			? theadElement.querySelectorAll('th')
+			: ([] as unknown as NodeListOf<HTMLTableCellElement>);
+		const thsWithColumn = Array.from(allThs).filter((th) =>
+			th.hasAttribute('data-kt-datatable-column'),
+		);
+		const currentTableHeaders =
+			thsWithColumn.length > 0
+				? thsWithColumn.length !== allThs.length
+					? allThs.length
+					: thsWithColumn.length
+				: this.options.getLogicalColumnCount();
+
+		return currentTableHeaders !== totalColumns;
+	}
+}