@keenthemes/ktui 1.2.0 → 1.2.2

package/src/components/range-slider/range-slider.ts

@@ -0,0 +1,276 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import KTData from '../../helpers/data';
+import KTComponent from '../component';
+import {
+	KTRangeSliderConfigInterface,
+	KTRangeSliderEventPayloadInterface,
+	KTRangeSliderInterface,
+} from './types';
+
+declare global {
+	interface Window {
+		KTRangeSlider: typeof KTRangeSlider;
+	}
+}
+
+const FILL_VAR = '--kt-range-fill';
+
+export class KTRangeSlider
+	extends KTComponent
+	implements KTRangeSliderInterface
+{
+	protected override _name: string = 'range-slider';
+	protected override _defaultConfig: KTRangeSliderConfigInterface = {
+		output: '',
+		lazy: false,
+	};
+	protected override _config: KTRangeSliderConfigInterface =
+		this._defaultConfig;
+	protected _rangeInput: HTMLInputElement | null = null;
+	protected _onNativeInput: ((e: Event) => void) | null = null;
+	protected _onNativeChange: ((e: Event) => void) | null = null;
+
+	constructor(
+		element: HTMLElement,
+		config: KTRangeSliderConfigInterface | null = null,
+	) {
+		super();
+
+		const input = KTRangeSlider.findRangeInput(element);
+		if (!input) {
+			return;
+		}
+
+		if (this._shouldSkipInit(element)) {
+			return;
+		}
+
+		this._rangeInput = input;
+		this._init(element);
+		this._buildConfig(config);
+
+		this._onNativeInput = this._handleNativeInput.bind(this);
+		this._onNativeChange = this._handleNativeChange.bind(this);
+		// Delegate events to the root so we keep working if the preview
+		// re-renders and replaces the native range input element.
+		this._element?.addEventListener('input', this._onNativeInput);
+		this._element?.addEventListener('change', this._onNativeChange);
+
+		this._syncFromInput();
+	}
+
+	private static findRangeInput(root: HTMLElement): HTMLInputElement | null {
+		if (root instanceof HTMLInputElement && root.type === 'range') {
+			return root;
+		}
+		return root.querySelector<HTMLInputElement>('input[type="range"]');
+	}
+
+	protected _getOutputSelector(): string {
+		const raw = this._getOption('output');
+		return typeof raw === 'string' ? raw.trim() : '';
+	}
+
+	protected _resolveOutputElement(): HTMLElement | null {
+		const selector = this._getOutputSelector();
+		if (!selector || !this._element) {
+			return null;
+		}
+		const fromRoot = this._element.querySelector<HTMLElement>(selector);
+		if (fromRoot) {
+			return fromRoot;
+		}
+		return document.querySelector<HTMLElement>(selector);
+	}
+
+	protected _getNumericMin(): number {
+		const input = this._rangeInput;
+		if (!input) return 0;
+		const n =
+			typeof input.min === 'string' && input.min !== ''
+				? parseFloat(input.min)
+				: 0;
+		return Number.isFinite(n) ? n : 0;
+	}
+
+	protected _getNumericMax(): number {
+		const input = this._rangeInput;
+		if (!input) return 100;
+		if (typeof input.max === 'string' && input.max !== '') {
+			const n = parseFloat(input.max);
+			if (Number.isFinite(n)) return n;
+		}
+		return 100;
+	}
+
+	/** Reflects `step` for events; `undefined` when `step="any"`. */
+	protected _getStepForPayload(): number | undefined {
+		const input = this._rangeInput;
+		if (!input) return undefined;
+		const raw = input.getAttribute('step');
+		if (raw === 'any') return undefined;
+		if (raw === null || raw === '') return 1;
+		const n = parseFloat(raw);
+		return Number.isFinite(n) && n > 0 ? n : 1;
+	}
+
+	protected _getCurrentValue(): number {
+		const input = this._rangeInput;
+		if (!input) return 0;
+		const v =
+			typeof input.valueAsNumber === 'number' &&
+			!Number.isNaN(input.valueAsNumber)
+				? input.valueAsNumber
+				: parseFloat(input.value);
+		return Number.isFinite(v) ? v : 0;
+	}
+
+	protected _clamp(value: number, min: number, max: number): number {
+		if (max < min) {
+			return value;
+		}
+		return Math.min(max, Math.max(min, value));
+	}
+
+	protected _fillRatio(value: number, min: number, max: number): number {
+		if (max === min) {
+			return 0;
+		}
+		return (this._clamp(value, min, max) - min) / (max - min);
+	}
+
+	protected _buildEventPayload(): KTRangeSliderEventPayloadInterface {
+		const min = this._getNumericMin();
+		const max = this._getNumericMax();
+		const value = this._getCurrentValue();
+		const step = this._getStepForPayload();
+		return {
+			value,
+			min,
+			max,
+			...(step !== undefined ? { step } : {}),
+		};
+	}
+
+	protected _syncFromInput(): void {
+		if (!this._element || !this._rangeInput) {
+			return;
+		}
+
+		const min = this._getNumericMin();
+		const max = this._getNumericMax();
+		const value = this._getCurrentValue();
+		const ratio = this._fillRatio(value, min, max);
+
+		this._element.style.setProperty(FILL_VAR, String(ratio));
+
+		const out = this._resolveOutputElement();
+		if (out) {
+			out.textContent = String(this._rangeInput.value);
+		}
+	}
+
+	protected _handleNativeInput(_event: Event): void {
+		const event = _event as Event;
+		const target = event.target;
+		if (!(target instanceof HTMLInputElement) || target.type !== 'range') {
+			return;
+		}
+
+		this._rangeInput = target;
+		this._syncFromInput();
+
+		const payload = this._buildEventPayload();
+		this._fireEvent('input', payload);
+		this._dispatchEvent('kt.range-slider.input', payload);
+	}
+
+	protected _handleNativeChange(_event: Event): void {
+		const event = _event as Event;
+		const target = event.target;
+		if (!(target instanceof HTMLInputElement) || target.type !== 'range') {
+			return;
+		}
+
+		this._rangeInput = target;
+		this._syncFromInput();
+
+		const payload = this._buildEventPayload();
+		this._fireEvent('change', payload);
+		this._dispatchEvent('kt.range-slider.change', payload);
+	}
+
+	public getRangeInput(): HTMLInputElement | null {
+		return this._rangeInput;
+	}
+
+	public getValue(): number {
+		return this._getCurrentValue();
+	}
+
+	public override dispose(): void {
+		if (this._element) {
+			if (this._onNativeInput) {
+				this._element.removeEventListener('input', this._onNativeInput);
+			}
+			if (this._onNativeChange) {
+				this._element.removeEventListener('change', this._onNativeChange);
+			}
+		}
+		this._onNativeInput = null;
+		this._onNativeChange = null;
+		this._rangeInput = null;
+		if (this._element) {
+			this._element.style.removeProperty(FILL_VAR);
+		}
+		super.dispose();
+	}
+
+	public static getInstance(element: HTMLElement): KTRangeSlider | null {
+		if (!element) {
+			return null;
+		}
+		if (KTData.has(element, 'range-slider')) {
+			return KTData.get(element, 'range-slider') as KTRangeSlider;
+		}
+		return null;
+	}
+
+	public static getOrCreateInstance(
+		element: HTMLElement,
+		config?: KTRangeSliderConfigInterface,
+	): KTRangeSlider | null {
+		const existing = this.getInstance(element);
+		if (existing) {
+			return existing;
+		}
+		if (!this.findRangeInput(element)) {
+			return null;
+		}
+		new KTRangeSlider(element, config ?? undefined);
+		return this.getInstance(element);
+	}
+
+	public static createInstances(): void {
+		document
+			.querySelectorAll<HTMLElement>('[data-kt-range-slider]')
+			.forEach((el) => {
+				if (el.getAttribute('data-kt-range-slider-lazy') === 'true') {
+					return;
+				}
+				new KTRangeSlider(el);
+			});
+	}
+
+	public static init(): void {
+		KTRangeSlider.createInstances();
+	}
+}
+
+if (typeof window !== 'undefined') {
+	window.KTRangeSlider = KTRangeSlider;
+}

package/src/components/range-slider/types.ts

@@ -0,0 +1,36 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+/**
+ * Optional CSS selector (document or root-relative) for an element whose text
+ * updates with the current range value. Prefer `data-kt-range-slider-output` on the root.
+ */
+export interface KTRangeSliderConfigInterface {
+	/** Selector for the output element; also read from `data-kt-range-slider-output`. */
+	output?: string;
+
+	/**
+	 * When true, skip auto-init; use `getInstance` / `new KTRangeSlider(element)` manually.
+	 */
+	lazy?: boolean;
+}
+
+export interface KTRangeSliderEventPayloadInterface {
+	value: number;
+	min: number;
+	max: number;
+	/** From the input `step` attribute; omitted when `step="any"`. */
+	step?: number;
+}
+
+export interface KTRangeSliderInterface {
+	getOption(name: string): unknown;
+	getElement(): HTMLElement;
+	getRangeInput(): HTMLInputElement | null;
+	getValue(): number;
+	on(eventType: string, callback: CallableFunction): string;
+	off(eventType: string, eventId: string): void;
+	dispose(): void;
+}

package/src/components/rating/__tests__/rating.test.ts

@@ -104,7 +104,9 @@ describe('KTRating', () => {
 			const instance = new KTRating(ratingEl);
 			instance.setValue(3);
 			expect(instance.getValue()).toBe(3);
-			const checked = ratingEl.querySelector<HTMLInputElement>('input[type="radio"]:checked');
+			const checked = ratingEl.querySelector<HTMLInputElement>(
+				'input[type="radio"]:checked',
+			);
 			expect(checked?.value).toBe('3');
 			instance.dispose();
 		});
@@ -121,8 +123,11 @@ describe('KTRating', () => {
 		it('dispatches kt.rating.change when user selects a value', () => {
 			const instance = new KTRating(ratingEl);
 			const events: CustomEvent[] = [];
-			ratingEl.addEventListener('kt.rating.change', ((e: CustomEvent) => events.push(e)) as EventListener);
-			const radio3 = ratingEl.querySelector<HTMLInputElement>('input[type="radio"][value="3"]');
+			ratingEl.addEventListener('kt.rating.change', ((e: CustomEvent) =>
+				events.push(e)) as EventListener);
+			const radio3 = ratingEl.querySelector<HTMLInputElement>(
+				'input[type="radio"][value="3"]',
+			);
 			expect(radio3).not.toBeNull();
 			radio3!.checked = true;
 			radio3!.dispatchEvent(new Event('change', { bubbles: true }));
@@ -226,7 +231,9 @@ describe('KTRating', () => {
 			ratingEl.setAttribute('data-kt-rating-value', '2');
 			const instance = new KTRating(ratingEl);
 			expect(instance.getValue()).toBe(2);
-			const checked = ratingEl.querySelector<HTMLInputElement>('input[type="radio"]:checked');
+			const checked = ratingEl.querySelector<HTMLInputElement>(
+				'input[type="radio"]:checked',
+			);
 			expect(checked?.value).toBe('2');
 			instance.dispose();
 		});

package/src/components/rating/rating.ts

@@ -4,7 +4,6 @@
  */
 
 import KTData from '../../helpers/data';
-import KTDom from '../../helpers/dom';
 import KTComponent from '../component';
 import { KTRatingConfigInterface, KTRatingInterface } from './types';
 
@@ -79,7 +78,8 @@ export class KTRating extends KTComponent implements KTRatingInterface {
 		const svg = `<svg class="shrink-0 size-5" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">${path}</svg>`;
 
 		const container = document.createElement('div');
-		container.className = 'kt-rating flex flex-row-reverse justify-end items-center gap-0';
+		container.className =
+			'kt-rating flex flex-row-reverse justify-end items-center gap-0';
 		container.setAttribute('role', readonly ? 'img' : 'group');
 		container.setAttribute('aria-label', `Rating: ${value} of ${max}`);
 		if (readonly) {
@@ -141,13 +141,21 @@ export class KTRating extends KTComponent implements KTRatingInterface {
 			'text-muted-foreground/50 dark:text-muted-foreground/50';
 		const filledTokens = filledClass.split(' ');
 		const unfilledTokens = unfilledClass.split(' ');
-		this._container.querySelectorAll<HTMLElement>('.kt-rating-label').forEach((label) => {
-			const v = parseInt(label.getAttribute('data-kt-rating-value') || '0', 10);
-			const filled = v <= (val ?? 0);
-			label.classList.remove(...filledTokens, ...unfilledTokens);
-			label.classList.add(...(filled ? filledTokens : unfilledTokens));
-		});
-		this._container.setAttribute('aria-valuenow', val != null ? String(val) : '0');
+		this._container
+			.querySelectorAll<HTMLElement>('.kt-rating-label')
+			.forEach((label) => {
+				const v = parseInt(
+					label.getAttribute('data-kt-rating-value') || '0',
+					10,
+				);
+				const filled = v <= (val ?? 0);
+				label.classList.remove(...filledTokens, ...unfilledTokens);
+				label.classList.add(...(filled ? filledTokens : unfilledTokens));
+			});
+		this._container.setAttribute(
+			'aria-valuenow',
+			val != null ? String(val) : '0',
+		);
 		this._container.setAttribute('aria-label', `Rating: ${val ?? 0} of ${max}`);
 	}
 
@@ -189,9 +197,11 @@ export class KTRating extends KTComponent implements KTRatingInterface {
 				this._updateInteractiveDisplay();
 			}
 		} else {
-			this._container.querySelectorAll<HTMLInputElement>('input[type="radio"]').forEach((r) => {
-				r.checked = false;
-			});
+			this._container
+				.querySelectorAll<HTMLInputElement>('input[type="radio"]')
+				.forEach((r) => {
+					r.checked = false;
+				});
 			this._updateInteractiveDisplay();
 		}
 	}

package/src/components/repeater/__tests__/repeater.test.ts

@@ -2,7 +2,7 @@
  * Tests for KTRepeater component
  */
 
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { KTRepeater } from '../repeater';
 
 function createFixture(options?: {
@@ -150,7 +150,8 @@ describe('KTRepeater', () => {
 			const { trigger } = createFixture();
 			const instance = new KTRepeater(trigger);
 			const events: CustomEvent[] = [];
-			trigger.addEventListener('add', ((e: Event) => events.push(e as CustomEvent)) as EventListener);
+			trigger.addEventListener('add', ((e: Event) =>
+				events.push(e as CustomEvent)) as EventListener);
 			instance.add();
 			expect(events.length).toBe(1);
 			expect(events[0].detail?.payload?.element).toBeInstanceOf(HTMLElement);
@@ -160,7 +161,7 @@ describe('KTRepeater', () => {
 
 	describe('limit', () => {
 		it('does not add more clones when at limit', () => {
-			const { wrapper, trigger } = createFixture({ limit: 2 });
+			const { trigger, wrapper } = createFixture({ limit: 2 });
 			const instance = new KTRepeater(trigger);
 			expect(wrapper.children.length).toBe(1);
 			instance.add();
@@ -173,7 +174,7 @@ describe('KTRepeater', () => {
 		});
 
 		it('disables trigger when at limit', () => {
-			const { wrapper, trigger } = createFixture({ limit: 2 });
+			const { trigger } = createFixture({ limit: 2 });
 			const instance = new KTRepeater(trigger);
 			expect(trigger.hasAttribute('disabled')).toBe(false);
 			instance.add();
@@ -182,7 +183,10 @@ describe('KTRepeater', () => {
 		});
 
 		it('re-enables trigger when a clone is removed (delete) and count drops below limit', () => {
-			const { wrapper, trigger } = createFixture({ limit: 2, withDeleteInTarget: true });
+			const { wrapper, trigger } = createFixture({
+				limit: 2,
+				withDeleteInTarget: true,
+			});
 			const instance = new KTRepeater(trigger);
 			instance.add();
 			expect(wrapper.children.length).toBe(2);
@@ -197,7 +201,7 @@ describe('KTRepeater', () => {
 		});
 
 		it('allows unlimited clones when limit is 0 or omitted', () => {
-			const { wrapper, trigger } = createFixture();
+			const { trigger, wrapper } = createFixture();
 			trigger.removeAttribute('data-kt-repeater-limit');
 			const instance = new KTRepeater(trigger);
 			for (let i = 0; i < 5; i++) instance.add();
@@ -213,7 +217,9 @@ describe('KTRepeater', () => {
 			instance.add();
 			expect(wrapper.children.length).toBe(2);
 			const firstClone = wrapper.children[1];
-			const deleteBtn = firstClone.querySelector('[data-kt-repeater-delete]') as HTMLElement;
+			const deleteBtn = firstClone.querySelector(
+				'[data-kt-repeater-delete]',
+			) as HTMLElement;
 			deleteBtn.click();
 			expect(wrapper.children.length).toBe(1);
 			instance.dispose();
@@ -224,7 +230,9 @@ describe('KTRepeater', () => {
 			const instance = new KTRepeater(trigger);
 			expect(wrapper.children.length).toBe(1);
 			const onlyRow = wrapper.children[0];
-			const deleteBtn = onlyRow.querySelector('[data-kt-repeater-delete]') as HTMLElement;
+			const deleteBtn = onlyRow.querySelector(
+				'[data-kt-repeater-delete]',
+			) as HTMLElement;
 			deleteBtn.click();
 			expect(wrapper.children.length).toBe(1);
 			instance.dispose();
@@ -233,12 +241,17 @@ describe('KTRepeater', () => {
 
 	describe('predefined (hidden) template', () => {
 		it('clones from hidden template and appends to wrapper', () => {
-			const { wrapper, trigger } = createFixture({ hiddenTemplate: true, withInitialChild: false });
+			const { wrapper, trigger } = createFixture({
+				hiddenTemplate: true,
+				withInitialChild: false,
+			});
 			expect(wrapper.children.length).toBe(0);
 			const instance = new KTRepeater(trigger);
 			instance.add();
 			expect(wrapper.children.length).toBe(1);
-			expect(wrapper.querySelector('input[placeholder="Enter Name"]')).not.toBeNull();
+			expect(
+				wrapper.querySelector('input[placeholder="Enter Name"]'),
+			).not.toBeNull();
 			instance.dispose();
 		});
 	});
@@ -266,7 +279,7 @@ describe('KTRepeater', () => {
 		});
 
 		it('createInstances initializes all data-kt-repeater elements', () => {
-			const { container, wrapper, trigger } = createFixture();
+			const { container, trigger } = createFixture();
 			const trigger2 = document.createElement('button');
 			trigger2.setAttribute('data-kt-repeater', '');
 			trigger2.setAttribute('data-kt-repeater-target', '#repeater-target');

package/src/components/repeater/repeater.ts

@@ -23,8 +23,8 @@ export class KTRepeater extends KTComponent implements KTRepeaterInterface {
 		wrapper: '',
 		limit: 0,
 	};
-	protected override _config: KTRepeaterConfigInterface =
-		this._defaultConfig as KTRepeaterConfigInterface;
+	protected override _config: KTRepeaterConfigInterface = this
+		._defaultConfig as KTRepeaterConfigInterface;
 	protected _wrapperElement: HTMLElement | null = null;
 	protected _deleteHandler: (e: Event) => void;
 
@@ -155,7 +155,9 @@ export class KTRepeater extends KTComponent implements KTRepeaterInterface {
 		element: HTMLElement,
 		config?: KTRepeaterConfigInterface,
 	): KTRepeater {
-		return this.getInstance(element) || new KTRepeater(element, config ?? undefined);
+		return (
+			this.getInstance(element) || new KTRepeater(element, config ?? undefined)
+		);
 	}
 
 	public static createInstances(): void {

package/src/components/select/__tests__/ux-behaviors.test.ts

@@ -34,7 +34,7 @@ describe('KTSelect UX Behaviors', () => {
 	/**
 	 * Helper to wait for KTSelect to fully initialize
 	 */
-	const waitForInit = async (select: KTSelect): Promise<void> => {
+	const waitForInit = async (_select: KTSelect): Promise<void> => {
 		// Wait for async initialization - KTSelect uses promises for setup
 		await waitFor(200);
 		// Wait for next tick to ensure all modules are initialized
@@ -52,7 +52,8 @@ describe('KTSelect UX Behaviors', () => {
 		// Clean up all KTSelect instances
 		const selects = document.querySelectorAll('.kt-select');
 		selects.forEach((select) => {
-			const instance = (select as any).instance;
+			const instance = (select as HTMLElement & { instance?: KTSelect })
+				.instance;
 			if (instance && typeof instance.destroy === 'function') {
 				instance.destroy();
 			}
@@ -60,7 +61,7 @@ describe('KTSelect UX Behaviors', () => {
 
 		// Clear document body
 		document.body.innerHTML = '';
-		container = null as any;
+		container = null as unknown as HTMLElement;
 
 		// Clear all event listeners
 		vi.clearAllMocks();
@@ -349,12 +350,30 @@ describe('KTSelect UX Behaviors', () => {
 			await waitFor(50);
 
 			// ArrowDown focuses first option; ArrowUp from first wraps to last (3). Enter selects focused.
-			searchInput.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true, cancelable: true }));
+			searchInput.dispatchEvent(
+				new KeyboardEvent('keydown', {
+					key: 'ArrowDown',
+					bubbles: true,
+					cancelable: true,
+				}),
+			);
 			await waitFor(20);
-			searchInput.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true, cancelable: true }));
+			searchInput.dispatchEvent(
+				new KeyboardEvent('keydown', {
+					key: 'ArrowUp',
+					bubbles: true,
+					cancelable: true,
+				}),
+			);
 			await waitFor(20);
 
-			searchInput.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, cancelable: true }));
+			searchInput.dispatchEvent(
+				new KeyboardEvent('keydown', {
+					key: 'Enter',
+					bubbles: true,
+					cancelable: true,
+				}),
+			);
 			await waitFor(150);
 
 			expect(select.getSelectedOptions()).toContain('3');