@keenthemes/ktui 1.2.4 → 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
@@ -74,12 +78,13 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	private _originalTdClasses: string[][] = []; // Store original td classes as a 2D array [row][col]
 	private _originalThClasses: string[] = []; // Store original th classes
 
-	private _infoElement: HTMLElement;
-	private _sizeElement: HTMLSelectElement;
-	private _paginationElement: HTMLElement;
+	private _infoElement: HTMLElement | null = null;
+	private _sizeElement: HTMLSelectElement | null = null;
+	private _paginationElement: HTMLElement | null = null;
 
 	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;
 		}
@@ -106,7 +111,14 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		this._defaultConfig = this._initDefaultConfig(config);
 
 		this._init(element);
+		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),
@@ -117,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();
@@ -152,6 +165,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 
 		if (this._config.stateSave) {
 			this._loadState();
+			this._normalizePageState();
 		}
 
 		this._updateData();
@@ -185,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
@@ -425,43 +502,37 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	 * @returns {void}
 	 */
 	private _initElements(): void {
-		/**
-		 * Data table element
-		 */
-		this._tableElement = this._element.querySelector<HTMLTableElement>(
-			this._config.attributes.table,
-		)!;
-		/**
-		 * Table body element
-		 */
+		const root = this._element;
+		const attrs = this._config.attributes;
+		if (!root || !attrs?.table) {
+			throw new Error(
+				'KTDataTable: root element and table selector are required',
+			);
+		}
+
+		const tableEl = root.querySelector<HTMLTableElement>(attrs.table);
+		if (!tableEl) {
+			throw new Error(`KTDataTable: table element not found (${attrs.table})`);
+		}
+		this._tableElement = tableEl;
+
 		this._tbodyElement =
 			this._tableElement.tBodies[0] || this._tableElement.createTBody();
-		/**
-		 * Table head element
-		 */
-		this._theadElement = this._tableElement.tHead!;
 
-		// Store original classes
+		this._theadElement =
+			this._tableElement.tHead ?? this._tableElement.createTHead();
+
 		this._storeOriginalClasses();
 
-		/**
-		 * Pagination info element
-		 */
-		this._infoElement = this._element.querySelector<HTMLElement>(
-			this._config.attributes.info,
-		)!;
-		/**
-		 * Page size dropdown element
-		 */
-		this._sizeElement = this._element.querySelector<HTMLSelectElement>(
-			this._config.attributes.size,
-		)!;
-		/**
-		 * Pagination element
-		 */
-		this._paginationElement = this._element.querySelector<HTMLElement>(
-			this._config.attributes.pagination,
-		)!;
+		this._infoElement = attrs.info
+			? root.querySelector<HTMLElement>(attrs.info)
+			: null;
+		this._sizeElement = attrs.size
+			? root.querySelector<HTMLSelectElement>(attrs.size)
+			: null;
+		this._paginationElement = attrs.pagination
+			? root.querySelector<HTMLElement>(attrs.pagination)
+			: null;
 	}
 
 	/**
@@ -540,7 +611,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	 * @returns {void}
 	 */
 	private _finalize(): void {
-		this._element.classList.add('datatable-initialized');
+		this._element?.classList.add('datatable-initialized');
 
 		// Initialize checkbox logic
 		this._checkbox.init();
@@ -600,7 +671,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			// Create a new debounced search function
 			const debouncedSearch = this._debounce(() => {
 				this.search(searchElement.value);
-			}, this._config.search.delay);
+			}, this._config.search?.delay ?? 500);
 
 			// Store the new debounced function as a property of the element
 			searchWithDebounce._debouncedSearch = debouncedSearch;
@@ -647,7 +718,9 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 
 	private _createUrl(
 		pathOrUrl: string,
-		baseUrl: string | null = window.location.origin,
+		baseUrl: string | null = typeof window !== 'undefined'
+			? window.location.origin
+			: null,
 	): URL {
 		// Regular expression to check if the input is a full URL
 		const isFullUrl = /^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//.test(pathOrUrl);
@@ -661,7 +734,39 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			? pathOrUrl
 			: `/${pathOrUrl}`;
 
-		return new URL(normalizedPath, baseUrl);
+		// Opaque origins (e.g. srcdoc iframes) serialize as the string "null", which is not a valid URL base.
+		const bases: string[] = [];
+		if (baseUrl && baseUrl !== 'null') {
+			bases.push(baseUrl);
+		}
+		if (typeof window !== 'undefined') {
+			const href = window.location.href;
+			if (href && !bases.includes(href)) {
+				bases.push(href);
+			}
+			try {
+				if (window.parent !== window && window.parent.location?.href) {
+					const parentHref = window.parent.location.href;
+					if (parentHref && !bases.includes(parentHref)) {
+						bases.push(parentHref);
+					}
+				}
+			} catch {
+				// parent is cross-origin
+			}
+		}
+
+		for (const base of bases) {
+			try {
+				return new URL(normalizedPath, base);
+			} catch {
+				// try next base
+			}
+		}
+
+		throw new Error(
+			`KTDataTable: cannot resolve relative apiEndpoint "${pathOrUrl}" (no valid base URL; use an absolute apiEndpoint).`,
+		);
 	}
 
 	/**
@@ -669,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();
@@ -683,10 +797,19 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			this._updateTable();
 		}
 
-		if (this._infoElement && this._paginationElement) {
+		if (this._infoElement || this._sizeElement || this._paginationElement) {
 			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
@@ -702,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,
@@ -714,6 +837,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			tableElement: this._tableElement,
 			theadElement: this._theadElement,
 		});
+		return this._tbodyElement;
 	}
 
 	/**
@@ -778,38 +902,45 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 
 	// Method to show the loading spinner
 	private _showSpinner(): void {
-		const spinner =
-			this._element.querySelector<HTMLElement>(
-				this._config.attributes.spinner,
-			) || this._createSpinner();
+		const root = this._element;
+		const spinnerSel = this._config.attributes?.spinner;
+		const fromDom =
+			root && spinnerSel ? root.querySelector<HTMLElement>(spinnerSel) : null;
+		const spinner = fromDom ?? this._createSpinner();
 		if (spinner) {
 			spinner.style.display = 'block';
 		}
-		this._element.classList.add(this._config.loadingClass);
+		root?.classList.add(this._config.loadingClass ?? 'loading');
 	}
 
 	// Method to hide the loading spinner
 	private _hideSpinner(): void {
-		const spinner = this._element.querySelector<HTMLElement>(
-			this._config.attributes.spinner,
-		);
+		const root = this._element;
+		const spinnerSel = this._config.attributes?.spinner;
+		const spinner =
+			root && spinnerSel ? root.querySelector<HTMLElement>(spinnerSel) : null;
 		if (spinner) {
 			spinner.style.display = 'none';
 		}
-		this._element.classList.remove(this._config.loadingClass);
+		root?.classList.remove(this._config.loadingClass ?? 'loading');
 	}
 
 	// Method to create a spinner element if it doesn't exist
-	private _createSpinner(): HTMLElement {
-		if (typeof this._config.loading === 'undefined') {
+	private _createSpinner(): HTMLElement | null {
+		const loading = this._config.loading;
+		if (!loading) {
 			return null;
 		}
 
 		const template = document.createElement('template');
-		template.innerHTML = this._config.loading.template
+		template.innerHTML = loading.template
 			.trim()
-			.replace('{content}', this._config.loading.content);
-		const spinner = template.content.firstChild as HTMLElement;
+			.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');
 
 		this._tableElement.appendChild(spinner);
@@ -878,18 +1009,15 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 	}
 
 	private _tableId(): string {
-		let id: string = null;
-		// If the table element has an ID, use that
-		if (this._tableElement?.getAttribute('id')) {
-			id = this._tableElement.getAttribute('id') as string;
+		const tableIdAttr = this._tableElement?.getAttribute('id');
+		if (tableIdAttr) {
+			return tableIdAttr;
 		}
-
-		// If the component element has an ID, use that
-		if (this._element?.getAttribute('id')) {
-			id = this._element.getAttribute('id') as string;
+		const rootIdAttr = this._element?.getAttribute('id');
+		if (rootIdAttr) {
+			return rootIdAttr;
 		}
-
-		return id;
+		return '';
 	}
 
 	/**
@@ -897,6 +1025,13 @@ 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;
+		}
+
 		this._cleanupCallbacks.forEach((cleanup) => cleanup());
 		this._cleanupCallbacks = [];
 
@@ -939,12 +1074,13 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		if (this._checkbox && typeof checkboxWithDispose.dispose === 'function') {
 			checkboxWithDispose.dispose();
 		} else {
-			// Remove header checkbox event listener if possible
-			const headerCheckElement = this._element.querySelector<HTMLInputElement>(
-				this._config.attributes.check,
-			);
-			if (headerCheckElement) {
-				headerCheckElement.replaceWith(headerCheckElement.cloneNode(true));
+			const checkSel = this._config.attributes?.check;
+			if (checkSel) {
+				const headerCheckElement =
+					root.querySelector<HTMLInputElement>(checkSel);
+				if (headerCheckElement) {
+					headerCheckElement.replaceWith(headerCheckElement.cloneNode(true));
+				}
 			}
 		}
 		// KTDataTableSortAPI does not have a dispose method, but we can remove th click listeners by replacing them
@@ -956,22 +1092,23 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 		}
 
 		// --- 5. Remove spinner DOM node if it exists ---
-		const spinner = this._element.querySelector<HTMLElement>(
-			this._config.attributes.spinner,
-		);
-		if (spinner && spinner.parentNode) {
-			spinner.parentNode.removeChild(spinner);
+		const spinnerSel = this._config.attributes?.spinner;
+		if (spinnerSel) {
+			const spinner = root.querySelector<HTMLElement>(spinnerSel);
+			if (spinner?.parentNode) {
+				spinner.parentNode.removeChild(spinner);
+			}
 		}
-		this._element.classList.remove(this._config.loadingClass);
+		root.classList.remove(this._config.loadingClass ?? 'loading');
 
 		// --- 6. Remove instance reference from the DOM element ---
-		const elementWithInstance = KTDataTable.asElementWithInstance(
-			this._element,
-		);
+		const elementWithInstance = KTDataTable.asElementWithInstance(root);
 		if (elementWithInstance.instance) {
 			delete elementWithInstance.instance;
 		}
 
+		KTData.remove(root, this._name);
+
 		// --- 7. (Optional) Clear localStorage state ---
 		// Uncomment the following line if you want to clear state on dispose:
 		// this._deleteState();

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[];