@keenthemes/ktui 1.2.3 → 1.2.5

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

@@ -0,0 +1,225 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableCleanup,
+	KTDataTablePaginationRenderer,
+	KTDataTablePaginationRendererInput,
+} from './datatable-contracts';
+
+export class KTDataTableDomPaginationRenderer implements KTDataTablePaginationRenderer {
+	public render(
+		input: KTDataTablePaginationRendererInput,
+	): KTDataTableCleanup | void {
+		if (input.sizeElement) {
+			this.removeChildElements(input.sizeElement);
+			this.createPageSizeControls(input);
+		}
+
+		if (input.paginationElement) {
+			this.removeChildElements(input.paginationElement);
+			this.createPaginationControls(input);
+		}
+
+		return () => {
+			if (input.sizeElement) {
+				input.sizeElement.onchange = null;
+			}
+			if (input.paginationElement) {
+				this.removeChildElements(input.paginationElement);
+			}
+		};
+	}
+
+	private removeChildElements(container?: HTMLElement | null): void {
+		if (!container) {
+			return;
+		}
+
+		while (container.firstChild) {
+			container.removeChild(container.firstChild);
+		}
+	}
+
+	private createPageSizeControls(
+		input: KTDataTablePaginationRendererInput,
+	): void {
+		if (!input.sizeElement) {
+			return;
+		}
+
+		const pageSizes = input.config.pageSizes ?? [5, 10, 20, 30, 50];
+
+		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.onchange = (event: Event) => {
+			input.reloadPageSize(
+				Number((event.target as HTMLSelectElement).value),
+				1,
+			);
+		};
+	}
+
+	private createPaginationControls(
+		input: KTDataTablePaginationRendererInput,
+	): HTMLElement | null {
+		if (!input.paginationElement || input.dataLength === 0) {
+			return null;
+		}
+
+		this.setPaginationInfoText(input);
+		this.createPaginationButtons(input.paginationElement, input);
+
+		return input.paginationElement;
+	}
+
+	private setPaginationInfoText(
+		input: KTDataTablePaginationRendererInput,
+	): void {
+		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 + '',
+			)
+			.replace(
+				'{end}',
+				Math.min(
+					input.state.page * input.state.pageSize,
+					input.state.totalItems,
+				) + '',
+			)
+			.replace('{total}', input.state.totalItems + '');
+	}
+
+	private createPaginationButtons(
+		paginationContainer: HTMLElement,
+		input: KTDataTablePaginationRendererInput,
+	): void {
+		const pagination = input.config.pagination;
+		if (!pagination) {
+			return;
+		}
+
+		const { page: currentPage, totalPages } = input.state;
+		const { previous, next, number, more } = pagination;
+		const pageMoreLimit = input.config.pageMoreLimit ?? 3;
+
+		const createButton = (
+			text: string,
+			className: string,
+			disabled: boolean,
+			handleClick: () => void,
+		): HTMLButtonElement => {
+			const button = document.createElement('button') as HTMLButtonElement;
+			button.className = className;
+			button.innerHTML = text;
+			button.disabled = disabled;
+			button.onclick = handleClick;
+			return button;
+		};
+
+		paginationContainer.appendChild(
+			createButton(
+				previous.text,
+				`${previous.class}${currentPage === 1 ? ' disabled' : ''}`,
+				currentPage === 1,
+				() => input.paginateData(currentPage - 1),
+			),
+		);
+
+		if (input.config.pageMore) {
+			const range = this.calculatePageRange(
+				currentPage,
+				totalPages,
+				pageMoreLimit,
+			);
+
+			if (range.start > 1) {
+				paginationContainer.appendChild(
+					createButton(more.text, more.class, false, () =>
+						input.paginateData(Math.max(1, range.start - 1)),
+					),
+				);
+			}
+
+			for (let i = range.start; i <= range.end; i++) {
+				paginationContainer.appendChild(
+					createButton(
+						number.text.replace('{page}', i.toString()),
+						`${number.class}${currentPage === i ? ' active disabled' : ''}`,
+						currentPage === i,
+						() => input.paginateData(i),
+					),
+				);
+			}
+
+			if (range.end < totalPages) {
+				paginationContainer.appendChild(
+					createButton(more.text, more.class, false, () =>
+						input.paginateData(Math.min(totalPages, range.end + 1)),
+					),
+				);
+			}
+		} else {
+			for (let i = 1; i <= totalPages; i++) {
+				paginationContainer.appendChild(
+					createButton(
+						number.text.replace('{page}', i.toString()),
+						`${number.class}${currentPage === i ? ' active disabled' : ''}`,
+						currentPage === i,
+						() => input.paginateData(i),
+					),
+				);
+			}
+		}
+
+		paginationContainer.appendChild(
+			createButton(
+				next.text,
+				`${next.class}${currentPage === totalPages ? ' disabled' : ''}`,
+				currentPage === totalPages,
+				() => input.paginateData(currentPage + 1),
+			),
+		);
+	}
+
+	private calculatePageRange(
+		currentPage: number,
+		totalPages: number,
+		maxButtons: number,
+	): { start: number; end: number } {
+		let startPage: number, endPage: number;
+		const halfMaxButtons = Math.floor(maxButtons / 2);
+
+		if (totalPages <= maxButtons) {
+			startPage = 1;
+			endPage = totalPages;
+		} else {
+			startPage = Math.max(currentPage - halfMaxButtons, 1);
+			endPage = Math.min(startPage + maxButtons - 1, totalPages);
+			if (endPage - startPage < maxButtons - 1) {
+				startPage = Math.max(endPage - maxButtons + 1, 1);
+			}
+		}
+
+		return { start: startPage, end: endPage };
+	}
+}

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

@@ -0,0 +1,178 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableColumnFilterInterface,
+	KTDataTableConfigInterface,
+	KTDataTableDataInterface,
+} from './types';
+import {
+	KTDataTableDataProvider,
+	KTDataTableEventAdapter,
+	KTDataTableProviderResult,
+	KTDataTableStateStore,
+} from './datatable-contracts';
+
+interface KTDataTableRemoteProviderOptions {
+	config: KTDataTableConfigInterface;
+	createUrl: (pathOrUrl: string) => URL;
+	eventAdapter: KTDataTableEventAdapter;
+	noticeOnTable: (message?: string) => void;
+	stateStore: KTDataTableStateStore;
+}
+
+export class KTDataTableRemoteDataProvider<
+	T extends KTDataTableDataInterface,
+> implements KTDataTableDataProvider<T> {
+	private abortController: AbortController | null = null;
+	private requestId = 0;
+
+	constructor(private readonly options: KTDataTableRemoteProviderOptions) {}
+
+	public dispose(): void {
+		if (this.abortController) {
+			this.abortController.abort();
+			this.abortController = null;
+		}
+	}
+
+	public async fetch(): Promise<KTDataTableProviderResult<T>> {
+		const currentRequestId = ++this.requestId;
+		const queryParams = this.getQueryParamsForFetchRequest();
+
+		let response: Response;
+		try {
+			response = await this.performFetchRequest(queryParams);
+		} catch (error) {
+			if ((error as Error).name === 'AbortError') {
+				return { data: [], totalItems: 0, skipped: true };
+			}
+			throw error;
+		}
+
+		if (currentRequestId !== this.requestId) {
+			return { data: [], totalItems: 0, skipped: true };
+		}
+
+		let responseData = null;
+
+		try {
+			responseData = await response.json();
+		} catch (error) {
+			this.options.eventAdapter.emit('parseError', {
+				response,
+				error: String(error),
+				status: response.status,
+				statusText: response.statusText,
+			});
+			return { data: [], totalItems: 0, skipped: true };
+		}
+
+		if (currentRequestId !== this.requestId) {
+			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);
+		}
+
+		return {
+			data: responseData.data as T[],
+			totalItems: responseData.totalCount,
+			response: responseData,
+		};
+	}
+
+	private getQueryParamsForFetchRequest(): URLSearchParams {
+		const { page, pageSize, sortField, sortOrder, filters, search } =
+			this.options.stateStore.getState();
+
+		let queryParams = new URLSearchParams();
+		queryParams.set('page', String(page));
+		queryParams.set('size', String(pageSize));
+
+		if (sortOrder !== undefined) {
+			queryParams.set('sortOrder', String(sortOrder));
+		}
+
+		if (sortField !== undefined) {
+			queryParams.set('sortField', String(sortField));
+		}
+
+		if (Array.isArray(filters) && filters.length) {
+			queryParams.set(
+				'filters',
+				JSON.stringify(
+					filters.map((filter: KTDataTableColumnFilterInterface) => ({
+						column: filter.column,
+						type: filter.type,
+						value: filter.value,
+					})),
+				),
+			);
+		}
+
+		if (search) {
+			queryParams.set(
+				'search',
+				typeof search === 'object' ? JSON.stringify(search) : search,
+			);
+		}
+
+		if (typeof this.options.config.mapRequest === 'function') {
+			queryParams = this.options.config.mapRequest.call(this, queryParams);
+		}
+
+		return queryParams;
+	}
+
+	private async performFetchRequest(
+		queryParams: URLSearchParams,
+	): Promise<Response> {
+		const requestMethod: RequestInit['method'] =
+			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();
+		}
+
+		this.abortController = new AbortController();
+
+		if (requestMethod === 'POST') {
+			requestBody = queryParams;
+		} else if (requestMethod === 'GET') {
+			const apiEndpointWithQueryParams = this.options.createUrl(apiEndpoint);
+			apiEndpointWithQueryParams.search = queryParams.toString();
+			apiEndpoint = apiEndpointWithQueryParams.toString();
+		}
+
+		return fetch(apiEndpoint, {
+			method: requestMethod,
+			body: requestBody,
+			headers: this.options.config.requestHeaders,
+			...(this.options.config.requestCredentials && {
+				credentials: this.options.config.requestCredentials,
+			}),
+			...(this.abortController && { signal: this.abortController.signal }),
+		}).catch((error) => {
+			if (error.name === 'AbortError') {
+				return Promise.reject(error);
+			}
+
+			this.options.eventAdapter.emit('error', { error });
+			this.options.noticeOnTable(
+				'Error performing fetch request: ' + String(error),
+			);
+			throw error;
+		});
+	}
+}

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

@@ -0,0 +1,94 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import {
+	KTDataTableAttributeInterface,
+	KTDataTableColumnFilterInterface,
+	KTDataTableConfigInterface,
+	KTDataTableDataInterface,
+	KTDataTableSortOrderInterface,
+	KTDataTableStateInterface,
+} from './types';
+import { KTDataTableStateStore } from './datatable-contracts';
+
+export class KTDataTableConfigStateStore implements KTDataTableStateStore {
+	constructor(private readonly config: KTDataTableConfigInterface) {
+		this.ensureState();
+	}
+
+	public getState(): KTDataTableStateInterface {
+		this.ensureState();
+		return {
+			page: 1,
+			sortField: null,
+			sortOrder: '',
+			pageSize: this.config.pageSize,
+			filters: [],
+			...this.config._state,
+		} as KTDataTableStateInterface;
+	}
+
+	public replaceState(state: KTDataTableStateInterface): void {
+		this.config._state = state;
+		this.ensureState();
+	}
+
+	public patchState(state: Partial<KTDataTableStateInterface>): void {
+		this.ensureState();
+		this.config._state = {
+			...this.config._state,
+			...state,
+		} as KTDataTableStateInterface;
+	}
+
+	public setPage(page: number): void {
+		this.patchState({ page });
+	}
+
+	public setPageSize(pageSize: number, page: number = 1): void {
+		this.patchState({ pageSize, page });
+	}
+
+	public setSort(
+		field: keyof KTDataTableDataInterface | number,
+		order: KTDataTableSortOrderInterface,
+	): void {
+		this.patchState({
+			sortField: field,
+			sortOrder: order,
+		} as Partial<KTDataTableStateInterface>);
+	}
+
+	public setSearch(search: string | object): void {
+		this.patchState({ search, page: 1 });
+	}
+
+	public setFilter(filter: KTDataTableColumnFilterInterface): void {
+		const filters = [
+			...(this.getState().filters || []).filter(
+				(currentFilter) => currentFilter.column !== filter.column,
+			),
+			filter,
+		];
+
+		this.patchState({ filters, page: 1 });
+	}
+
+	public setOriginalData(
+		originalData: KTDataTableDataInterface[],
+		originalDataAttributes: KTDataTableAttributeInterface[],
+	): void {
+		this.patchState({
+			originalData,
+			originalDataAttributes,
+		} as Partial<KTDataTableStateInterface>);
+	}
+
+	private ensureState(): void {
+		if (!this.config._state) {
+			this.config._state = {} as KTDataTableStateInterface;
+		}
+	}
+}

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

@@ -0,0 +1,214 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import { KTOptionType } from '../../types';
+import {
+	KTDataTableDataInterface,
+	KTDataTableAttributeInterface,
+} from './types';
+import {
+	KTDataTableTableRenderer,
+	KTDataTableTableRendererInput,
+} from './datatable-contracts';
+
+export class KTDataTableDomTableRenderer<
+	T extends KTDataTableDataInterface,
+> implements KTDataTableTableRenderer<T> {
+	public render(
+		input: KTDataTableTableRendererInput<T>,
+	): HTMLTableSectionElement {
+		while (input.tableElement.tBodies.length) {
+			input.tableElement.removeChild(input.tableElement.tBodies[0]);
+		}
+
+		const tbodyElement =
+			input.tableElement.createTBody() as HTMLTableSectionElement;
+
+		if (input.originalTbodyClass) {
+			tbodyElement.className = input.originalTbodyClass;
+		}
+
+		this.renderContent(input, tbodyElement);
+
+		return tbodyElement;
+	}
+
+	public notice(
+		tableElement: HTMLTableElement,
+		getLogicalColumnCount: () => number,
+		message: string = '',
+	): void {
+		const row = tableElement.tBodies[0].insertRow();
+		const cell = row.insertCell();
+		const logicalCount = getLogicalColumnCount();
+		cell.colSpan = logicalCount > 0 ? logicalCount : 1;
+		cell.innerHTML = message;
+	}
+
+	private renderContent(
+		input: KTDataTableTableRendererInput<T>,
+		tbodyElement: HTMLTableSectionElement,
+	): HTMLTableSectionElement {
+		const fragment = document.createDocumentFragment();
+
+		tbodyElement.textContent = '';
+
+		if (input.data.length === 0) {
+			this.notice(
+				input.tableElement,
+				input.getLogicalColumnCount,
+				input.config.infoEmpty || '',
+			);
+			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 logicalColumnCount =
+			columnsToRender.length > 0
+				? columnsToRender.length
+				: input.getLogicalColumnCount();
+
+		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.config.columns) {
+				this.renderImplicitColumns(input, row, item, rowIndex, {
+					columnsToRender,
+					logicalColumnCount,
+				});
+			} else {
+				this.renderConfiguredColumns(input, row, item, rowIndex);
+			}
+
+			fragment.appendChild(row);
+		});
+
+		tbodyElement.appendChild(fragment);
+		return tbodyElement;
+	}
+
+	private renderImplicitColumns(
+		input: KTDataTableTableRendererInput<T>,
+		row: HTMLTableRowElement,
+		item: T,
+		rowIndex: number,
+		options: {
+			columnsToRender: HTMLTableCellElement[];
+			logicalColumnCount: number;
+		},
+	): void {
+		const dataRowAttributes = input.getState().originalDataAttributes
+			? input.getState().originalDataAttributes[rowIndex]
+			: null;
+
+		for (let colIndex = 0; colIndex < options.logicalColumnCount; colIndex++) {
+			const th = options.columnsToRender[colIndex];
+			const colName = th?.getAttribute('data-kt-datatable-column');
+			const td = document.createElement('td');
+			let value: KTOptionType | '';
+			if (colName && Object.prototype.hasOwnProperty.call(item, colName)) {
+				value = item[colName as keyof T];
+			} else if (Object.prototype.hasOwnProperty.call(item, colIndex)) {
+				value = item[colIndex as keyof T];
+			} else {
+				value = '';
+			}
+			td.innerHTML = value as string;
+
+			this.applyOriginalTdClass(input, td, rowIndex, colIndex);
+			this.applyDataRowAttributes(td, dataRowAttributes ?? null, colIndex);
+
+			row.appendChild(td);
+		}
+	}
+
+	private renderConfiguredColumns(
+		input: KTDataTableTableRendererInput<T>,
+		row: HTMLTableRowElement,
+		item: T,
+		rowIndex: number,
+	): void {
+		const columns = input.config.columns;
+		if (!columns) {
+			return;
+		}
+
+		Object.keys(columns).forEach((key, colIndex) => {
+			const columnDef = columns[key];
+			if (!columnDef) {
+				return;
+			}
+			const colKey = key as keyof T;
+
+			const td = document.createElement('td');
+
+			this.applyOriginalTdClass(input, td, rowIndex, colIndex);
+
+			if (typeof columnDef.render === 'function') {
+				const result = columnDef.render.call(
+					input.context,
+					item[colKey],
+					item,
+					input.context,
+				);
+				if (
+					result instanceof HTMLElement ||
+					result instanceof DocumentFragment
+				) {
+					td.appendChild(result);
+				} else if (typeof result === 'string') {
+					td.innerHTML = result as string;
+				}
+			} else {
+				td.textContent = item[colKey] as string;
+			}
+
+			if (typeof columnDef.createdCell === 'function') {
+				columnDef.createdCell.call(input.context, td, item[colKey], item, row);
+			}
+
+			row.appendChild(td);
+		});
+	}
+
+	private applyOriginalTdClass(
+		input: KTDataTableTableRendererInput<T>,
+		td: HTMLTableCellElement,
+		rowIndex: number,
+		colIndex: number,
+	): void {
+		if (
+			input.originalTdClasses &&
+			input.originalTdClasses[rowIndex] &&
+			input.originalTdClasses[rowIndex][colIndex]
+		) {
+			td.className = input.originalTdClasses[rowIndex][colIndex];
+		}
+	}
+
+	private applyDataRowAttributes(
+		td: HTMLTableCellElement,
+		dataRowAttributes: KTDataTableAttributeInterface | null,
+		colIndex: number,
+	): void {
+		if (dataRowAttributes && dataRowAttributes[colIndex]) {
+			for (const attr in dataRowAttributes[colIndex]) {
+				td.setAttribute(attr, dataRowAttributes[colIndex][attr]);
+			}
+		}
+	}
+}