@keenthemes/ktui 1.2.6 → 1.2.7

package/src/components/datatable/datatable-column-utils.ts

@@ -0,0 +1,63 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+/**
+ * Shared column resolution utilities for KTDataTable.
+ * Eliminates duplicated column discovery logic across local-provider,
+ * table-renderer, and the main datatable class.
+ */
+
+export interface ResolvedColumns {
+	/** All <th> elements from the thead */
+	allThs: HTMLTableCellElement[];
+	/** Only <th> elements that have data-kt-datatable-column attribute */
+	typedThs: HTMLTableCellElement[];
+	/** The column list to use for rendering: typedThs if all ths have the attr, else allThs */
+	columnsByIndex: HTMLTableCellElement[];
+}
+
+/**
+ * Resolve column headers from a thead element.
+ * Returns both the raw th list and the typed (data-kt-datatable-column) subset.
+ * When some ths lack the attribute, columnsByIndex falls back to all ths by index.
+ */
+export function resolveColumns(
+	theadElement: HTMLTableSectionElement | null,
+): ResolvedColumns {
+	const allThs: HTMLTableCellElement[] = theadElement
+		? Array.from(theadElement.querySelectorAll('th'))
+		: [];
+
+	const typedThs = allThs.filter((th) =>
+		th.hasAttribute('data-kt-datatable-column'),
+	);
+
+	const columnsByIndex = typedThs.length > 0 ? typedThs : allThs;
+
+	return { allThs, typedThs, columnsByIndex };
+}
+
+/**
+ * Get the logical column count: number of data columns.
+ * Prefers originalData keys, falls back to first tbody row td count,
+ * then to resolved columns from thead.
+ */
+export function getLogicalColumnCount(
+	theadElement: HTMLTableSectionElement | null,
+	tbodyElement: HTMLTableSectionElement | null,
+	originalData?: Array<Record<string, unknown>>,
+): number {
+	if (originalData && originalData.length > 0) {
+		return Object.keys(originalData[0]).length;
+	}
+	if (tbodyElement) {
+		const firstRow = tbodyElement.querySelector<HTMLTableRowElement>('tr');
+		if (firstRow) {
+			return firstRow.querySelectorAll('td').length;
+		}
+	}
+	const { columnsByIndex } = resolveColumns(theadElement);
+	return columnsByIndex.length;
+}

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

@@ -11,6 +11,7 @@ import {
 	KTDataTableInterface,
 	KTDataTableSortOrderInterface,
 	KTDataTableStateInterface,
+	OriginalTableClasses,
 } from './types';
 
 export type KTDataTableEmit = (eventName: string, eventData?: object) => void;
@@ -64,9 +65,7 @@ export interface KTDataTableTableRendererInput<
 	data: T[];
 	getLogicalColumnCount: () => number;
 	getState: () => KTDataTableStateInterface;
-	originalTbodyClass: string;
-	originalTrClasses: string[];
-	originalTdClasses: string[][];
+	originalClasses: OriginalTableClasses;
 	tableElement: HTMLTableElement;
 	theadElement: HTMLTableSectionElement;
 }

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

@@ -0,0 +1,204 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import { KTDataTableConfigInterface, KTDataTableStateInterface } from './types';
+
+/** Default page size options shown in the size selector */
+export const DEFAULT_PAGE_SIZES = [5, 10, 20, 30, 50] as const;
+
+/** Default debounce delay (ms) for search input */
+export const DEFAULT_SEARCH_DELAY = 500;
+
+/** Default maximum visible page buttons before showing '...' */
+export const DEFAULT_PAGE_MORE_LIMIT = 3;
+
+/**
+ * Default configuration for KTDataTable.
+ * Extracted from _initDefaultConfig() for separation of concerns.
+ * Note: sort.callback and search.callback are NOT included here because
+ * they require instance context (this._sortHandler). They are added
+ * in datatable.ts _initDefaultConfig().
+ */
+export const DATATABLE_DEFAULTS: Readonly<KTDataTableConfigInterface> = {
+	/**
+	 * HTTP method for server-side API call
+	 */
+	requestMethod: 'GET',
+	/**
+	 * Custom HTTP headers for the API request
+	 */
+	requestHeaders: {
+		'Content-Type': 'application/x-www-form-urlencoded',
+	},
+	/**
+	 * Pagination info template
+	 */
+	info: '{start}-{end} of {total}',
+	/**
+	 * Info text when there is no data
+	 */
+	infoEmpty: 'No records found',
+	/**
+	 * Available page sizes
+	 */
+	pageSizes: [...DEFAULT_PAGE_SIZES],
+	/**
+	 * Default page size
+	 */
+	pageSize: 10,
+	/**
+	 * Enable or disable pagination more button
+	 */
+	pageMore: true,
+	/**
+	 * Maximum number of pages before enabling pagination more button
+	 */
+	pageMoreLimit: 3,
+	/**
+	 * Pagination button templates
+	 */
+	pagination: {
+		number: {
+			/**
+			 * CSS classes to be added to the pagination button
+			 */
+			class: 'kt-datatable-pagination-button',
+			/**
+			 * Text to be displayed in the pagination button
+			 */
+			text: '{page}',
+		},
+		previous: {
+			/**
+			 * CSS classes to be added to the previous pagination button
+			 */
+			class: 'kt-datatable-pagination-button kt-datatable-pagination-prev',
+			/**
+			 * Text to be displayed in the previous pagination button
+			 */
+			text: `
+				<svg class="rtl:transform rtl:rotate-180 size-3.5 shrink-0" width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+					<path d="M8.86501 16.7882V12.8481H21.1459C21.3724 12.8481 21.5897 12.7581 21.7498 12.5979C21.91 12.4378 22 12.2205 22 11.994C22 11.7675 21.91 11.5503 21.7498 11.3901C21.5897 11.2299 21.3724 11.1399 21.1459 11.1399H8.86501V7.2112C8.86628 7.10375 8.83517 6.9984 8.77573 6.90887C8.7163 6.81934 8.63129 6.74978 8.53177 6.70923C8.43225 6.66869 8.32283 6.65904 8.21775 6.68155C8.11267 6.70405 8.0168 6.75766 7.94262 6.83541L2.15981 11.6182C2.1092 11.668 2.06901 11.7274 2.04157 11.7929C2.01413 11.8584 2 11.9287 2 11.9997C2 12.0707 2.01413 12.141 2.04157 12.2065C2.06901 12.272 2.1092 12.3314 2.15981 12.3812L7.94262 17.164C8.0168 17.2417 8.11267 17.2953 8.21775 17.3178C8.32283 17.3403 8.43225 17.3307 8.53177 17.2902C8.63129 17.2496 8.7163 17.18 8.77573 17.0905C8.83517 17.001 8.86628 16.8956 8.86501 16.7882Z" fill="currentColor"/>
+				</svg>
+			`,
+		},
+		next: {
+			/**
+			 * CSS classes to be added to the next pagination button
+			 */
+			class: 'kt-datatable-pagination-button kt-datatable-pagination-next',
+			/**
+			 * Text to be displayed in the next pagination button
+			 */
+			text: `
+				<svg class="rtl:transform rtl:rotate-180 size-3.5 shrink-0" width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+					<path d="M15.135 7.21144V11.1516H2.85407C2.62756 11.1516 2.41032 11.2415 2.25015 11.4017C2.08998 11.5619 2 11.7791 2 12.0056C2 12.2321 2.08998 12.4494 2.25015 12.6096C2.41032 12.7697 2.62756 12.8597 2.85407 12.8597H15.135V16.7884C15.1337 16.8959 15.1648 17.0012 15.2243 17.0908C15.2837 17.1803 15.3687 17.2499 15.4682 17.2904C15.5677 17.3309 15.6772 17.3406 15.7822 17.3181C15.8873 17.2956 15.9832 17.242 16.0574 17.1642L21.8402 12.3814C21.8908 12.3316 21.931 12.2722 21.9584 12.2067C21.9859 12.1412 22 12.0709 22 11.9999C22 11.9289 21.9859 11.8586 21.9584 11.7931C21.931 11.7276 21.8908 11.6683 21.8402 11.6185L16.0574 6.83565C15.9832 6.75791 15.8873 6.70429 15.7822 6.68179C15.6772 6.65929 15.5677 6.66893 15.4682 6.70948C15.3687 6.75002 15.2837 6.81959 15.2243 6.90911C15.1648 6.99864 15.1337 7.10399 15.135 7.21144Z" fill="currentColor"/>
+				</svg>
+			`,
+		},
+		more: {
+			/**
+			 * CSS classes to be added to the pagination more button
+			 */
+			class: 'kt-datatable-pagination-button kt-datatable-pagination-more',
+			/**
+			 * Text to be displayed in the pagination more button
+			 */
+			text: '...',
+		},
+	},
+	/**
+	 * Sorting options — classes only; callback is added in datatable.ts
+	 */
+	sort: {
+		/**
+		 * CSS classes to be added to the sortable headers
+		 */
+		classes: {
+			base: 'kt-table-col',
+			asc: 'asc',
+			desc: 'desc',
+		},
+	},
+	/**
+	 * Search options — delay only; callback is added in datatable.ts
+	 */
+	search: {
+		/**
+		 * Delay in milliseconds before the search function is applied to the data array
+		 * @default 500
+		 */
+		delay: 500, // ms
+	},
+	/**
+	 * Loading spinner options
+	 */
+	loading: {
+		/**
+		 * Template to be displayed during data fetching process
+		 */
+		template: `
+			<div class="absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2">
+				<div class="kt-datatable-loading">
+					<svg class="animate-spin -ml-1 h-5 w-5 text-gray-600" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+						<circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="3"></circle>
+						<path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+					</svg>
+					{content}
+				</div>
+			</div>
+		`,
+		/**
+		 * Loading text to be displayed in the template
+		 */
+		content: 'Loading...',
+	},
+	/**
+	 * Selectors of the elements to be targeted
+	 */
+	attributes: {
+		/**
+		 * Data table element
+		 */
+		table: 'table[data-kt-datatable-table="true"]',
+		/**
+		 * Pagination info element
+		 */
+		info: '[data-kt-datatable-info="true"]',
+		/**
+		 * Page size dropdown element
+		 */
+		size: '[data-kt-datatable-size="true"]',
+		/**
+		 * Pagination element
+		 */
+		pagination: '[data-kt-datatable-pagination="true"]',
+		/**
+		 * Spinner element
+		 */
+		spinner: '[data-kt-datatable-spinner="true"]',
+		/**
+		 * Checkbox element
+		 */
+		check: '[data-kt-datatable-check="true"]',
+		checkbox: '[data-kt-datatable-row-check="true"]',
+	},
+	/**
+	 * Enable or disable state saving
+	 */
+	stateSave: true,
+	checkbox: {
+		checkedClass: 'checked',
+	},
+	/**
+	 * Table layout algorithm: 'auto' (default) or 'fixed' for consistent column widths
+	 */
+	tableLayout: 'auto',
+	/**
+	 * Private properties
+	 */
+	_state: {} as KTDataTableStateInterface,
+	loadingClass: 'loading',
+};

package/src/components/datatable/datatable-layout-plugin.ts

@@ -434,8 +434,18 @@ export const createStickyLayoutPlugin =
 				detachResizeListener();
 				applyLayout(ctx);
 
+				// Throttle re-layout with rAF to avoid running on every resize/scroll event
+				let rafId = 0;
+				const throttledApply = () => {
+					if (rafId) return;
+					rafId = requestAnimationFrame(() => {
+						rafId = 0;
+						applyLayout(ctx);
+					});
+				};
+
 				const scrollContainer = getScrollContainer(ctx.rootElement);
-				resizeHandler = () => applyLayout(ctx);
+				resizeHandler = throttledApply;
 				window.addEventListener('resize', resizeHandler);
 				scrollContainerTarget = scrollContainer;
 				scrollContainer.addEventListener('scroll', resizeHandler);

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

@@ -15,6 +15,34 @@ import {
 	KTDataTableProviderResult,
 	KTDataTableStateStore,
 } from './datatable-contracts';
+import { resolveColumns } from './datatable-column-utils';
+import { stripHtml } from './datatable-utils';
+
+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;
@@ -76,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 &&
@@ -110,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;
 		}
@@ -120,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;
@@ -140,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;
@@ -177,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(
@@ -51,7 +52,7 @@ 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);
@@ -117,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);
 		}