@keenthemes/ktui 1.2.5 → 1.2.6

package/src/components/datatable/datatable.ts

@@ -11,6 +11,8 @@ import {
 	KTDataTableSortOrderInterface,
 	KTDataTableStateInterface,
 	KTDataTableColumnFilterInterface,
+	KTDataTableLayoutPluginContextInterface,
+	KTDataTableLayoutPluginInterface,
 } from './types';
 import { KTOptionType } from '../../types';
 import KTComponents from '../../index';
@@ -20,6 +22,7 @@ import {
 	KTDataTableCheckboxAPI,
 } from './datatable-checkbox';
 import { createSortHandler, KTDataTableSortAPI } from './datatable-sort';
+import { createStickyLayoutPlugin } from './datatable-layout-plugin';
 import {
 	KTDataTableCleanup,
 	KTDataTableEventAdapter,
@@ -33,6 +36,7 @@ import { KTDataTableRemoteDataProvider } from './datatable-remote-provider';
 import { KTDataTableConfigStateStore } from './datatable-state-store';
 import { KTDataTableDomPaginationRenderer } from './datatable-pagination-renderer';
 import { KTDataTableDomTableRenderer } from './datatable-table-renderer';
+import KTUtils from '../../helpers/utils';
 
 /**
  * Custom DataTable plugin class with server-side API, pagination, and sorting
@@ -80,6 +84,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 
 	private _checkbox: KTDataTableCheckboxAPI;
 	private _sortHandler: KTDataTableSortAPI<T>;
+	private _layoutPlugin: KTDataTableLayoutPluginInterface | null = null;
 	private _eventAdapter: KTDataTableEventAdapter;
 	private _stateStore: KTDataTableStateStore;
 	private _localProvider: KTDataTableLocalDataProvider<T>;
@@ -95,10 +100,10 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		super();
 
 		if (KTData.has(element as HTMLElement, this._name)) {
-			// Already initialized (e.g. by createInstances). Merge user config so columns/sortType etc. apply.
+			// Already initialized (e.g. by createInstances). Merge demo config and redraw once.
 			const existing = KTDataTable.getInstance(element as HTMLElement);
 			if (existing && config) {
-				existing._mergeConfig(config);
+				existing._applyRuntimeConfig(config);
 			}
 			return;
 		}
@@ -109,7 +114,11 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		if (!this._element) {
 			return;
 		}
+		if (!this._element.hasAttribute('data-kt-datatable')) {
+			this._element.setAttribute('data-kt-datatable', 'true');
+		}
 		this._buildConfig();
+		this._normalizePageSizeConfig();
 		this._stateStore = new KTDataTableConfigStateStore(this._config);
 		this._eventAdapter = createDataTableEventAdapter(
 			this._fireEvent.bind(this),
@@ -120,6 +129,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		KTDataTable.asElementWithInstance(element).instance = this;
 
 		this._initElements();
+		this._layoutPlugin = this._createLayoutPlugin();
 		this._tableRenderer = new KTDataTableDomTableRenderer<T>();
 		this._paginationRenderer = new KTDataTableDomPaginationRenderer();
 		this._initDataProviders();
@@ -155,6 +165,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 
 		if (this._config.stateSave) {
 			this._loadState();
+			this._normalizePageState();
 		}
 
 		this._updateData();
@@ -188,6 +199,69 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		});
 	}
 
+	private _createLayoutPlugin(): KTDataTableLayoutPluginInterface | null {
+		if (this._config.layoutPlugin) {
+			return this._config.layoutPlugin;
+		}
+
+		if (this._config.lockedLayout) {
+			return createStickyLayoutPlugin();
+		}
+
+		return null;
+	}
+
+	/**
+	 * Apply config from a late constructor call (e.g. docs demo script after auto-init).
+	 */
+	private _applyRuntimeConfig(config: KTDataTableConfigInterface): void {
+		this._mergeConfig(config);
+		this._normalizePageSizeConfig();
+		this._layoutPlugin = this._createLayoutPlugin();
+		this.reload();
+	}
+
+	private _normalizePageSizeConfig(): void {
+		const configuredPageSizes = Array.isArray(this._config.pageSizes)
+			? this._config.pageSizes
+			: [];
+		const pageSizes = configuredPageSizes
+			.map((size) => Number(size))
+			.filter((size) => Number.isFinite(size) && size > 0)
+			.map((size) => Math.floor(size));
+		const fallbackPageSizes = [5, 10, 20, 30, 50];
+		this._config.pageSizes =
+			pageSizes.length > 0 ? Array.from(new Set(pageSizes)) : fallbackPageSizes;
+
+		const configuredPageSize = Number(this._config.pageSize);
+		this._config.pageSize =
+			Number.isFinite(configuredPageSize) && configuredPageSize > 0
+				? Math.floor(configuredPageSize)
+				: this._config.pageSizes[0];
+	}
+
+	private _normalizePageState(): void {
+		const statePageSize = Number(this._config._state.pageSize);
+		this._config._state.pageSize =
+			Number.isFinite(statePageSize) && statePageSize > 0
+				? Math.floor(statePageSize)
+				: this._config.pageSize;
+
+		const statePage = Number(this._config._state.page);
+		this._config._state.page =
+			Number.isFinite(statePage) && statePage > 0 ? Math.floor(statePage) : 1;
+	}
+
+	private _getLayoutPluginContext(): KTDataTableLayoutPluginContextInterface {
+		return {
+			rootElement: this._element,
+			tableElement: this._tableElement,
+			theadElement: this._theadElement,
+			tbodyElement: this._tbodyElement,
+			config: this._config,
+		};
+	}
+
 	/**
 	 * Initialize default configuration for the datatable
 	 * @param config User-provided configuration options
@@ -431,7 +505,9 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		const root = this._element;
 		const attrs = this._config.attributes;
 		if (!root || !attrs?.table) {
-			throw new Error('KTDataTable: root element and table selector are required');
+			throw new Error(
+				'KTDataTable: root element and table selector are required',
+			);
 		}
 
 		const tableEl = root.querySelector<HTMLTableElement>(attrs.table);
@@ -698,11 +774,20 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	 * @returns {Promise<void>} A promise that resolves when the table and pagination controls are updated
 	 */
 	private async _draw(): Promise<void> {
-		this._stateStore.patchState({
-			totalPages:
-				Math.ceil(this.getState().totalItems / this.getState().pageSize) || 0,
-		});
+		const normalizedPageSize = Math.max(
+			1,
+			Number(this.getState().pageSize) || Number(this._config.pageSize) || 1,
+		);
+		const totalPages =
+			Math.ceil(this.getState().totalItems / normalizedPageSize) || 0;
+		const page =
+			totalPages > 0
+				? Math.min(Math.max(1, this.getState().page), totalPages)
+				: 1;
+
+		this._stateStore.patchState({ totalPages, page });
 
+		this._layoutPlugin?.beforeDraw?.(this._getLayoutPluginContext());
 		this._emit('draw');
 
 		this._dispose();
@@ -716,6 +801,15 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			this._updatePagination();
 		}
 
+		this._layoutPlugin?.afterDraw?.(this._getLayoutPluginContext());
+		if (!this._config.apiEndpoint) {
+			this._stateStore.patchState({
+				_contentChecksum: KTUtils.checksum(
+					JSON.stringify(this._tbodyElement.innerHTML),
+				),
+			});
+		}
+
 		this._emit('drew');
 
 		// Spinner is hidden in _finalize() to ensure it stays visible until the entire request completes
@@ -731,7 +825,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	 * @returns {HTMLTableSectionElement} The new table body element
 	 */
 	private _updateTable(): HTMLTableSectionElement {
-		return this._tableRenderer.render({
+		this._tbodyElement = this._tableRenderer.render({
 			config: this._config,
 			context: this,
 			data: this._data,
@@ -743,6 +837,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			tableElement: this._tableElement,
 			theadElement: this._theadElement,
 		});
+		return this._tbodyElement;
 	}
 
 	/**
@@ -810,9 +905,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		const root = this._element;
 		const spinnerSel = this._config.attributes?.spinner;
 		const fromDom =
-			root && spinnerSel
-				? root.querySelector<HTMLElement>(spinnerSel)
-				: null;
+			root && spinnerSel ? root.querySelector<HTMLElement>(spinnerSel) : null;
 		const spinner = fromDom ?? this._createSpinner();
 		if (spinner) {
 			spinner.style.display = 'block';
@@ -825,9 +918,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		const root = this._element;
 		const spinnerSel = this._config.attributes?.spinner;
 		const spinner =
-			root && spinnerSel
-				? root.querySelector<HTMLElement>(spinnerSel)
-				: null;
+			root && spinnerSel ? root.querySelector<HTMLElement>(spinnerSel) : null;
 		if (spinner) {
 			spinner.style.display = 'none';
 		}
@@ -934,6 +1025,8 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	 * This method is called before re-rendering or when disposing the component.
 	 */
 	private _dispose() {
+		this._layoutPlugin?.dispose?.(this._getLayoutPluginContext());
+
 		const root = this._element;
 		if (!root) {
 			return;
@@ -983,7 +1076,8 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		} else {
 			const checkSel = this._config.attributes?.check;
 			if (checkSel) {
-				const headerCheckElement = root.querySelector<HTMLInputElement>(checkSel);
+				const headerCheckElement =
+					root.querySelector<HTMLInputElement>(checkSel);
 				if (headerCheckElement) {
 					headerCheckElement.replaceWith(headerCheckElement.cloneNode(true));
 				}

package/src/components/datatable/index.ts

@@ -16,4 +16,9 @@ export type {
 	KTDataTableCheckConfigInterface,
 	KTDataTableCheckInterface,
 	KTDataTableCheckChangePayloadInterface,
+	KTDataTableLockedRowsConfigInterface,
+	KTDataTableLockedColumnsConfigInterface,
+	KTDataTableLockedLayoutConfigInterface,
+	KTDataTableLayoutPluginContextInterface,
+	KTDataTableLayoutPluginInterface,
 } from './types';

package/src/components/datatable/types.ts

@@ -69,6 +69,36 @@ export interface KTDataTableResponseDataInterface {
 	totalCount: number;
 }
 
+export interface KTDataTableLockedRowsConfigInterface {
+	top?: number;
+	bottom?: number;
+}
+
+export interface KTDataTableLockedColumnsConfigInterface {
+	left?: string[];
+	right?: string[];
+}
+
+export interface KTDataTableLockedLayoutConfigInterface {
+	stickyHeader?: boolean;
+	stickyRows?: KTDataTableLockedRowsConfigInterface;
+	stickyColumns?: KTDataTableLockedColumnsConfigInterface;
+}
+
+export interface KTDataTableLayoutPluginContextInterface {
+	rootElement: HTMLElement;
+	tableElement: HTMLTableElement;
+	theadElement: HTMLTableSectionElement;
+	tbodyElement: HTMLTableSectionElement;
+	config: KTDataTableConfigInterface;
+}
+
+export interface KTDataTableLayoutPluginInterface {
+	beforeDraw?: (ctx: KTDataTableLayoutPluginContextInterface) => void;
+	afterDraw?: (ctx: KTDataTableLayoutPluginContextInterface) => void;
+	dispose?: (ctx: KTDataTableLayoutPluginContextInterface) => void;
+}
+
 // Define the DataTable options type
 export interface KTDataTableConfigInterface {
 	requestMethod?: string;
@@ -187,6 +217,9 @@ export interface KTDataTableConfigInterface {
 		preserveSelection?: boolean;
 	};
 
+	lockedLayout?: KTDataTableLockedLayoutConfigInterface;
+	layoutPlugin?: KTDataTableLayoutPluginInterface;
+
 	_state?: KTDataTableStateInterface;
 	_data?: KTDataTableDataInterface[];
 

package/src/index.ts

@@ -87,6 +87,11 @@ export type {
 	KTDataTableCheckConfigInterface,
 	KTDataTableCheckInterface,
 	KTDataTableCheckChangePayloadInterface,
+	KTDataTableLockedRowsConfigInterface,
+	KTDataTableLockedColumnsConfigInterface,
+	KTDataTableLockedLayoutConfigInterface,
+	KTDataTableLayoutPluginContextInterface,
+	KTDataTableLayoutPluginInterface,
 } from './components/datatable';
 export type {
 	KTDismissConfigInterface,