@keenthemes/ktui 1.2.4 → 1.2.6

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

@@ -0,0 +1,449 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableConfigInterface,
+	KTDataTableLayoutPluginContextInterface,
+	KTDataTableLayoutPluginInterface,
+} from './types';
+
+type Edge = 'left' | 'right';
+
+const LOCKED_CELL_CLASS = 'kt-datatable-locked-cell';
+const LOCKED_HEADER_CLASS = 'kt-datatable-locked-header';
+const LOCKED_TOP_ROW_CLASS = 'kt-datatable-locked-top-row';
+const LOCKED_BOTTOM_ROW_CLASS = 'kt-datatable-locked-bottom-row';
+const LOCKED_LEFT_CLASS = 'kt-datatable-locked-left';
+const LOCKED_RIGHT_CLASS = 'kt-datatable-locked-right';
+const LOCKED_LAYOUT_SEPARATE_CLASS = 'kt-datatable-locked-layout-separate';
+const LOCKED_HEADER_SECTION_CLASS = 'kt-datatable-locked-header-section';
+
+const HEADER_Z_INDEX = 40;
+const ROW_Z_INDEX = 30;
+const COLUMN_Z_INDEX = 35;
+const INTERSECTION_Z_INDEX = 45;
+
+const toPositiveInteger = (value: number | undefined): number => {
+	if (typeof value !== 'number' || !Number.isFinite(value)) {
+		return 0;
+	}
+
+	return Math.max(0, Math.floor(value));
+};
+
+const hasStickyColumns = (config: KTDataTableConfigInterface): boolean => {
+	const lockedLayout = config.lockedLayout;
+	if (!lockedLayout?.stickyColumns) {
+		return false;
+	}
+
+	return (
+		(lockedLayout.stickyColumns.left?.length || 0) > 0 ||
+		(lockedLayout.stickyColumns.right?.length || 0) > 0
+	);
+};
+
+const hasLockedLayoutConfig = (config: KTDataTableConfigInterface): boolean => {
+	const lockedLayout = config.lockedLayout;
+	if (!lockedLayout) {
+		return false;
+	}
+
+	return (
+		lockedLayout.stickyHeader === true ||
+		toPositiveInteger(lockedLayout.stickyRows?.top) > 0 ||
+		toPositiveInteger(lockedLayout.stickyRows?.bottom) > 0 ||
+		(lockedLayout.stickyColumns?.left?.length || 0) > 0 ||
+		(lockedLayout.stickyColumns?.right?.length || 0) > 0
+	);
+};
+
+const getScrollContainer = (rootElement: HTMLElement): HTMLElement => {
+	return (
+		rootElement.closest<HTMLElement>('.kt-table-wrapper') ||
+		rootElement.querySelector<HTMLElement>('.kt-table-wrapper') ||
+		rootElement
+	);
+};
+
+const clearStickyStyles = (
+	tableElement: HTMLTableElement,
+	scrollContainer: HTMLElement,
+): void => {
+	tableElement.classList.remove(
+		'kt-datatable-locked-layout',
+		LOCKED_LAYOUT_SEPARATE_CLASS,
+	);
+	scrollContainer.classList.remove('kt-datatable-locked-layout-host');
+	tableElement.style.borderCollapse = '';
+	tableElement.style.borderSpacing = '';
+
+	const theadElement = tableElement.tHead;
+	if (theadElement) {
+		theadElement.classList.remove(LOCKED_HEADER_SECTION_CLASS);
+		theadElement.style.position = '';
+		theadElement.style.top = '';
+		theadElement.style.zIndex = '';
+	}
+
+	const stickyElements = tableElement.querySelectorAll<HTMLElement>(
+		`.${LOCKED_CELL_CLASS}`,
+	);
+
+	stickyElements.forEach((element) => {
+		element.classList.remove(
+			LOCKED_CELL_CLASS,
+			LOCKED_HEADER_CLASS,
+			LOCKED_TOP_ROW_CLASS,
+			LOCKED_BOTTOM_ROW_CLASS,
+			LOCKED_LEFT_CLASS,
+			LOCKED_RIGHT_CLASS,
+		);
+		element.style.position = '';
+		element.style.top = '';
+		element.style.bottom = '';
+		element.style.left = '';
+		element.style.right = '';
+		element.style.zIndex = '';
+		element.style.backgroundColor = '';
+	});
+};
+
+const getDirection = (tableElement: HTMLTableElement): 'ltr' | 'rtl' => {
+	const scopedDir = tableElement
+		.closest<HTMLElement>('[dir]')
+		?.getAttribute('dir');
+	const globalDir =
+		typeof document !== 'undefined'
+			? document.documentElement.getAttribute('dir')
+			: null;
+	return scopedDir === 'rtl' || globalDir === 'rtl' ? 'rtl' : 'ltr';
+};
+
+const resolveEdgeProperty = (edge: Edge, direction: 'ltr' | 'rtl'): Edge => {
+	if (direction === 'rtl') {
+		return edge === 'left' ? 'right' : 'left';
+	}
+
+	return edge;
+};
+
+const setStickyEdge = (
+	element: HTMLElement,
+	edge: Edge,
+	offset: number,
+	direction: 'ltr' | 'rtl',
+): void => {
+	const resolvedEdge = resolveEdgeProperty(edge, direction);
+	if (resolvedEdge === 'left') {
+		element.style.left = `${offset}px`;
+		element.style.right = '';
+	} else {
+		element.style.right = `${offset}px`;
+		element.style.left = '';
+	}
+};
+
+const ensureStickyCell = (
+	element: HTMLElement,
+	className: string,
+	zIndex: number,
+): void => {
+	element.classList.add(LOCKED_CELL_CLASS, className);
+	element.style.position = 'sticky';
+	element.style.zIndex = String(zIndex);
+};
+
+const measureStickyHeaderHeight = (
+	theadElement: HTMLTableSectionElement,
+): number => Math.round(theadElement.offsetHeight);
+
+/** Offset for top sticky body rows so they sit flush under a sticky header. */
+const getStickyTopRowOffset = (
+	headerHeight: number,
+	useCollapsedBorders: boolean,
+): number => {
+	if (headerHeight <= 0) {
+		return 0;
+	}
+
+	// Collapsed row borders are shared between thead and the first tbody row.
+	return useCollapsedBorders ? headerHeight - 1 : headerHeight;
+};
+
+const markIntersectionZIndex = (element: HTMLElement): void => {
+	const isRowLocked =
+		element.classList.contains(LOCKED_HEADER_CLASS) ||
+		element.classList.contains(LOCKED_TOP_ROW_CLASS) ||
+		element.classList.contains(LOCKED_BOTTOM_ROW_CLASS);
+	const isColumnLocked =
+		element.classList.contains(LOCKED_LEFT_CLASS) ||
+		element.classList.contains(LOCKED_RIGHT_CLASS);
+
+	if (isRowLocked && isColumnLocked) {
+		element.style.zIndex = String(INTERSECTION_Z_INDEX);
+	}
+};
+
+const applyStickyHeader = (
+	theadElement: HTMLTableSectionElement,
+	enabled: boolean,
+	useSectionSticky: boolean,
+): number => {
+	if (!enabled) {
+		return 0;
+	}
+
+	if (useSectionSticky) {
+		theadElement.classList.add(LOCKED_HEADER_SECTION_CLASS);
+		theadElement.style.position = 'sticky';
+		theadElement.style.top = '0';
+		theadElement.style.zIndex = String(HEADER_Z_INDEX);
+
+		Array.from(theadElement.rows).forEach((row) => {
+			Array.from(row.cells).forEach((cell) => {
+				const headerCell = cell as HTMLTableCellElement;
+				headerCell.classList.add(LOCKED_CELL_CLASS, LOCKED_HEADER_CLASS);
+			});
+		});
+
+		return measureStickyHeaderHeight(theadElement);
+	}
+
+	let cumulativeTop = 0;
+	Array.from(theadElement.rows).forEach((row) => {
+		const rowTop = cumulativeTop;
+		Array.from(row.cells).forEach((cell) => {
+			const headerCell = cell as HTMLTableCellElement;
+			ensureStickyCell(headerCell, LOCKED_HEADER_CLASS, HEADER_Z_INDEX);
+			headerCell.style.top = `${rowTop}px`;
+		});
+		cumulativeTop += row.offsetHeight;
+	});
+
+	return cumulativeTop;
+};
+
+const applyStickyRows = (
+	tbodyElement: HTMLTableSectionElement,
+	headerHeight: number,
+	topCount: number,
+	bottomCount: number,
+	useCollapsedBorders: boolean,
+): void => {
+	const rows = Array.from(tbodyElement.rows);
+
+	let topOffset = getStickyTopRowOffset(headerHeight, useCollapsedBorders);
+	rows.slice(0, topCount).forEach((row) => {
+		const rowTop = topOffset;
+		Array.from(row.cells).forEach((cell) => {
+			const td = cell as HTMLTableCellElement;
+			ensureStickyCell(td, LOCKED_TOP_ROW_CLASS, ROW_Z_INDEX);
+			td.style.top = `${rowTop}px`;
+		});
+		topOffset += row.offsetHeight;
+	});
+
+	let bottomOffset = 0;
+	rows
+		.slice(Math.max(0, rows.length - bottomCount))
+		.reverse()
+		.forEach((row) => {
+			const rowBottom = bottomOffset;
+			Array.from(row.cells).forEach((cell) => {
+				const td = cell as HTMLTableCellElement;
+				ensureStickyCell(td, LOCKED_BOTTOM_ROW_CLASS, ROW_Z_INDEX);
+				td.style.bottom = `${rowBottom}px`;
+			});
+			bottomOffset += row.offsetHeight;
+		});
+};
+
+const getColumnIndexMap = (
+	theadElement: HTMLTableSectionElement,
+	config: KTDataTableConfigInterface,
+): Map<string, number> => {
+	const map = new Map<string, number>();
+	const typedHeaders = Array.from(
+		theadElement.querySelectorAll<HTMLTableCellElement>(
+			'th[data-kt-datatable-column]',
+		),
+	);
+
+	if (typedHeaders.length > 0) {
+		typedHeaders.forEach((th, index) => {
+			const column = th.getAttribute('data-kt-datatable-column');
+			if (column) {
+				map.set(column, index);
+			}
+		});
+		return map;
+	}
+
+	if (config.columns) {
+		Object.keys(config.columns).forEach((key, index) => {
+			map.set(key, index);
+		});
+	}
+
+	return map;
+};
+
+const getColumnCells = (
+	tableElement: HTMLTableElement,
+	columnIndex: number,
+): HTMLTableCellElement[] => {
+	const cells: HTMLTableCellElement[] = [];
+	tableElement.querySelectorAll('tr').forEach((row) => {
+		const cell = row.children.item(columnIndex);
+		if (cell instanceof HTMLTableCellElement) {
+			cells.push(cell);
+		}
+	});
+	return cells;
+};
+
+const applyStickyColumns = (
+	tableElement: HTMLTableElement,
+	theadElement: HTMLTableSectionElement,
+	config: KTDataTableConfigInterface,
+): void => {
+	const lockedColumns = config.lockedLayout?.stickyColumns;
+	if (!lockedColumns) {
+		return;
+	}
+
+	const direction = getDirection(tableElement);
+	const columnMap = getColumnIndexMap(theadElement, config);
+
+	let leftOffset = 0;
+	(lockedColumns.left || []).forEach((key) => {
+		const index = columnMap.get(key);
+		if (typeof index !== 'number') {
+			return;
+		}
+
+		const cells = getColumnCells(tableElement, index);
+		if (cells.length === 0) {
+			return;
+		}
+
+		const width = cells[0].getBoundingClientRect().width;
+		cells.forEach((cell) => {
+			ensureStickyCell(cell, LOCKED_LEFT_CLASS, COLUMN_Z_INDEX);
+			setStickyEdge(cell, 'left', leftOffset, direction);
+		});
+		leftOffset += width;
+	});
+
+	let rightOffset = 0;
+	[...(lockedColumns.right || [])].reverse().forEach((key) => {
+		const index = columnMap.get(key);
+		if (typeof index !== 'number') {
+			return;
+		}
+
+		const cells = getColumnCells(tableElement, index);
+		if (cells.length === 0) {
+			return;
+		}
+
+		const width = cells[0].getBoundingClientRect().width;
+		cells.forEach((cell) => {
+			ensureStickyCell(cell, LOCKED_RIGHT_CLASS, COLUMN_Z_INDEX);
+			setStickyEdge(cell, 'right', rightOffset, direction);
+		});
+		rightOffset += width;
+	});
+
+	tableElement
+		.querySelectorAll<HTMLElement>(`.${LOCKED_CELL_CLASS}`)
+		.forEach(markIntersectionZIndex);
+};
+
+export const createStickyLayoutPlugin =
+	(): KTDataTableLayoutPluginInterface => {
+		let resizeHandler: (() => void) | null = null;
+		let scrollContainerTarget: HTMLElement | null = null;
+		let isApplying = false;
+
+		const applyLayout = (
+			ctx: KTDataTableLayoutPluginContextInterface,
+		): void => {
+			if (isApplying || !hasLockedLayoutConfig(ctx.config)) {
+				return;
+			}
+
+			isApplying = true;
+			try {
+				const scrollContainer = getScrollContainer(ctx.rootElement);
+				clearStickyStyles(ctx.tableElement, scrollContainer);
+				ctx.tableElement.classList.add('kt-datatable-locked-layout');
+				scrollContainer.classList.add('kt-datatable-locked-layout-host');
+
+				if (hasStickyColumns(ctx.config)) {
+					ctx.tableElement.classList.add(LOCKED_LAYOUT_SEPARATE_CLASS);
+					ctx.tableElement.style.borderCollapse = 'separate';
+					ctx.tableElement.style.borderSpacing = '0';
+				}
+
+				const lockedLayout = ctx.config.lockedLayout || {};
+				const useCollapsedBorders = !hasStickyColumns(ctx.config);
+				const headerHeight = applyStickyHeader(
+					ctx.theadElement,
+					lockedLayout.stickyHeader === true,
+					useCollapsedBorders,
+				);
+
+				applyStickyRows(
+					ctx.tbodyElement,
+					headerHeight,
+					toPositiveInteger(lockedLayout.stickyRows?.top),
+					toPositiveInteger(lockedLayout.stickyRows?.bottom),
+					useCollapsedBorders,
+				);
+
+				applyStickyColumns(ctx.tableElement, ctx.theadElement, ctx.config);
+			} finally {
+				isApplying = false;
+			}
+		};
+
+		const detachResizeListener = (): void => {
+			if (!resizeHandler) {
+				return;
+			}
+
+			window.removeEventListener('resize', resizeHandler);
+			if (scrollContainerTarget) {
+				scrollContainerTarget.removeEventListener('scroll', resizeHandler);
+			}
+
+			resizeHandler = null;
+			scrollContainerTarget = null;
+		};
+
+		return {
+			beforeDraw: (ctx) => {
+				const scrollContainer = getScrollContainer(ctx.rootElement);
+				clearStickyStyles(ctx.tableElement, scrollContainer);
+			},
+			afterDraw: (ctx) => {
+				detachResizeListener();
+				applyLayout(ctx);
+
+				const scrollContainer = getScrollContainer(ctx.rootElement);
+				resizeHandler = () => applyLayout(ctx);
+				window.addEventListener('resize', resizeHandler);
+				scrollContainerTarget = scrollContainer;
+				scrollContainer.addEventListener('scroll', resizeHandler);
+			},
+			dispose: (ctx) => {
+				detachResizeListener();
+				const scrollContainer = getScrollContainer(ctx.rootElement);
+				clearStickyStyles(ctx.tableElement, scrollContainer);
+			},
+		};
+	};

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

@@ -8,7 +8,6 @@ import {
 	KTDataTableAttributeInterface,
 	KTDataTableConfigInterface,
 	KTDataTableDataInterface,
-	KTDataTableStateInterface,
 } from './types';
 import {
 	KTDataTableDataProvider,
@@ -17,7 +16,7 @@ import {
 	KTDataTableStateStore,
 } from './datatable-contracts';
 
-interface KTDataTableLocalProviderOptions<T extends KTDataTableDataInterface> {
+interface KTDataTableLocalProviderOptions {
 	config: KTDataTableConfigInterface;
 	elements: () => KTDataTableLocalProviderElements;
 	getLogicalColumnCount: () => number;
@@ -28,7 +27,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 +36,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();
@@ -63,20 +66,24 @@ export class KTDataTableLocalDataProvider<
 
 		if (search) {
 			const searchTerm = typeof search === 'string' ? search : '';
-			filteredData = data = this.options.config.search.callback.call(
-				this,
-				data,
-				searchTerm,
-			) as T[];
+			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 this.options.config.sort.callback === 'function'
+			typeof sortCallback === 'function'
 		) {
-			data = this.options.config.sort.callback.call(
+			data = sortCallback.call(
 				this,
 				data,
 				sortField as string,
@@ -114,7 +121,7 @@ export class KTDataTableLocalDataProvider<
 		const { _state, ...restConfig } = this.options.config;
 		const checksum: string = KTUtils.checksum(JSON.stringify(restConfig));
 
-		if (_state._configChecksum !== checksum) {
+		if ((_state?._configChecksum ?? '') !== checksum) {
 			this.options.stateStore.patchState({ _configChecksum: checksum });
 			return true;
 		}

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

@@ -13,21 +13,28 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 	public render(
 		input: KTDataTablePaginationRendererInput,
 	): KTDataTableCleanup | void {
-		this.removeChildElements(input.sizeElement);
-		this.createPageSizeControls(input);
+		if (input.sizeElement) {
+			this.removeChildElements(input.sizeElement);
+			this.createPageSizeControls(input);
+		}
 
-		this.removeChildElements(input.paginationElement);
-		this.createPaginationControls(input);
+		if (input.paginationElement) {
+			this.removeChildElements(input.paginationElement);
+			this.createPaginationControls(input);
+		}
 
 		return () => {
 			if (input.sizeElement) {
 				input.sizeElement.onchange = null;
+				this.removeChildElements(input.sizeElement);
+			}
+			if (input.paginationElement) {
+				this.removeChildElements(input.paginationElement);
 			}
-			this.removeChildElements(input.paginationElement);
 		};
 	}
 
-	private removeChildElements(container: HTMLElement): void {
+	private removeChildElements(container?: HTMLElement | null): void {
 		if (!container) {
 			return;
 		}
@@ -39,22 +46,21 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 
 	private createPageSizeControls(
 		input: KTDataTablePaginationRendererInput,
-	): HTMLSelectElement {
+	): void {
 		if (!input.sizeElement) {
-			return input.sizeElement;
+			return;
 		}
 
-		setTimeout(() => {
-			const options = input.config.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;
-			});
+		const pageSizes = input.config.pageSizes ?? [5, 10, 20, 30, 50];
+		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(
@@ -62,18 +68,12 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 				1,
 			);
 		};
-
-		return input.sizeElement;
 	}
 
 	private createPaginationControls(
 		input: KTDataTablePaginationRendererInput,
-	): HTMLElement {
-		if (
-			!input.infoElement ||
-			!input.paginationElement ||
-			input.dataLength === 0
-		) {
+	): HTMLElement | null {
+		if (!input.paginationElement || input.dataLength === 0) {
 			return null;
 		}
 
@@ -86,7 +86,12 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 	private setPaginationInfoText(
 		input: KTDataTablePaginationRendererInput,
 	): void {
-		input.infoElement.textContent = input.config.info
+		if (!input.infoElement) {
+			return;
+		}
+
+		const infoTemplate = input.config.info ?? '{start}-{end} of {total}';
+		input.infoElement.textContent = infoTemplate
 			.replace(
 				'{start}',
 				(input.state.page - 1) * input.state.pageSize + 1 + '',
@@ -105,8 +110,14 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 		paginationContainer: HTMLElement,
 		input: KTDataTablePaginationRendererInput,
 	): void {
+		const pagination = input.config.pagination;
+		if (!pagination) {
+			return;
+		}
+
 		const { page: currentPage, totalPages } = input.state;
-		const { previous, next, number, more } = input.config.pagination;
+		const { previous, next, number, more } = pagination;
+		const pageMoreLimit = input.config.pageMoreLimit ?? 3;
 
 		const createButton = (
 			text: string,
@@ -135,7 +146,7 @@ export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRe
 			const range = this.calculatePageRange(
 				currentPage,
 				totalPages,
-				input.config.pageMoreLimit,
+				pageMoreLimit,
 			);
 
 			if (range.start > 1) {

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

@@ -137,6 +137,9 @@ export class KTDataTableRemoteDataProvider<
 			this.options.config.requestMethod;
 		let requestBody: RequestInit['body'] | undefined = undefined;
 		let apiEndpoint = this.options.config.apiEndpoint;
+		if (!apiEndpoint) {
+			throw new Error('KTDataTable: apiEndpoint is required for remote fetch');
+		}
 
 		if (this.abortController) {
 			this.abortController.abort();