@keenthemes/ktui 1.2.5 → 1.2.7

package/src/components/datatable/index.ts

@@ -13,7 +13,15 @@ export type {
 	KTDataTableConfigInterface,
 	KTDataTableColumnFilterTypeInterface,
 	KTDataTableColumnFilterInterface,
+	KTDataTableTextFilterInterface,
+	KTDataTableNumericFilterInterface,
+	KTDataTableDateRangeFilterInterface,
 	KTDataTableCheckConfigInterface,
 	KTDataTableCheckInterface,
 	KTDataTableCheckChangePayloadInterface,
+	KTDataTableLockedRowsConfigInterface,
+	KTDataTableLockedColumnsConfigInterface,
+	KTDataTableLockedLayoutConfigInterface,
+	KTDataTableLayoutPluginContextInterface,
+	KTDataTableLayoutPluginInterface,
 } from './types';

package/src/components/datatable/types.ts

@@ -62,6 +62,69 @@ export interface KTDataTableInterface {
 	showSpinner(): void;
 
 	hideSpinner(): void;
+
+	/**
+	 * Redraw the table, optionally navigating to a specific page.
+	 * @param page The page number to navigate to (defaults to 1)
+	 */
+	redraw(page?: number): void;
+
+	/**
+	 * Search the data using a string query or object.
+	 * @param query The search query
+	 */
+	search(query: string | object): void;
+
+	/**
+	 * Set or replace a column filter.
+	 * @param filter The filter to apply
+	 */
+	setFilter(filter: KTDataTableColumnFilterInterface): void;
+
+	/**
+	 * Get the current state of the datatable.
+	 */
+	getState(): KTDataTableStateInterface;
+
+	/**
+	 * Dispose of the datatable instance, cleaning up event listeners and DOM nodes.
+	 */
+	dispose(): void;
+
+	/**
+	 * Check if all visible rows are checked (header checkbox state).
+	 */
+	isChecked(): boolean;
+
+	/**
+	 * Toggle all visible row checkboxes.
+	 */
+	toggle(): void;
+
+	/**
+	 * Check all visible row checkboxes.
+	 */
+	check(): void;
+
+	/**
+	 * Uncheck all visible row checkboxes.
+	 */
+	uncheck(): void;
+
+	/**
+	 * Get all checked row IDs.
+	 */
+	getChecked(): string[];
+
+	/**
+	 * Re-apply checkbox checked states to visible rows after a redraw or pagination change.
+	 */
+	refreshCheckboxes(): void;
+
+	/**
+	 * @deprecated Use {@link refreshCheckboxes} instead.
+	 */
+	update(): void;
 }
 
 export interface KTDataTableResponseDataInterface {
@@ -69,8 +132,40 @@ 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 {
+export interface KTDataTableConfigInterface<
+	T extends KTDataTableDataInterface = KTDataTableDataInterface,
+> {
 	requestMethod?: string;
 	requestHeaders?: { [key: string]: string };
 	requestCredentials?: RequestCredentials;
@@ -87,20 +182,18 @@ export interface KTDataTableConfigInterface {
 	stateNamespace?: string;
 	pageSizes?: number[];
 	columns?: {
-		[key: keyof KTDataTableDataInterface | string]: {
+		[key: string]: {
 			title?: string;
 			render?: (
-				item: KTDataTableDataInterface[keyof KTDataTableDataInterface] | string,
-				data: KTDataTableDataInterface,
+				item: T[keyof T] | string,
+				data: T,
 				context: KTDataTableInterface,
 			) => string | HTMLElement | DocumentFragment;
 			checkbox?: boolean;
 			createdCell?: (
 				cell: HTMLTableCellElement,
-				cellData:
-					| KTDataTableDataInterface[keyof KTDataTableDataInterface]
-					| string,
-				rowData: KTDataTableDataInterface,
+				cellData: T[keyof T] | string,
+				rowData: T,
 				row: HTMLTableRowElement,
 			) => void;
 			/**
@@ -114,11 +207,14 @@ export interface KTDataTableConfigInterface {
 			 * Use for custom formats (e.g. dates, combined fields, custom parsing).
 			 */
 			sortValue?: (
-				cellValue:
-					| KTDataTableDataInterface[keyof KTDataTableDataInterface]
-					| string,
-				rowData: KTDataTableDataInterface,
+				cellValue: T[keyof T] | string,
+				rowData: T,
 			) => number | string;
+			/**
+			 * Fixed width for this column when tableLayout is 'fixed'.
+			 * Accepts any CSS length value (e.g. '120px', '20%', '10rem').
+			 */
+			width?: string;
 		};
 	};
 
@@ -139,18 +235,15 @@ export interface KTDataTableConfigInterface {
 		};
 		// local data sort callback
 		callback?: (
-			data: KTDataTableDataInterface[],
-			sortField: keyof KTDataTableDataInterface | number,
+			data: T[],
+			sortField: keyof T | number,
 			sortOrder: KTDataTableSortOrderInterface,
-		) => KTDataTableDataInterface[];
+		) => T[];
 	};
 
 	search?: {
 		delay?: number; // delay in milliseconds
-		callback?: (
-			data: KTDataTableDataInterface[],
-			search: string,
-		) => KTDataTableDataInterface[]; // search callback
+		callback?: (data: T[], search: string) => T[]; // search callback
 	};
 
 	pagination?: {
@@ -187,8 +280,20 @@ export interface KTDataTableConfigInterface {
 		preserveSelection?: boolean;
 	};
 
+	/**
+	 * Table layout algorithm. When 'fixed', the table uses `table-layout: fixed`
+	 * and generates a `<colgroup>` to keep column widths consistent across pagination.
+	 * Column widths are read from `columns[key].width` (configured mode) or from
+	 * `data-kt-datatable-column-width` attribute on `<th>` elements (implicit mode).
+	 * @default 'auto'
+	 */
+	tableLayout?: 'auto' | 'fixed';
+
+	lockedLayout?: KTDataTableLockedLayoutConfigInterface;
+	layoutPlugin?: KTDataTableLayoutPluginInterface;
+
 	_state?: KTDataTableStateInterface;
-	_data?: KTDataTableDataInterface[];
+	_data?: T[];
 
 	loadingClass?: string;
 }
@@ -198,11 +303,28 @@ export type KTDataTableColumnFilterTypeInterface =
 	| 'numeric'
 	| 'dateRange';
 
-export type KTDataTableColumnFilterInterface = {
+export interface KTDataTableTextFilterInterface {
 	column: keyof KTDataTableDataInterface;
-	type: KTDataTableColumnFilterTypeInterface;
+	type: 'text';
 	value: string;
-};
+}
+
+export interface KTDataTableNumericFilterInterface {
+	column: keyof KTDataTableDataInterface;
+	type: 'numeric';
+	value: number;
+}
+
+export interface KTDataTableDateRangeFilterInterface {
+	column: keyof KTDataTableDataInterface;
+	type: 'dateRange';
+	value: { from: string; to: string };
+}
+
+export type KTDataTableColumnFilterInterface =
+	| KTDataTableTextFilterInterface
+	| KTDataTableNumericFilterInterface
+	| KTDataTableDateRangeFilterInterface;
 
 export interface KTDataTableCheckConfigInterface {
 	target: string;
@@ -224,3 +346,15 @@ export interface KTDataTableCheckInterface {
 export interface KTDataTableCheckChangePayloadInterface {
 	cancel?: boolean;
 }
+
+/**
+ * Stores original CSS classes from the server-rendered table,
+ * used to preserve styling after datatable redraws.
+ */
+export interface OriginalTableClasses {
+	tbody: string;
+	thead: string;
+	tr: string[];
+	td: string[][];
+	th: string[];
+}