@keenthemes/ktui 1.1.6 → 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

@@ -0,0 +1,241 @@
+/**
+ * Tests for KTRating component
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { KTRating } from '../rating';
+
+describe('KTRating', () => {
+	let container: HTMLElement;
+	let ratingEl: HTMLElement;
+
+	beforeEach(() => {
+		document.body.innerHTML = '';
+		container = document.createElement('div');
+		container.id = 'test-container';
+		ratingEl = document.createElement('div');
+		ratingEl.setAttribute('data-kt-rating', 'true');
+		container.appendChild(ratingEl);
+		document.body.appendChild(container);
+	});
+
+	afterEach(() => {
+		document.body.innerHTML = '';
+	});
+
+	describe('initialization', () => {
+		it('initializes on element with data-kt-rating', () => {
+			const instance = new KTRating(ratingEl);
+			expect(instance).toBeInstanceOf(KTRating);
+			expect(instance.getElement()).toBe(ratingEl);
+			expect(ratingEl.querySelector('.kt-rating')).not.toBeNull();
+			instance.dispose();
+		});
+
+		it('reads value and max from data attributes', () => {
+			ratingEl.setAttribute('data-kt-rating-value', '3');
+			ratingEl.setAttribute('data-kt-rating-max', '10');
+			const instance = new KTRating(ratingEl);
+			expect(instance.getOption('value')).toBe(3);
+			expect(instance.getOption('max')).toBe(10);
+			instance.dispose();
+		});
+
+		it('does not double-initialize when constructor called twice on same element', () => {
+			new KTRating(ratingEl);
+			new KTRating(ratingEl);
+			expect(ratingEl.querySelectorAll('.kt-rating').length).toBe(1);
+			const instance = KTRating.getInstance(ratingEl);
+			expect(instance).not.toBeNull();
+			instance!.dispose();
+		});
+	});
+
+	describe('readonly mode', () => {
+		it('renders filled and unfilled symbols for value 3 of 5', () => {
+			ratingEl.setAttribute('data-kt-rating-value', '3');
+			ratingEl.setAttribute('data-kt-rating-readonly', 'true');
+			const instance = new KTRating(ratingEl);
+			const wrapper = ratingEl.querySelector('.kt-rating');
+			expect(wrapper).not.toBeNull();
+			expect(wrapper?.getAttribute('role')).toBe('img');
+			expect(wrapper?.getAttribute('aria-valuenow')).toBe('3');
+			expect(wrapper?.getAttribute('aria-valuemax')).toBe('5');
+			expect(wrapper?.querySelectorAll('span').length).toBe(5);
+			expect(wrapper?.querySelectorAll('input[type="radio"]').length).toBe(0);
+			instance.dispose();
+		});
+
+		it('getValue returns config value in readonly mode', () => {
+			ratingEl.setAttribute('data-kt-rating-value', '4');
+			ratingEl.setAttribute('data-kt-rating-readonly', 'true');
+			const instance = new KTRating(ratingEl);
+			expect(instance.getValue()).toBe(4);
+			instance.dispose();
+		});
+
+		it('getValue returns null when readonly value is 0', () => {
+			ratingEl.setAttribute('data-kt-rating-value', '0');
+			ratingEl.setAttribute('data-kt-rating-readonly', 'true');
+			const instance = new KTRating(ratingEl);
+			expect(instance.getValue()).toBeNull();
+			instance.dispose();
+		});
+	});
+
+	describe('interactive mode', () => {
+		it('renders radio inputs for each value 1..max', () => {
+			const instance = new KTRating(ratingEl);
+			const wrapper = ratingEl.querySelector('.kt-rating');
+			const radios = wrapper?.querySelectorAll('input[type="radio"]') ?? [];
+			expect(radios.length).toBe(5);
+			expect(radios[0].getAttribute('value')).toBe('5');
+			expect(radios[4].getAttribute('value')).toBe('1');
+			instance.dispose();
+		});
+
+		it('getValue returns null when no selection', () => {
+			const instance = new KTRating(ratingEl);
+			expect(instance.getValue()).toBeNull();
+			instance.dispose();
+		});
+
+		it('setValue updates checked radio and getValue', () => {
+			const instance = new KTRating(ratingEl);
+			instance.setValue(3);
+			expect(instance.getValue()).toBe(3);
+			const checked = ratingEl.querySelector<HTMLInputElement>(
+				'input[type="radio"]:checked',
+			);
+			expect(checked?.value).toBe('3');
+			instance.dispose();
+		});
+
+		it('setValue(null) clears selection', () => {
+			const instance = new KTRating(ratingEl);
+			instance.setValue(4);
+			instance.setValue(null);
+			expect(instance.getValue()).toBeNull();
+			expect(ratingEl.querySelector('input[type="radio"]:checked')).toBeNull();
+			instance.dispose();
+		});
+
+		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"]',
+			);
+			expect(radio3).not.toBeNull();
+			radio3!.checked = true;
+			radio3!.dispatchEvent(new Event('change', { bubbles: true }));
+			expect(events.length).toBe(1);
+			expect(events[0].detail?.payload?.value).toBe(3);
+			instance.dispose();
+		});
+	});
+
+	describe('configurable max', () => {
+		it('renders max symbols when max is 10', () => {
+			ratingEl.setAttribute('data-kt-rating-max', '10');
+			ratingEl.setAttribute('data-kt-rating-readonly', 'true');
+			ratingEl.setAttribute('data-kt-rating-value', '7');
+			const instance = new KTRating(ratingEl);
+			const wrapper = ratingEl.querySelector('.kt-rating');
+			expect(wrapper?.querySelectorAll('span').length).toBe(10);
+			expect(wrapper?.getAttribute('aria-valuemax')).toBe('10');
+			instance.dispose();
+		});
+
+		it('interactive mode renders 10 radios when max is 10', () => {
+			ratingEl.setAttribute('data-kt-rating-max', '10');
+			const instance = new KTRating(ratingEl);
+			const radios = ratingEl.querySelectorAll('input[type="radio"]');
+			expect(radios.length).toBe(10);
+			instance.setValue(8);
+			expect(instance.getValue()).toBe(8);
+			instance.dispose();
+		});
+	});
+
+	describe('getInstance and static methods', () => {
+		it('getInstance returns null for element without data-kt-rating', () => {
+			ratingEl.removeAttribute('data-kt-rating');
+			expect(KTRating.getInstance(ratingEl)).toBeNull();
+		});
+
+		it('getInstance returns instance for initialized element', () => {
+			const instance = new KTRating(ratingEl);
+			expect(KTRating.getInstance(ratingEl)).toBe(instance);
+			instance.dispose();
+		});
+
+		it('createInstances initializes all data-kt-rating elements', () => {
+			const el2 = document.createElement('div');
+			el2.setAttribute('data-kt-rating', 'true');
+			container.appendChild(el2);
+			KTRating.createInstances();
+			expect(KTRating.getInstance(ratingEl)).not.toBeNull();
+			expect(KTRating.getInstance(el2)).not.toBeNull();
+			KTRating.getInstance(ratingEl)?.dispose();
+			KTRating.getInstance(el2)?.dispose();
+		});
+
+		it('createInstances skips elements with data-kt-rating-lazy="true"', () => {
+			ratingEl.setAttribute('data-kt-rating-lazy', 'true');
+			KTRating.createInstances();
+			// Lazy elements are not auto-initialized, so no .kt-rating container yet
+			expect(ratingEl.querySelector('.kt-rating')).toBeNull();
+		});
+	});
+
+	describe('dispose', () => {
+		it('removes change listener and allows re-initialization', () => {
+			const instance = new KTRating(ratingEl);
+			instance.dispose();
+			// getInstance creates on demand, so assert re-init works instead
+			const instance2 = new KTRating(ratingEl);
+			expect(instance2).toBeInstanceOf(KTRating);
+			expect(instance2.getValue()).toBeNull();
+			instance2.setValue(2);
+			expect(instance2.getValue()).toBe(2);
+			instance2.dispose();
+		});
+
+		it('dispose is idempotent', () => {
+			const instance = new KTRating(ratingEl);
+			instance.dispose();
+			expect(() => instance.dispose()).not.toThrow();
+		});
+	});
+
+	describe('custom symbol', () => {
+		it('renders heart symbol when data-kt-rating-symbol="heart"', () => {
+			ratingEl.setAttribute('data-kt-rating-symbol', 'heart');
+			ratingEl.setAttribute('data-kt-rating-readonly', 'true');
+			ratingEl.setAttribute('data-kt-rating-value', '2');
+			const instance = new KTRating(ratingEl);
+			const wrapper = ratingEl.querySelector('.kt-rating');
+			expect(wrapper).not.toBeNull();
+			// Heart uses red fill path
+			const path = wrapper?.querySelector('path[fill-rule="evenodd"]');
+			expect(path).not.toBeNull();
+			instance.dispose();
+		});
+	});
+
+	describe('initial value in interactive mode', () => {
+		it('pre-selects radio when value is set via config', () => {
+			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',
+			);
+			expect(checked?.value).toBe('2');
+			instance.dispose();
+		});
+	});
+});

package/src/components/rating/index.ts

@@ -0,0 +1,11 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+export { KTRating } from './rating';
+export type {
+	KTRatingConfigInterface,
+	KTRatingInterface,
+	KTRatingSymbolType,
+} from './types';

package/src/components/rating/rating.css

@@ -0,0 +1,11 @@
+/**
+ * KTUI Rating component
+ * Layout and symbol styling; colors use Tailwind utilities (filled/unfilled, dark mode).
+ */
+.kt-rating {
+	display: flex;
+	align-items: center;
+}
+.kt-rating-label {
+	pointer-events: auto;
+}