@keenthemes/ktui 1.2.0 → 1.2.2

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/component.ts

@@ -19,7 +19,7 @@ export default class KTComponent {
 	protected _name: string;
 	protected _defaultConfig: object;
 	protected _config: object;
-	protected _events: Map<string, Map<string, CallableFunction>>;
+	protected _events: Map<string, Map<string, CallableFunction>> = new Map();
 	protected _uid: string | null = null;
 	protected _element: HTMLElement | null = null;
 
@@ -67,7 +67,7 @@ export default class KTComponent {
 
 	protected async _fireEvent(
 		eventType: string,
-		payload: object = null,
+		payload: object | null = null,
 	): Promise<void> {
 		const callbacks = this._events.get(eventType);
 
@@ -86,7 +86,10 @@ export default class KTComponent {
 		);
 	}
 
-	protected _dispatchEvent(eventType: string, payload: object = null): void {
+	protected _dispatchEvent(
+		eventType: string,
+		payload: object | null = null,
+	): void {
 		const event = new CustomEvent(eventType, {
 			detail: { payload },
 			bubbles: true,
@@ -100,6 +103,9 @@ export default class KTComponent {
 
 	protected _getOption(name: string): KTOptionType {
 		const value = this._config[name as keyof object];
+		if (!this._element) {
+			return value as KTOptionType;
+		}
 		const reponsiveValue = KTDom.getCssProp(
 			this._element,
 			`--kt-${this._name}-${KTUtils.camelReverseCase(name)}`,
@@ -163,7 +169,11 @@ export default class KTComponent {
 			this._events.set(eventType, new Map());
 		}
 
-		this._events.get(eventType).set(eventId, callback);
+		const eventMap = this._events.get(eventType);
+		if (!eventMap) {
+			return eventId;
+		}
+		eventMap.set(eventId, callback);
 
 		return eventId;
 	}
@@ -176,7 +186,7 @@ export default class KTComponent {
 		return this._getOption(name as keyof object);
 	}
 
-	public getElement(): HTMLElement {
+	public getElement(): HTMLElement | null {
 		if (!this._element) return null;
 		return this._element;
 	}

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

@@ -8,6 +8,7 @@
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { createSortHandler } from '../datatable-sort';
+import { KTDataTableConfigInterface } from '../types';
 
 describe('KTDataTable - Currency/numeric sort', () => {
 	let thead: HTMLTableSectionElement;
@@ -29,7 +30,7 @@ describe('KTDataTable - Currency/numeric sort', () => {
 			},
 		};
 		const handler = createSortHandler(
-			config as any,
+			config as KTDataTableConfigInterface,
 			thead,
 			() => ({ sortField: null, sortOrder: '' }),
 			noop,
@@ -58,7 +59,7 @@ describe('KTDataTable - Currency/numeric sort', () => {
 			},
 		};
 		const handler = createSortHandler(
-			config as any,
+			config as KTDataTableConfigInterface,
 			thead,
 			() => ({ sortField: null, sortOrder: '' }),
 			noop,
@@ -67,11 +68,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) =>
@@ -83,7 +80,7 @@ describe('KTDataTable - Currency/numeric sort', () => {
 	it('without sortType numeric, sorts lexicographically (e.g. £123 before £20)', () => {
 		const config = { columns: {} };
 		const handler = createSortHandler(
-			config as any,
+			config as KTDataTableConfigInterface,
 			thead,
 			() => ({ sortField: null, sortOrder: '' }),
 			noop,
@@ -92,11 +89,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__/pagination-reset.test.ts

@@ -13,7 +13,7 @@ import { KTDataTableColumnFilterInterface } from '../types';
 describe('KTDataTable - Pagination Reset', () => {
 	let container: HTMLElement;
 	let tableElement: HTMLTableElement;
-	let datatable: KTDataTable<any>;
+	let datatable: KTDataTable<Record<string, unknown>>;
 
 	/**
 	 * Helper: Create a mock datatable with sample data
@@ -177,13 +177,16 @@ describe('KTDataTable - Pagination Reset', () => {
 				// Provide custom search callback that handles objects
 				search: {
 					delay: 500,
-					callback: (data: any[], search: string | object) => {
+					callback: (
+						data: Record<string, unknown>[],
+						search: string | object,
+					) => {
 						if (!search) return data;
 						// For object search, just return all data (simplified for test)
 						if (typeof search === 'object') return data;
 						// String search
-						return data.filter((item: any) =>
-							Object.values(item).some((value: any) =>
+						return data.filter((item: Record<string, unknown>) =>
+							Object.values(item).some((value: unknown) =>
 								String(value)
 									.toLowerCase()
 									.includes((search as string).toLowerCase()),