@keenthemes/ktui 1.2.5 → 1.2.7

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

@@ -10,6 +10,19 @@ import {
 	KTDataTableSortOrderInterface,
 	KTDataTableDataInterface,
 } from './types';
+import { stripHtml } from './datatable-utils';
+
+export interface KTDataTableSortHandlerDeps<T> {
+	config: KTDataTableConfigInterface;
+	theadElement: HTMLTableSectionElement;
+	getState: () => {
+		sortField: keyof T | number;
+		sortOrder: KTDataTableSortOrderInterface;
+	};
+	setState: (field: keyof T | number, order: KTDataTableSortOrderInterface) => void;
+	emit: (eventName: string, eventData?: object) => void;
+	updateData: () => void;
+}
 
 export interface KTDataTableSortAPI<T = KTDataTableDataInterface> {
 	initSort(): void;
@@ -27,31 +40,42 @@ export interface KTDataTableSortAPI<T = KTDataTableDataInterface> {
 		sortField: keyof T,
 		sortOrder: KTDataTableSortOrderInterface,
 	): void;
+	dispose(): void;
 }
 
-export function createSortHandler<T = KTDataTableDataInterface>(
-	config: KTDataTableConfigInterface,
-	theadElement: HTMLTableSectionElement,
-	getState: () => {
+export class KTDataTableSortHandler<T = KTDataTableDataInterface>
+	implements KTDataTableSortAPI<T>
+{
+	private _config: KTDataTableConfigInterface;
+	private _theadElement: HTMLTableSectionElement;
+	private _getState: () => {
 		sortField: keyof T | number;
 		sortOrder: KTDataTableSortOrderInterface;
-	},
-	setState: (
+	};
+	private _setState: (
 		field: keyof T | number,
 		order: KTDataTableSortOrderInterface,
-	) => void,
-	fireEvent: (eventName: string, eventData?: object) => void,
-	dispatchEvent: (eventName: string, eventData?: object) => void,
-	updateData: () => void,
-): KTDataTableSortAPI<T> {
-	// Helper to compare values for sorting (string)
-	function compareValues(
+	) => void;
+	private _emit: (eventName: string, eventData?: object) => void;
+	private _updateData: () => void;
+	private _sortAbortController: AbortController | null = null;
+
+	constructor(deps: KTDataTableSortHandlerDeps<T>) {
+		this._config = deps.config;
+		this._theadElement = deps.theadElement;
+		this._getState = deps.getState;
+		this._setState = deps.setState;
+		this._emit = deps.emit;
+		this._updateData = deps.updateData;
+	}
+
+	private static _compareValues(
 		a: unknown,
 		b: unknown,
 		sortOrder: KTDataTableSortOrderInterface,
 	): number {
-		const aText = String(a).replace(/<[^>]*>|&nbsp;/g, '');
-		const bText = String(b).replace(/<[^>]*>|&nbsp;/g, '');
+		const aText = stripHtml(a);
+		const bText = stripHtml(b);
 		return aText > bText
 			? sortOrder === 'asc'
 				? 1
@@ -63,8 +87,7 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 				: 0;
 	}
 
-	// Parse value for numeric sort: strip currency/commas, then parseFloat
-	function parseNumeric(value: unknown): number {
+	private static _parseNumeric(value: unknown): number {
 		if (value === null || value === undefined || value === '') {
 			return Number.NaN;
 		}
@@ -73,8 +96,7 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 		return Number.isNaN(n) ? Number.NaN : n;
 	}
 
-	// Compare two numbers; NaN sorts to the end for both asc and desc
-	function compareNumeric(
+	private static _compareNumeric(
 		aNum: number,
 		bNum: number,
 		sortOrder: KTDataTableSortOrderInterface,
@@ -89,7 +111,7 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 		return 0;
 	}
 
-	function getColumnDef(sortField: keyof T | number):
+	private _getColumnDef(sortField: keyof T | number):
 		| {
 				sortType?: 'string' | 'numeric';
 				sortValue?: (
@@ -100,7 +122,7 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 				) => number | string;
 		  }
 		| undefined {
-		const columns = config.columns;
+		const columns = this._config.columns;
 		if (!columns) return undefined;
 		const key =
 			typeof sortField === 'number'
@@ -109,15 +131,25 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 		return key !== undefined ? columns[key as string] : undefined;
 	}
 
-	function sortData(
+	public sortData(
 		data: T[],
 		sortField: keyof T | number,
 		sortOrder: KTDataTableSortOrderInterface,
 	): T[] {
-		const columnDef = getColumnDef(sortField);
+		const columnDef = this._getColumnDef(sortField);
 		const sortValueFn = columnDef?.sortValue;
 		const useNumeric = !sortValueFn && columnDef?.sortType === 'numeric';
 
+		// Pre-strip HTML from cell values once (instead of on every comparison).
+		// For N rows this runs N regex replacements instead of N*log(N).
+		const strippedCache = new Map<T, string>();
+
+		if (!sortValueFn) {
+			for (const item of data) {
+				strippedCache.set(item, stripHtml(item[sortField as keyof T]));
+			}
+		}
+
 		return data.sort((a, b) => {
 			const aRaw = a[sortField as keyof T] as unknown;
 			const bRaw = b[sortField as keyof T] as unknown;
@@ -135,31 +167,33 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 						| string,
 					b as KTDataTableDataInterface,
 				);
-				const aNum = typeof aVal === 'number' ? aVal : parseNumeric(aVal);
-				const bNum = typeof bVal === 'number' ? bVal : parseNumeric(bVal);
+				const aNum =
+					typeof aVal === 'number'
+						? aVal
+						: KTDataTableSortHandler._parseNumeric(aVal);
+				const bNum =
+					typeof bVal === 'number'
+						? bVal
+						: KTDataTableSortHandler._parseNumeric(bVal);
 				if (typeof aVal === 'number' && typeof bVal === 'number') {
-					return compareNumeric(aNum, bNum, sortOrder);
+					return KTDataTableSortHandler._compareNumeric(aNum, bNum, sortOrder);
 				}
-				return compareValues(aVal, bVal, sortOrder);
+				return KTDataTableSortHandler._compareValues(aVal, bVal, sortOrder);
 			}
 			if (useNumeric) {
-				const aNum = parseNumeric(
-					aRaw as
-						| KTDataTableDataInterface[keyof KTDataTableDataInterface]
-						| string,
-				);
-				const bNum = parseNumeric(
-					bRaw as
-						| KTDataTableDataInterface[keyof KTDataTableDataInterface]
-						| string,
-				);
-				return compareNumeric(aNum, bNum, sortOrder);
+				const aNum = KTDataTableSortHandler._parseNumeric(strippedCache.get(a) ?? aRaw);
+				const bNum = KTDataTableSortHandler._parseNumeric(strippedCache.get(b) ?? bRaw);
+				return KTDataTableSortHandler._compareNumeric(aNum, bNum, sortOrder);
 			}
-			return compareValues(aRaw, bRaw, sortOrder);
+			return KTDataTableSortHandler._compareValues(
+				strippedCache.get(a) ?? aRaw,
+				strippedCache.get(b) ?? bRaw,
+				sortOrder,
+			);
 		});
 	}
 
-	function toggleSortOrder(
+	public toggleSortOrder(
 		currentField: keyof T | number,
 		currentOrder: KTDataTableSortOrderInterface,
 		newField: keyof T | number,
@@ -177,18 +211,17 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 		return 'asc';
 	}
 
-	function setSortIcon(
+	public setSortIcon(
 		sortField: keyof T,
 		sortOrder: KTDataTableSortOrderInterface,
 	): void {
-		const baseClass = config.sort?.classes?.base || '';
+		const baseClass = this._config.sort?.classes?.base || '';
 		const sortClass = sortOrder
 			? sortOrder === 'asc'
-				? config.sort?.classes?.asc || ''
-				: config.sort?.classes?.desc || ''
+				? this._config.sort?.classes?.asc || ''
+				: this._config.sort?.classes?.desc || ''
 			: '';
-		// Clear all headers: remove sort state so only the active column shows highlighted arrow
-		const allTh = theadElement.querySelectorAll('th');
+		const allTh = this._theadElement.querySelectorAll('th');
 		allTh.forEach((header) => {
 			const el = header as HTMLElement;
 			el.setAttribute('aria-sort', 'none');
@@ -197,11 +230,10 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 				sortElement.className = baseClass;
 			}
 		});
-		// Apply sort state to the active column so table.css [aria-sort='asc'] / [aria-sort='desc'] can highlight the arrow
 		const th =
 			typeof sortField === 'number'
 				? allTh[sortField]
-				: (theadElement.querySelector(
+				: (this._theadElement.querySelector(
 						`th[data-kt-datatable-column="${String(sortField)}"], th[data-kt-datatable-column-sort="${String(sortField)}"]`,
 					) as HTMLElement);
 		if (th) {
@@ -217,17 +249,25 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 		}
 	}
 
-	function initSort(): void {
-		if (!theadElement) return;
-		// Set the initial sort icon
-		setSortIcon(getState().sortField as keyof T, getState().sortOrder);
-		// Get all the table headers
-		const headers = Array.from(theadElement.querySelectorAll('th'));
+	public initSort(): void {
+		if (!this._theadElement) return;
+
+		// Abort previous sort listeners before attaching new ones
+		if (this._sortAbortController) {
+			this._sortAbortController.abort();
+		}
+		this._sortAbortController = new AbortController();
+		const signal = this._sortAbortController.signal;
+
+		this.setSortIcon(
+			this._getState().sortField as keyof T,
+			this._getState().sortOrder,
+		);
+		const headers = Array.from(this._theadElement.querySelectorAll('th'));
 		headers.forEach((header) => {
-			// If the sort class is not found, it's not a sortable column
-			if (!header.querySelector(`.${config.sort?.classes?.base}`)) return;
+			if (!header.querySelector(`.${this._config.sort?.classes?.base}`))
+				return;
 
-			// Check if sorting is disabled for this column
 			const sortDisabled =
 				header.getAttribute('data-kt-datatable-column-sort') === 'false';
 			if (sortDisabled) return;
@@ -239,20 +279,25 @@ export function createSortHandler<T = KTDataTableDataInterface>(
 				? (sortAttribute as keyof T)
 				: (header.cellIndex as keyof T);
 			header.addEventListener('click', () => {
-				const state = getState();
-				const sortOrder = toggleSortOrder(
+				const state = this._getState();
+				const sortOrder = this.toggleSortOrder(
 					state.sortField,
 					state.sortOrder,
 					sortField,
 				);
-				setSortIcon(sortField, sortOrder);
-				setState(sortField, sortOrder);
-				fireEvent('sort', { field: sortField, order: sortOrder });
-				dispatchEvent('sort', { field: sortField, order: sortOrder });
-				updateData();
-			});
+				this.setSortIcon(sortField, sortOrder);
+				this._setState(sortField, sortOrder);
+				this._emit('sort', { field: sortField, order: sortOrder });
+				this._updateData();
+			}, { signal });
 		});
 	}
 
-	return { initSort, sortData, toggleSortOrder, setSortIcon };
+	public dispose(): void {
+		if (this._sortAbortController) {
+			this._sortAbortController.abort();
+			this._sortAbortController = null;
+		}
+	}
 }
+

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

@@ -0,0 +1,103 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+export interface KTDataTableSpinner {
+	show(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+			loading?: { template: string; content: string };
+		},
+		tableElement: HTMLTableElement,
+	): void;
+	hide(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+		},
+	): void;
+	remove(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+		},
+	): void;
+}
+
+export function createSpinner(): KTDataTableSpinner {
+	function findSpinner(
+		root: HTMLElement | null,
+		spinnerSel: string | undefined,
+	): HTMLElement | null {
+		return root && spinnerSel
+			? root.querySelector<HTMLElement>(spinnerSel)
+			: null;
+	}
+
+	function createSpinnerElement(
+		tableElement: HTMLTableElement,
+		loading: { template: string; content: string },
+	): HTMLElement | null {
+		const template = document.createElement('template');
+		template.innerHTML = loading.template
+			.trim()
+			.replace('{content}', loading.content);
+		const first = template.content.firstChild;
+		if (!first || !(first instanceof HTMLElement)) return null;
+		const spinner = first;
+		spinner.setAttribute('data-kt-datatable-spinner', 'true');
+		tableElement.appendChild(spinner);
+		return spinner;
+	}
+
+	function show(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+			loading?: { template: string; content: string };
+		},
+		tableElement: HTMLTableElement,
+	): void {
+		const spinnerSel = config.attributes?.spinner;
+		const fromDom = findSpinner(root, spinnerSel);
+		const spinner =
+			fromDom ??
+			(config.loading
+				? createSpinnerElement(tableElement, config.loading)
+				: null);
+		if (spinner) spinner.style.display = 'block';
+		root?.classList.add(config.loadingClass ?? 'loading');
+	}
+
+	function hide(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+		},
+	): void {
+		const spinner = findSpinner(root, config.attributes?.spinner);
+		if (spinner) spinner.style.display = 'none';
+		root?.classList.remove(config.loadingClass ?? 'loading');
+	}
+
+	function remove(
+		root: HTMLElement | null,
+		config: {
+			attributes?: { spinner?: string };
+			loadingClass?: string;
+		},
+	): void {
+		const spinner = findSpinner(root, config.attributes?.spinner);
+		if (spinner?.parentNode) spinner.parentNode.removeChild(spinner);
+		root?.classList.remove(config.loadingClass ?? 'loading');
+	}
+
+	return { show, hide, remove };
+}

package/src/components/datatable/datatable-state-persistence.ts

@@ -0,0 +1,67 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import { KTDataTableStateInterface } from './types';
+
+export interface KTDataTableStatePersistence {
+	save(namespace: string, state: KTDataTableStateInterface): void;
+	load(namespace: string): KTDataTableStateInterface | null;
+	remove(namespace: string): void;
+}
+
+export function createStatePersistence(): KTDataTableStatePersistence {
+	function save(namespace: string, state: KTDataTableStateInterface): void {
+		if (namespace) {
+			try {
+				localStorage.setItem(namespace, JSON.stringify(state));
+			} catch {
+				// localStorage unavailable (e.g. Node.js without --localstorage-file)
+			}
+		}
+	}
+
+	function load(namespace: string): KTDataTableStateInterface | null {
+		try {
+			const stateString = localStorage.getItem(namespace);
+			if (!stateString) return null;
+
+			return JSON.parse(stateString) as KTDataTableStateInterface;
+		} catch {
+			return null;
+		}
+	}
+
+	function remove(namespace: string): void {
+		if (namespace) {
+			try {
+				localStorage.removeItem(namespace);
+			} catch {
+				// localStorage unavailable
+			}
+		}
+	}
+
+	return { save, load, remove };
+}
+
+/**
+ * Resolve the namespace for a datatable state key.
+ * Priority: config.stateNamespace > table element ID > root element ID > fallback name.
+ */
+export function resolveTableNamespace(
+	config: { stateNamespace?: string },
+	tableElement: HTMLTableElement | null,
+	rootElement: HTMLElement | null,
+	fallbackName: string,
+): string {
+	if (config.stateNamespace) {
+		return config.stateNamespace;
+	}
+	const tableIdAttr = tableElement?.getAttribute('id');
+	if (tableIdAttr) return tableIdAttr;
+	const rootIdAttr = rootElement?.getAttribute('id');
+	if (rootIdAttr) return rootIdAttr;
+	return fallbackName;
+}

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

@@ -12,6 +12,7 @@ import {
 	KTDataTableTableRenderer,
 	KTDataTableTableRendererInput,
 } from './datatable-contracts';
+import { resolveColumns } from './datatable-column-utils';
 
 export class KTDataTableDomTableRenderer<
 	T extends KTDataTableDataInterface,
@@ -26,10 +27,12 @@ export class KTDataTableDomTableRenderer<
 		const tbodyElement =
 			input.tableElement.createTBody() as HTMLTableSectionElement;
 
-		if (input.originalTbodyClass) {
-			tbodyElement.className = input.originalTbodyClass;
+		if (input.originalClasses.tbody) {
+			tbodyElement.className = input.originalClasses.tbody;
 		}
 
+		this.applyTableLayout(input);
+
 		this.renderContent(input, tbodyElement);
 
 		return tbodyElement;
@@ -44,9 +47,71 @@ export class KTDataTableDomTableRenderer<
 		const cell = row.insertCell();
 		const logicalCount = getLogicalColumnCount();
 		cell.colSpan = logicalCount > 0 ? logicalCount : 1;
+		cell.style.textAlign = 'center';
 		cell.innerHTML = message;
 	}
 
+	private applyTableLayout(
+		input: KTDataTableTableRendererInput<T>,
+	): void {
+		const tableLayout = input.config.tableLayout || 'auto';
+		const tableElement = input.tableElement;
+
+		tableElement.style.tableLayout = tableLayout;
+
+		if (tableLayout === 'fixed') {
+			if (!tableElement.style.width) {
+				tableElement.style.width = '100%';
+			}
+			this.updateColgroup(input);
+		} else {
+			const existingColgroup = tableElement.querySelector('colgroup');
+			if (existingColgroup) {
+				tableElement.removeChild(existingColgroup);
+			}
+		}
+	}
+
+	private updateColgroup(
+		input: KTDataTableTableRendererInput<T>,
+	): void {
+		const tableElement = input.tableElement;
+		const existingColgroup = tableElement.querySelector('colgroup');
+		if (existingColgroup) {
+			tableElement.removeChild(existingColgroup);
+		}
+
+		const colgroup = document.createElement('colgroup');
+
+		if (input.config.columns) {
+			const columns = input.config.columns;
+			for (const key of Object.keys(columns)) {
+				const col = document.createElement('col');
+				if (columns[key].width) {
+					col.style.width = columns[key].width;
+				}
+				colgroup.appendChild(col);
+			}
+		} else {
+			const { columnsByIndex } = resolveColumns(input.theadElement);
+			for (const th of columnsByIndex) {
+				const col = document.createElement('col');
+				const width = th.getAttribute('data-kt-datatable-column-width');
+				if (width) {
+					col.style.width = width;
+				}
+				colgroup.appendChild(col);
+			}
+		}
+
+		const thead = tableElement.querySelector('thead');
+		if (thead) {
+			tableElement.insertBefore(colgroup, thead);
+		} else {
+			tableElement.appendChild(colgroup);
+		}
+	}
+
 	private renderContent(
 		input: KTDataTableTableRendererInput<T>,
 		tbodyElement: HTMLTableSectionElement,
@@ -64,15 +129,7 @@ export class KTDataTableDomTableRenderer<
 			return tbodyElement;
 		}
 
-		const allThs: NodeListOf<HTMLTableCellElement> = input.theadElement
-			? input.theadElement.querySelectorAll('th')
-			: ([] as unknown as NodeListOf<HTMLTableCellElement>);
-
-		const ths: HTMLTableCellElement[] = Array.from(allThs).filter((th) =>
-			th.hasAttribute('data-kt-datatable-column'),
-		);
-		const columnsToRender: HTMLTableCellElement[] =
-			ths.length > 0 && ths.length !== allThs.length ? Array.from(allThs) : ths;
+		const { columnsByIndex: columnsToRender } = resolveColumns(input.theadElement);
 		const logicalColumnCount =
 			columnsToRender.length > 0
 				? columnsToRender.length
@@ -81,8 +138,8 @@ export class KTDataTableDomTableRenderer<
 		input.data.forEach((item: T, rowIndex: number) => {
 			const row = document.createElement('tr');
 
-			if (input.originalTrClasses && input.originalTrClasses[rowIndex]) {
-				row.className = input.originalTrClasses[rowIndex];
+			if (input.originalClasses.tr && input.originalClasses.tr[rowIndex]) {
+				row.className = input.originalClasses.tr[rowIndex];
 			}
 
 			if (!input.config.columns) {
@@ -174,7 +231,13 @@ export class KTDataTableDomTableRenderer<
 					td.innerHTML = result as string;
 				}
 			} else {
-				td.textContent = item[colKey] as string;
+				const cellValue = item[colKey];
+				if (cellValue === null || cellValue === undefined) {
+					td.textContent = '';
+				} else {
+					// Match implicit column rendering: preserve HTML from DOM extraction.
+					td.innerHTML = String(cellValue);
+				}
 			}
 
 			if (typeof columnDef.createdCell === 'function') {
@@ -192,11 +255,11 @@ export class KTDataTableDomTableRenderer<
 		colIndex: number,
 	): void {
 		if (
-			input.originalTdClasses &&
-			input.originalTdClasses[rowIndex] &&
-			input.originalTdClasses[rowIndex][colIndex]
+			input.originalClasses.td &&
+			input.originalClasses.td[rowIndex] &&
+			input.originalClasses.td[rowIndex][colIndex]
 		) {
-			td.className = input.originalTdClasses[rowIndex][colIndex];
+			td.className = input.originalClasses.td[rowIndex][colIndex];
 		}
 	}
 

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

@@ -0,0 +1,12 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+/**
+ * Strip HTML tags and   entities from a value, returning plain text.
+ * Used by sort, search, and filter pipelines.
+ */
+export function stripHtml(value: unknown): string {
+	return String(value).replace(/<[^>]*>|&nbsp;/g, '');
+}