@keenthemes/ktui 1.2.0 → 1.2.1

package/src/components/clipboard/clipboard.ts

@@ -0,0 +1,416 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import KTComponent from '../component';
+import KTData from '../../helpers/data';
+import KTDom from '../../helpers/dom';
+import {
+	KTClipboardActionType,
+	KTClipboardConfigInterface,
+	KTClipboardInterface,
+} from './types';
+
+type KTClipboardEventPayload = {
+	action: KTClipboardActionType;
+	text: string | null;
+	target: string | null;
+	error?: string;
+};
+
+declare global {
+	interface Window {
+		KTClipboard: typeof KTClipboard;
+	}
+}
+
+export class KTClipboard extends KTComponent implements KTClipboardInterface {
+	protected override _name: string = 'clipboard';
+
+	protected override _defaultConfig: KTClipboardConfigInterface = {
+		target: '',
+		text: '',
+		action: 'copy',
+		copiedClass: '',
+		successEvent: 'kt.clipboard.success',
+		errorEvent: 'kt.clipboard.error',
+	};
+
+	protected override _config: KTClipboardConfigInterface = this
+		._defaultConfig as KTClipboardConfigInterface;
+
+	private _activateHandler: ((event: Event) => void) | null = null;
+
+	constructor(
+		element: HTMLElement,
+		config: KTClipboardConfigInterface | null = null,
+	) {
+		super();
+
+		// Ensure we don't double bind handlers on the same trigger.
+		if (this._shouldSkipInit(element)) {
+			return;
+		}
+
+		this._init(element);
+		this._buildConfig(config);
+
+		if (!this._element) return;
+
+		this._activateHandler = this._handleActivate.bind(this);
+		this._element.addEventListener('click', this._activateHandler);
+	}
+
+	private _getSuccessEventName(): string {
+		const eventName = this._getOption('successEvent');
+		return typeof eventName === 'string' && eventName.length > 0
+			? eventName
+			: 'kt.clipboard.success';
+	}
+
+	private _getErrorEventName(): string {
+		const eventName = this._getOption('errorEvent');
+		return typeof eventName === 'string' && eventName.length > 0
+			? eventName
+			: 'kt.clipboard.error';
+	}
+
+	private _getAction(): KTClipboardActionType {
+		const action = this._getOption('action');
+		return action === 'cut' ? 'cut' : 'copy';
+	}
+
+	private _getTrimmedString(optionValue: unknown): string {
+		return typeof optionValue === 'string' ? optionValue.trim() : '';
+	}
+
+	private _getPredefinedText(): string {
+		const text = this._getOption('text');
+		return this._getTrimmedString(text);
+	}
+
+	private _getTargetSelector(): string {
+		const target = this._getOption('target');
+		return this._getTrimmedString(target);
+	}
+
+	private _getCopiedClass(): string {
+		const copiedClass = this._getOption('copiedClass');
+		return this._getTrimmedString(copiedClass);
+	}
+
+	private _setCopiedClass(shouldSet: boolean): void {
+		const copiedClass = this._getCopiedClass();
+		if (!copiedClass || !this._element) return;
+
+		// Keep deterministic behavior: remove any previous state before toggling.
+		KTDom.removeClass(this._element, copiedClass);
+		if (shouldSet) {
+			KTDom.addClass(this._element, copiedClass);
+		}
+	}
+
+	private _isInputLike(element: HTMLElement): boolean {
+		return element.tagName === 'INPUT' || element.tagName === 'TEXTAREA';
+	}
+
+	private _readTargetValue(target: HTMLElement): string {
+		if (this._isInputLike(target)) {
+			return (target as HTMLInputElement | HTMLTextAreaElement).value ?? '';
+		}
+
+		return target.textContent ?? '';
+	}
+
+	private _execCommandCopy(text: string): boolean {
+		const textarea = document.createElement('textarea');
+		textarea.value = text;
+
+		// Avoid scrolling to bottom on iOS/Safari and keep it out of layout.
+		textarea.style.position = 'fixed';
+		textarea.style.top = '0';
+		textarea.style.left = '0';
+		textarea.style.opacity = '0';
+		textarea.style.pointerEvents = 'none';
+
+		document.body.appendChild(textarea);
+		textarea.focus();
+		textarea.select();
+		// Some browsers require explicit range selection.
+		textarea.setSelectionRange(0, textarea.value.length);
+
+		try {
+			return document.execCommand('copy');
+		} catch {
+			return false;
+		} finally {
+			textarea.remove();
+		}
+	}
+
+	private async _writeText(text: string): Promise<boolean> {
+		// Native Clipboard API (requires secure context).
+		const clipboard =
+			typeof navigator !== 'undefined' ? navigator.clipboard : null;
+		const writeText =
+			clipboard && typeof clipboard.writeText === 'function'
+				? clipboard.writeText.bind(clipboard)
+				: null;
+
+		if (writeText) {
+			await writeText(text);
+			return true;
+		}
+
+		const ok = this._execCommandCopy(text);
+		if (!ok) {
+			throw new Error('Clipboard copy failed.');
+		}
+
+		return true;
+	}
+
+	private async _handleActivate(event: Event): Promise<void> {
+		event.preventDefault();
+
+		const action = this._getAction();
+		const successEventName = this._getSuccessEventName();
+		const errorEventName = this._getErrorEventName();
+		const textFromConfig = this._getPredefinedText();
+		const targetSelector = this._getTargetSelector();
+		const hasPredefinedText = Boolean(
+			this._element?.hasAttribute('data-kt-clipboard-text'),
+		);
+
+		// Deterministic precedence:
+		// - If `data-kt-clipboard-text` attribute is present, it wins over target.
+		if (hasPredefinedText) {
+			let targetElForCut: HTMLElement | null = null;
+
+			// `cut` requires an editable target (input/textarea) even when predefined text is used.
+			if (action === 'cut') {
+				if (!targetSelector) {
+					this._setCopiedClass(false);
+
+					const payload: KTClipboardEventPayload = {
+						action,
+						text: null,
+						target: null,
+						error:
+							'Cut action requires data-kt-clipboard-target pointing to an input/textarea.',
+					};
+
+					this._fireEvent(errorEventName, payload);
+					this._dispatchEvent(errorEventName, payload);
+					return;
+				}
+
+				targetElForCut = KTDom.getElement(targetSelector) as HTMLElement | null;
+
+				if (!targetElForCut || !this._isInputLike(targetElForCut)) {
+					this._setCopiedClass(false);
+
+					const payload: KTClipboardEventPayload = {
+						action,
+						text: null,
+						target: targetSelector,
+						error: 'Cut action is only supported for input/textarea targets.',
+					};
+
+					this._fireEvent(errorEventName, payload);
+					this._dispatchEvent(errorEventName, payload);
+					return;
+				}
+			}
+
+			// Treat empty/whitespace-only predefined text as invalid.
+			if (!textFromConfig) {
+				this._setCopiedClass(false);
+
+				const payload: KTClipboardEventPayload = {
+					action,
+					text: null,
+					target: targetSelector || null,
+					error: 'Predefined clipboard text is empty.',
+				};
+
+				this._fireEvent(errorEventName, payload);
+				this._dispatchEvent(errorEventName, payload);
+				return;
+			}
+
+			try {
+				await this._writeText(textFromConfig);
+
+				// For `cut`, clear the editable target after successful clipboard write.
+				if (action === 'cut' && targetElForCut) {
+					(targetElForCut as HTMLInputElement | HTMLTextAreaElement).value = '';
+					targetElForCut.dispatchEvent(new Event('input', { bubbles: true }));
+				}
+
+				this._setCopiedClass(true);
+
+				const payload: KTClipboardEventPayload = {
+					action,
+					text: textFromConfig,
+					target: targetSelector || null,
+				};
+
+				this._fireEvent(successEventName, payload);
+				this._dispatchEvent(successEventName, payload);
+			} catch (error) {
+				this._setCopiedClass(false);
+
+				const payload: KTClipboardEventPayload = {
+					action,
+					text: textFromConfig,
+					target: targetSelector || null,
+					error:
+						error instanceof Error ? error.message : String(error ?? 'Unknown'),
+				};
+
+				this._fireEvent(errorEventName, payload);
+				this._dispatchEvent(errorEventName, payload);
+			}
+
+			return;
+		}
+
+		// No usable predefined text; copy from target.
+		if (!targetSelector) {
+			this._setCopiedClass(false);
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: null,
+				target: null,
+				error:
+					'Missing clipboard source (provide data-kt-clipboard-text or data-kt-clipboard-target).',
+			};
+
+			this._fireEvent(errorEventName, payload);
+			this._dispatchEvent(errorEventName, payload);
+			return;
+		}
+
+		const targetEl = KTDom.getElement(targetSelector) as HTMLElement | null;
+		if (!targetEl) {
+			this._setCopiedClass(false);
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: null,
+				target: targetSelector,
+				error: `Clipboard target not found: ${targetSelector}`,
+			};
+
+			this._fireEvent(errorEventName, payload);
+			this._dispatchEvent(errorEventName, payload);
+			return;
+		}
+
+		const value = this._readTargetValue(targetEl).trim();
+		if (!value) {
+			this._setCopiedClass(false);
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: null,
+				target: targetSelector,
+				error: 'Target content is empty.',
+			};
+
+			this._fireEvent(errorEventName, payload);
+			this._dispatchEvent(errorEventName, payload);
+			return;
+		}
+
+		// Cut action: only allowed for input/textarea.
+		if (action === 'cut' && !this._isInputLike(targetEl)) {
+			this._setCopiedClass(false);
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: null,
+				target: targetSelector,
+				error: 'Cut action is only supported for input/textarea targets.',
+			};
+
+			this._fireEvent(errorEventName, payload);
+			this._dispatchEvent(errorEventName, payload);
+			return;
+		}
+
+		try {
+			await this._writeText(value);
+			this._setCopiedClass(true);
+
+			if (action === 'cut') {
+				(targetEl as HTMLInputElement | HTMLTextAreaElement).value = '';
+				targetEl.dispatchEvent(new Event('input', { bubbles: true }));
+			}
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: value,
+				target: targetSelector,
+			};
+
+			this._fireEvent(successEventName, payload);
+			this._dispatchEvent(successEventName, payload);
+		} catch (error) {
+			this._setCopiedClass(false);
+
+			const payload: KTClipboardEventPayload = {
+				action,
+				text: null,
+				target: targetSelector,
+				error:
+					error instanceof Error ? error.message : String(error ?? 'Unknown'),
+			};
+
+			this._fireEvent(errorEventName, payload);
+			this._dispatchEvent(errorEventName, payload);
+		}
+	}
+
+	public override dispose(): void {
+		if (this._element && this._activateHandler) {
+			this._element.removeEventListener('click', this._activateHandler);
+		}
+		this._activateHandler = null;
+		super.dispose();
+	}
+
+	public static getInstance(element: HTMLElement): KTClipboard | null {
+		if (!element) return null;
+		if (KTData.has(element, 'clipboard')) {
+			return KTData.get(element, 'clipboard') as KTClipboard;
+		}
+		return null;
+	}
+
+	public static getOrCreateInstance(
+		element: HTMLElement,
+		config?: KTClipboardConfigInterface,
+	): KTClipboard {
+		return (
+			this.getInstance(element) || new KTClipboard(element, config ?? undefined)
+		);
+	}
+
+	public static createInstances(): void {
+		document.querySelectorAll('[data-kt-clipboard]').forEach((el) => {
+			new KTClipboard(el as HTMLElement);
+		});
+	}
+
+	public static init(): void {
+		KTClipboard.createInstances();
+	}
+}
+
+if (typeof window !== 'undefined') {
+	window.KTClipboard = KTClipboard;
+}

package/src/components/clipboard/index.ts

@@ -0,0 +1,2 @@
+export { KTClipboard } from './clipboard';
+export type { KTClipboardConfigInterface, KTClipboardInterface } from './types';

package/src/components/clipboard/types.ts

@@ -0,0 +1,51 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+export type KTClipboardActionType = 'copy' | 'cut';
+
+export interface KTClipboardConfigInterface {
+	/**
+	 * CSS selector for the element to read from when copying from target.
+	 * For `input`/`textarea`, reads `.value`; for other elements, reads `.textContent`.
+	 */
+	target?: string;
+
+	/**
+	 * Static string to copy. Takes precedence over `target` when both are present.
+	 */
+	text?: string;
+
+	/**
+	 * Clipboard action to perform.
+	 * - `copy` (default)
+	 * - `cut` (only valid for `input`/`textarea` targets)
+	 */
+	action?: KTClipboardActionType;
+
+	/**
+	 * Optional class toggled on the trigger when copy/cut succeeds.
+	 */
+	copiedClass?: string;
+
+	/**
+	 * Optional DOM event name dispatched on success.
+	 * Defaults to `kt.clipboard.success`.
+	 */
+	successEvent?: string;
+
+	/**
+	 * Optional DOM event name dispatched on failure.
+	 * Defaults to `kt.clipboard.error`.
+	 */
+	errorEvent?: string;
+}
+
+export interface KTClipboardInterface {
+	getOption(name: string): unknown;
+	getElement(): HTMLElement | null;
+	on(eventType: string, callback: CallableFunction): string;
+	off(eventType: string, eventId: string): void;
+	dispose(): void;
+}

package/src/components/datatable/__tests__/currency-sort.test.ts

@@ -67,11 +67,7 @@ describe('KTDataTable - Currency/numeric sort', () => {
 			noop,
 		);
 
-		const data = [
-			{ price: '£5' },
-			{ price: '£20' },
-			{ price: '£123' },
-		];
+		const data = [{ price: '£5' }, { price: '£20' }, { price: '£123' }];
 		const sorted = handler.sortData(data, 'price', 'desc');
 
 		const numericOrder = sorted.map((row) =>
@@ -92,11 +88,7 @@ describe('KTDataTable - Currency/numeric sort', () => {
 			noop,
 		);
 
-		const data = [
-			{ price: '£123' },
-			{ price: '£20' },
-			{ price: '£5' },
-		];
+		const data = [{ price: '£123' }, { price: '£20' }, { price: '£5' }];
 		const sorted = handler.sortData(data, 'price', 'asc');
 
 		// String sort: "£123" < "£20" < "£5" (1 < 2 < 5)

package/src/components/datatable/__tests__/multi-row-headers.test.ts

@@ -89,7 +89,7 @@ describe('KTDataTable - Multi-row header column count', () => {
 
 	it('should render exactly 17 columns when thead has multi-row headers and no data-kt-datatable-column', async () => {
 		createMultiRowHeaderTable(2);
-		const datatable = new KTDataTable(container, { stateSave: false });
+		new KTDataTable(container, { stateSave: false });
 		await vi.runAllTimersAsync();
 
 		const tbody = tableElement.tBodies[0];
@@ -107,7 +107,7 @@ describe('KTDataTable - Multi-row header column count', () => {
 		createMultiRowHeaderTable(0);
 		const tbody = tableElement.querySelector('tbody');
 		expect(tbody).toBeDefined();
-		const datatable = new KTDataTable(container, { stateSave: false });
+		new KTDataTable(container, { stateSave: false });
 		await vi.runAllTimersAsync();
 
 		const noticeRow = tableElement.tBodies[0].querySelector('tr');

package/src/components/datatable/__tests__/race-conditions.test.ts

@@ -43,7 +43,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 		// Mock fetch to track requests and signals
 		abortSignals = [];
-		mockFetch = vi.fn<typeof fetch>((url, options) => {
+		mockFetch = vi.fn<typeof fetch>((_url, options) => {
 			// Store abort signal for verification
 			if (options?.signal) {
 				abortSignals.push(options.signal);
@@ -98,12 +98,9 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 	describe('AbortController Integration', () => {
 		it('should create AbortController for remote data requests', async () => {
-			const datatable = new KTDataTable(
-				container.querySelector('[data-kt-datatable="true"]')!,
-				{
-					apiEndpoint: '/api/data',
-				},
-			);
+			new KTDataTable(container.querySelector('[data-kt-datatable="true"]')!, {
+				apiEndpoint: '/api/data',
+			});
 
 			await waitFor(150);
 
@@ -186,7 +183,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 			// Mock to capture request sequence
 			mockFetch.mockImplementation(
-				(url: RequestInfo | URL, options?: RequestInit) => {
+				(_url: RequestInfo | URL, _options?: RequestInit) => {
 					callCount++;
 					const id = callCount;
 					requestIds.push(id);
@@ -293,7 +290,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 		it('should reset _isFetching flag even after fetch error', async () => {
 			let callCount = 0;
 			mockFetch.mockImplementation(
-				(url: RequestInfo | URL, options?: RequestInit) => {
+				(_url: RequestInfo | URL, _options?: RequestInit) => {
 					callCount++;
 					if (callCount === 1) {
 						// Return invalid JSON to trigger parse error
@@ -333,7 +330,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
 			) as HTMLElement;
-			const datatable = new KTDataTable(element, {
+			new KTDataTable(element, {
 				apiEndpoint: '/api/data',
 			});
 
@@ -410,7 +407,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 
 	describe('Event Handling During Race Conditions', () => {
 		it('should fire fetch event for successful requests', async () => {
-			const fetchEvents: any[] = [];
+			const fetchEvents: Event[] = [];
 
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
@@ -433,7 +430,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 		});
 
 		it('should fire fetched event after successful data load', async () => {
-			const fetchedEvents: any[] = [];
+			const fetchedEvents: Event[] = [];
 
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',
@@ -442,7 +439,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 				fetchedEvents.push(e);
 			});
 
-			const datatable = new KTDataTable(element, {
+			new KTDataTable(element, {
 				apiEndpoint: '/api/data',
 			});
 
@@ -453,7 +450,7 @@ describe('KTDataTable Race Condition Fixes', () => {
 		});
 
 		it('should not fire error events for AbortError', async () => {
-			const errorEvents: any[] = [];
+			const errorEvents: Event[] = [];
 
 			const element = container.querySelector(
 				'[data-kt-datatable="true"]',

package/src/components/datatable/datatable.ts

@@ -746,9 +746,8 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			return Object.keys(originalData[0]).length;
 		}
 		if (this._tbodyElement) {
-			const firstRow = this._tbodyElement.querySelector<HTMLTableRowElement>(
-				'tr',
-			);
+			const firstRow =
+				this._tbodyElement.querySelector<HTMLTableRowElement>('tr');
 			if (firstRow) {
 				return firstRow.querySelectorAll<HTMLTableCellElement>('td').length;
 			}
@@ -1052,8 +1051,7 @@ export class KTDataTable<T extends KTDataTableDataInterface>
 			th.hasAttribute('data-kt-datatable-column'),
 		);
 		// When no th has data-kt-datatable-column (e.g. multi-row headers), use logical column count from tbody so we don't overcount thead cells
-		const columnsToRender: HTMLTableCellElement[] =
-			ths.length > 0 ? ths : [];
+		const columnsToRender: HTMLTableCellElement[] = ths.length > 0 ? ths : [];
 		const logicalColumnCount =
 			ths.length > 0 ? ths.length : this._getLogicalColumnCount();