@keenthemes/ktui 1.2.0 → 1.2.1

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

@@ -79,7 +79,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 +142,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 +198,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

@@ -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);
@@ -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);
@@ -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();
 		});
 	});

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

@@ -349,12 +349,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');

package/src/components/select/utils.ts

@@ -372,7 +372,11 @@ export class FocusManager {
 		const focusedEl = this._element.querySelector(
 			`${this._optionsSelector}.${this._focusClass}`,
 		) as HTMLElement | null;
-		if (focusedEl && !focusedEl.classList.contains('hidden') && focusedEl.style.display !== 'none') {
+		if (
+			focusedEl &&
+			!focusedEl.classList.contains('hidden') &&
+			focusedEl.style.display !== 'none'
+		) {
 			const idx = options.indexOf(focusedEl);
 			if (idx >= 0) {
 				this._focusedOptionIndex = idx;

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

@@ -15,8 +15,13 @@ describe('KTSticky', () => {
 	beforeEach(() => {
 		document.body.innerHTML = '';
 		scrollTop = 0;
-		vi.spyOn(KTDomModule.default, 'getScrollTop').mockImplementation(() => scrollTop);
-		vi.spyOn(KTDomModule.default, 'getViewPort').mockReturnValue({ height: 800, width: 1024 });
+		vi.spyOn(KTDomModule.default, 'getScrollTop').mockImplementation(
+			() => scrollTop,
+		);
+		vi.spyOn(KTDomModule.default, 'getViewPort').mockReturnValue({
+			height: 800,
+			width: 1024,
+		});
 
 		wrapper = document.createElement('div');
 		wrapper.setAttribute('data-kt-sticky-wrapper', 'true');
@@ -151,7 +156,9 @@ describe('KTSticky', () => {
 		it('fires change event when sticky becomes active and when released', async () => {
 			const instance = new KTSticky(stickyEl);
 			const changes: { active: boolean }[] = [];
-			instance.on('change', (payload: { active: boolean }) => changes.push(payload));
+			instance.on('change', (payload: { active: boolean }) =>
+				changes.push(payload),
+			);
 
 			scrollTop = 150;
 			window.dispatchEvent(new Event('scroll', { bubbles: true }));

package/src/components/sticky/sticky.ts

@@ -119,42 +119,35 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 
 		// Store scroll handler reference for cleanup
 		this._scrollHandler = () => {
-
 			this._isScrolling = true;
 
-			if(this._isActive() === true){
-
+			if (this._isActive() === true) {
 				this._debounceScroll(() => {
-
 					this._isScrolling = false;
 					this._process();
-
 				}, 200);
-
-			}else{
-
+			} else {
 				this._isScrolling = false;
 				this._process();
-
 			}
-
 		};
 
 		if (this._targetElement) {
 			if (this._targetElement === document) {
-				window.addEventListener('scroll', this._scrollHandler, { passive: true });
+				window.addEventListener('scroll', this._scrollHandler, {
+					passive: true,
+				});
 			} else {
 				(this._targetElement as HTMLElement).addEventListener(
 					'scroll',
 					this._scrollHandler,
-					{ passive: true }
+					{ passive: true },
 				);
 			}
 		}
 	}
 
 	protected _debounceScroll(callback: () => void, delay: number = 200): void {
-
 		if (this._scrollTimeout) {
 			clearTimeout(this._scrollTimeout);
 		}
@@ -162,7 +155,6 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 		this._scrollTimeout = setTimeout(() => {
 			callback();
 		}, delay);
-
 	}
 
 	protected _process(): void {
@@ -352,7 +344,7 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 		const activeClassList = this._getOption('activeClass') as string;
 		if (activeClassList) {
 			KTDom.addClass(this._element, activeClassList);
-		}else{
+		} else {
 			const classList = this._getOption('class') as string;
 			if (classList) {
 				KTDom.addClass(this._element, classList);
@@ -387,10 +379,10 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 		const activeClassList = this._getOption('activeClass') as string;
 		if (activeClassList) {
 			KTDom.removeClass(this._element, activeClassList);
-		}else{
+		} else {
 			const classList = this._getOption('class') as string;
 			if (classList) {
-					KTDom.removeClass(this._element, classList);
+				KTDom.removeClass(this._element, classList);
 			}
 		}
 
@@ -399,12 +391,11 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 			KTDom.addClass(this._element, releaseClassList);
 		}
 
-		if(this._eventTriggerState === false){
+		if (this._eventTriggerState === false) {
 			const releaseDelay = this._getOption('releaseDelay') as number;
-			if(releaseDelay && this._timeoutState === null){
+			if (releaseDelay && this._timeoutState === null) {
 				this._timeoutState = setTimeout(() => {
-
-					if (!this._element){
+					if (!this._element) {
 						return;
 					}
 
@@ -413,12 +404,11 @@ export class KTSticky extends KTComponent implements KTStickyInterface {
 					}
 
 					this._timeoutState = null;
-
 				}, releaseDelay);
-			}else{
+			} else {
 				this._resetStyles();
 			}
-		}else{
+		} else {
 			this._timeoutState = null;
 		}
 	}

package/src/components/sticky/types.ts

@@ -19,9 +19,9 @@ export interface KTStickyConfigInterface {
 	reverse: boolean;
 	release: string;
 	activate: string;
-	releaseDelay: number,
-	activeClass: string,
-	releaseClass: string,
+	releaseDelay: number;
+	activeClass: string;
+	releaseClass: string;
 }
 
 export interface KTStickyInterface {