@keenthemes/ktui 1.2.5 → 1.2.7

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

@@ -8,7 +8,6 @@ import {
 	KTDataTableAttributeInterface,
 	KTDataTableConfigInterface,
 	KTDataTableDataInterface,
-	KTDataTableStateInterface,
 } from './types';
 import {
 	KTDataTableDataProvider,
@@ -16,8 +15,36 @@ import {
 	KTDataTableProviderResult,
 	KTDataTableStateStore,
 } from './datatable-contracts';
+import { resolveColumns } from './datatable-column-utils';
+import { stripHtml } from './datatable-utils';
 
-interface KTDataTableLocalProviderOptions<T extends KTDataTableDataInterface> {
+type FilterMatcher = (cellValue: unknown, filterValue: unknown) => boolean;
+
+const FILTER_MATCHERS: Record<string, FilterMatcher> = {
+	text: (cellValue, filterValue) => {
+		if (!filterValue) return true;
+		return stripHtml(cellValue)
+			.toLowerCase()
+			.includes(String(filterValue).toLowerCase());
+	},
+	numeric: (cellValue, filterValue) => {
+		const num = parseFloat(
+			String(cellValue ?? '').replace(/[^0-9.-]/g, ''),
+		);
+		return !Number.isNaN(num) && num === filterValue;
+	},
+	dateRange: (cellValue, filterValue) => {
+		const range = filterValue as { from?: string; to?: string };
+		if (!range?.from && !range?.to) return true;
+		const cellDate = new Date(String(cellValue ?? ''));
+		if (Number.isNaN(cellDate.getTime())) return false;
+		if (range.from && cellDate < new Date(range.from)) return false;
+		if (range.to && cellDate > new Date(range.to)) return false;
+		return true;
+	},
+};
+
+interface KTDataTableLocalProviderOptions {
 	config: KTDataTableConfigInterface;
 	elements: () => KTDataTableLocalProviderElements;
 	getLogicalColumnCount: () => number;
@@ -28,7 +55,7 @@ interface KTDataTableLocalProviderOptions<T extends KTDataTableDataInterface> {
 export class KTDataTableLocalDataProvider<
 	T extends KTDataTableDataInterface,
 > implements KTDataTableDataProvider<T> {
-	constructor(private readonly options: KTDataTableLocalProviderOptions<T>) {}
+	constructor(private readonly options: KTDataTableLocalProviderOptions) {}
 
 	public async fetch(): Promise<KTDataTableProviderResult<T>> {
 		return this.fetchSync();
@@ -37,13 +64,17 @@ export class KTDataTableLocalDataProvider<
 	public fetchSync(): KTDataTableProviderResult<T> {
 		const state = this.options.stateStore.getState();
 		let { originalData } = state;
+		const skipDomInvalidation = Boolean(
+			this.options.config.lockedLayout || this.options.config.layoutPlugin,
+		);
 
 		if (
 			!this.options.elements().tableElement ||
 			originalData === undefined ||
-			this.tableConfigInvalidate() ||
-			this.localTableHeaderInvalidate() ||
-			this.localTableContentInvalidate()
+			(!skipDomInvalidation &&
+				(this.tableConfigInvalidate() ||
+					this.localTableHeaderInvalidate() ||
+					this.localTableContentInvalidate()))
 		) {
 			const { originalData, originalDataAttributes } =
 				this.localExtractTableContent();
@@ -73,6 +104,18 @@ export class KTDataTableLocalDataProvider<
 			}
 		}
 
+		// Apply column filters
+		const { filters } = this.options.stateStore.getState();
+		if (filters && filters.length > 0) {
+			filteredData = data = data.filter((item: T) => {
+				return filters.every((filter) => {
+					const cellValue = item[filter.column as keyof T];
+					const matcher = FILTER_MATCHERS[filter.type];
+					return matcher ? matcher(cellValue, filter.value) : true;
+				});
+			}) as T[];
+		}
+
 		const sortCallback = this.options.config.sort?.callback;
 		if (
 			sortField !== undefined &&
@@ -80,7 +123,12 @@ export class KTDataTableLocalDataProvider<
 			sortOrder !== '' &&
 			typeof sortCallback === 'function'
 		) {
-			data = sortCallback.call(this, data, sortField as string, sortOrder) as T[];
+			data = sortCallback.call(
+				this,
+				data,
+				sortField as string,
+				sortOrder,
+			) as T[];
 		}
 
 		if (data?.length > 0) {
@@ -102,6 +150,30 @@ export class KTDataTableLocalDataProvider<
 		);
 
 		if (this.options.stateStore.getState()._contentChecksum !== checksum) {
+			const domRowCount =
+				tbodyElement.querySelectorAll<HTMLTableRowElement>('tr').length;
+			const storedRowCount =
+				this.options.stateStore.getState().originalData?.length ?? 0;
+
+			// Programmatic dataset with an empty tbody must not re-import from the DOM.
+			if (domRowCount === 0 && storedRowCount > 0) {
+				return false;
+			}
+
+			// After pagination redraw the tbody only holds the current page. A checksum
+			// mismatch there must not shrink originalData to pageSize rows.
+			if (
+				storedRowCount > 0 &&
+				domRowCount > 0 &&
+				domRowCount < storedRowCount
+			) {
+				const { pageSize } = this.options.stateStore.getState();
+				if (domRowCount <= pageSize) {
+					this.options.stateStore.patchState({ _contentChecksum: checksum });
+					return false;
+				}
+			}
+
 			this.options.stateStore.patchState({ _contentChecksum: checksum });
 			return true;
 		}
@@ -112,10 +184,14 @@ export class KTDataTableLocalDataProvider<
 	private tableConfigInvalidate(): boolean {
 		const { _state, ...restConfig } = this.options.config;
 		const checksum: string = KTUtils.checksum(JSON.stringify(restConfig));
+		const previousChecksum = _state?._configChecksum ?? '';
 
-		if ((_state?._configChecksum ?? '') !== checksum) {
+		if (previousChecksum !== checksum) {
 			this.options.stateStore.patchState({ _configChecksum: checksum });
-			return true;
+			// First load skips this check (originalData === undefined). On the first
+			// pagination fetch, previousChecksum is still empty — record it but do
+			// not re-extract from the paginated DOM (that would shrink originalData).
+			return previousChecksum !== '';
 		}
 
 		return false;
@@ -132,15 +208,7 @@ export class KTDataTableLocalDataProvider<
 		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;
+		const { columnsByIndex } = resolveColumns(theadElement);
 
 		rows.forEach((row: HTMLTableRowElement) => {
 			const dataRow: T = {} as T;
@@ -169,25 +237,28 @@ export class KTDataTableLocalDataProvider<
 
 	private localTableHeaderInvalidate(): boolean {
 		const { originalData } = this.options.stateStore.getState();
+		if (!originalData?.length) {
+			return false;
+		}
+
 		const { theadElement } = this.options.elements();
+		const { typedThs } = resolveColumns(theadElement);
 
-		const totalColumns = originalData.length
-			? Object.keys(originalData[0]).length
-			: 0;
+		if (typedThs.length === 0) {
+			return (
+				this.options.getLogicalColumnCount() !==
+				Object.keys(originalData[0]).length
+			);
+		}
 
-		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;
+		const typedColumnNames = typedThs
+			.map((th) => th.getAttribute('data-kt-datatable-column'))
+			.filter((name): name is string => Boolean(name));
+		const dataColumnKeys = Object.keys(originalData[0]);
+		const matchingTypedColumns = typedColumnNames.filter((name) =>
+			dataColumnKeys.includes(name),
+		).length;
+
+		return typedColumnNames.length !== matchingTypedColumns;
 	}
 }

package/src/components/datatable/datatable-pagination-renderer.ts

@@ -8,6 +8,7 @@ import {
 	KTDataTablePaginationRenderer,
 	KTDataTablePaginationRendererInput,
 } from './datatable-contracts';
+import { DEFAULT_PAGE_MORE_LIMIT, DEFAULT_PAGE_SIZES } from './datatable-defaults';
 
 export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRenderer {
 	public render(
@@ -26,6 +27,7 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 		return () => {
 			if (input.sizeElement) {
 				input.sizeElement.onchange = null;
+				this.removeChildElements(input.sizeElement);
 			}
 			if (input.paginationElement) {
 				this.removeChildElements(input.paginationElement);
@@ -50,19 +52,16 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 			return;
 		}
 
-		const pageSizes = input.config.pageSizes ?? [5, 10, 20, 30, 50];
+		const pageSizes = input.config.pageSizes ?? DEFAULT_PAGE_SIZES;
+		const options = pageSizes.map((size: number) => {
+			const option = document.createElement('option') as HTMLOptionElement;
+			option.value = String(size);
+			option.text = String(size);
+			option.selected = input.state.pageSize === size;
+			return option;
+		});
 
-		setTimeout(() => {
-			const options = pageSizes.map((size: number) => {
-				const option = document.createElement('option') as HTMLOptionElement;
-				option.value = String(size);
-				option.text = String(size);
-				option.selected = input.state.pageSize === size;
-				return option;
-			});
-
-			input.sizeElement.append(...options);
-		}, 100);
+		input.sizeElement.append(...options);
 
 		input.sizeElement.onchange = (event: Event) => {
 			input.reloadPageSize(
@@ -92,8 +91,7 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 			return;
 		}
 
-		const infoTemplate =
-			input.config.info ?? '{start}-{end} of {total}';
+		const infoTemplate = input.config.info ?? '{start}-{end} of {total}';
 		input.infoElement.textContent = infoTemplate
 			.replace(
 				'{start}',
@@ -120,7 +118,7 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 
 		const { page: currentPage, totalPages } = input.state;
 		const { previous, next, number, more } = pagination;
-		const pageMoreLimit = input.config.pageMoreLimit ?? 3;
+		const pageMoreLimit = input.config.pageMoreLimit ?? DEFAULT_PAGE_MORE_LIMIT;
 
 		const createButton = (
 			text: string,

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

@@ -0,0 +1,89 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import KTData from '../../helpers/data';
+
+type DataTableInstance = {
+	dispose(): void;
+};
+
+export interface KTDataTableRegistry<T extends DataTableInstance> {
+	register(element: HTMLElement, instance: T): void;
+	get(element: HTMLElement): T | undefined;
+	remove(element: HTMLElement): void;
+	clear(): void;
+	createAll(factory: (element: HTMLElement) => T): void;
+	reinit(factory: (element: HTMLElement) => T): void;
+}
+
+export function createDataTableRegistry<
+	T extends DataTableInstance,
+>(): KTDataTableRegistry<T> {
+	type ElementWithInstance = HTMLElement & { instance?: T };
+	const instances = new Map<HTMLElement, T>();
+
+	function toElementWithInstance(element: HTMLElement): ElementWithInstance {
+		return element as ElementWithInstance;
+	}
+
+	function register(element: HTMLElement, instance: T): void {
+		instances.set(element, instance);
+		toElementWithInstance(element).instance = instance;
+	}
+
+	function get(element: HTMLElement): T | undefined {
+		return instances.get(element) ?? toElementWithInstance(element).instance;
+	}
+
+	function remove(element: HTMLElement): void {
+		instances.delete(element);
+		const el = toElementWithInstance(element);
+		if (el.instance) delete el.instance;
+	}
+
+	function clear(): void {
+		instances.clear();
+	}
+
+	function createAll(factory: (element: HTMLElement) => T): void {
+		if (typeof document === 'undefined') return;
+		const elements = document.querySelectorAll<HTMLElement>(
+			'[data-kt-datatable="true"]',
+		);
+		elements.forEach((element) => {
+			if (
+				element.hasAttribute('data-kt-datatable') &&
+				!element.classList.contains('datatable-initialized')
+			) {
+				const instance = factory(element);
+				register(element, instance);
+			}
+		});
+	}
+
+	function reinit(factory: (element: HTMLElement) => T): void {
+		if (typeof document === 'undefined') return;
+		const elements = document.querySelectorAll<HTMLElement>(
+			'[data-kt-datatable="true"]',
+		);
+		elements.forEach((element) => {
+			try {
+				const instance = get(element);
+				if (instance && typeof instance.dispose === 'function') {
+					instance.dispose();
+				}
+				KTData.remove(element, 'datatable');
+				element.removeAttribute('data-kt-datatable-initialized');
+				element.classList.remove('datatable-initialized');
+			} catch {
+				// ignore per-element errors
+			}
+		});
+		clear();
+		createAll(factory);
+	}
+
+	return { register, get, remove, clear, createAll, reinit };
+}

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

@@ -61,7 +61,7 @@ export class KTDataTableRemoteDataProvider<
 		try {
 			responseData = await response.json();
 		} catch (error) {
-			this.options.eventAdapter.emit('parseError', {
+			this.options.eventAdapter.emit('fetchError', {
 				response,
 				error: String(error),
 				status: response.status,
@@ -74,8 +74,6 @@ export class KTDataTableRemoteDataProvider<
 			return { data: [], totalItems: 0, skipped: true };
 		}
 
-		this.options.eventAdapter.emit('fetched', { response: responseData });
-
 		if (typeof this.options.config.mapResponse === 'function') {
 			responseData = this.options.config.mapResponse.call(this, responseData);
 		}

package/src/components/datatable/datatable-search-handler.ts

@@ -0,0 +1,97 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+/**
+ * Search binding utilities for KTDataTable.
+ * Manages debounced search input binding and cleanup.
+ */
+
+type SearchElementWithDebounce = HTMLInputElement & {
+	_debouncedSearch?: EventListener;
+};
+
+export interface KTDataTableSearchHandler {
+	attach(
+		tableId: string,
+		currentSearch: string | object | undefined,
+		delay: number,
+		onSearch: (query: string) => void,
+	): void;
+	detach(tableId: string): void;
+}
+
+export function createSearchHandler(): KTDataTableSearchHandler {
+	function findSearchElement(tableId: string): HTMLInputElement | null {
+		return document.querySelector<HTMLInputElement>(
+			`[data-kt-datatable-search="#${tableId}"]`,
+		);
+	}
+
+	function asSearchElementWithDebounce(
+		element: HTMLInputElement,
+	): SearchElementWithDebounce {
+		return element as SearchElementWithDebounce;
+	}
+
+	function debounce<TArgs extends unknown[]>(
+		func: (...args: TArgs) => void,
+		wait: number,
+	): (...args: TArgs) => void {
+		let timeout: number | undefined;
+		return function (...args: TArgs) {
+			const later = () => {
+				clearTimeout(timeout);
+				func(...args);
+			};
+			clearTimeout(timeout);
+			timeout = window.setTimeout(later, wait);
+		};
+	}
+
+	function attach(
+		tableId: string,
+		currentSearch: string | object | undefined,
+		delay: number,
+		onSearch: (query: string) => void,
+	): void {
+		const searchElement = findSearchElement(tableId);
+		if (!searchElement) return;
+
+		// Restore search value from state
+		if (currentSearch !== undefined && currentSearch !== null) {
+			searchElement.value =
+				typeof currentSearch === 'string'
+					? currentSearch
+					: String(currentSearch);
+		}
+
+		// Remove existing debounced listener if any
+		const el = asSearchElementWithDebounce(searchElement);
+		if (el._debouncedSearch) {
+			searchElement.removeEventListener('keyup', el._debouncedSearch);
+		}
+
+		// Create and attach new debounced search
+		const debouncedSearch = debounce(() => {
+			onSearch(searchElement.value);
+		}, delay);
+
+		el._debouncedSearch = debouncedSearch;
+		searchElement.addEventListener('keyup', debouncedSearch);
+	}
+
+	function detach(tableId: string): void {
+		const searchElement = findSearchElement(tableId);
+		if (!searchElement) return;
+
+		const el = asSearchElementWithDebounce(searchElement);
+		if (el._debouncedSearch) {
+			searchElement.removeEventListener('keyup', el._debouncedSearch);
+			delete el._debouncedSearch;
+		}
+	}
+
+	return { attach, detach };
+}