@keenthemes/ktui 1.1.5 → 1.2.0

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

@@ -0,0 +1,234 @@
+/**
+ * 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;
+}

package/src/components/rating/rating.ts

@@ -0,0 +1,234 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+import KTData from '../../helpers/data';
+import KTDom from '../../helpers/dom';
+import KTComponent from '../component';
+import { KTRatingConfigInterface, KTRatingInterface } from './types';
+
+declare global {
+	interface Window {
+		KTRating: typeof KTRating;
+	}
+}
+
+const STAR_SVG =
+	'<path d="M3.612 15.443c-.386.198-.824-.149-.746-.592l.83-4.73L.173 6.765c-.329-.314-.158-.888.283-.95l4.898-.696L7.538.792c.197-.39.73-.39.927 0l2.184 4.327 4.898.696c.441.062.612.636.282.95l-3.522 3.356.83 4.73c.078.443-.36.79-.746.592L8 13.187l-4.389 2.256z"/>';
+const HEART_SVG =
+	'<path fill-rule="evenodd" d="M8 1.314C12.438-3.248 23.534 4.735 8 15-7.534 4.736 3.562-3.248 8 1.314z"/>';
+
+export class KTRating extends KTComponent implements KTRatingInterface {
+	protected override _name: string = 'rating';
+	protected override _defaultConfig: KTRatingConfigInterface = {
+		value: 0,
+		max: 5,
+		readonly: false,
+		name: 'rating',
+		symbol: 'star',
+		lazy: false,
+	};
+	protected override _config: KTRatingConfigInterface = this._defaultConfig;
+	protected _container: HTMLElement | null = null;
+	protected _changeListener: ((e: Event) => void) | null = null;
+
+	constructor(
+		element: HTMLElement,
+		config: KTRatingConfigInterface | null = null,
+	) {
+		super();
+
+		if (KTData.has(element as HTMLElement, this._name)) return;
+
+		this._init(element);
+		this._buildConfig(config);
+
+		this._render();
+		if (!this._config.readonly) {
+			this._handlers();
+		}
+	}
+
+	protected _getMax(): number {
+		const max = Number(this._getOption('max'));
+		return Number.isFinite(max) && max >= 1 ? Math.floor(max) : 5;
+	}
+
+	protected _getValue(): number {
+		const v = Number(this._getOption('value'));
+		const max = this._getMax();
+		return Number.isFinite(v) && v >= 0 && v <= max ? Math.floor(v) : 0;
+	}
+
+	protected _render(): void {
+		if (!this._element) return;
+		const max = this._getMax();
+		const value = this._getValue();
+		const readonly = this._config.readonly === true;
+		const symbol = (this._config.symbol as string) || 'star';
+		const name = (this._config.name as string) || 'rating';
+
+		const isStar = symbol !== 'heart';
+		const filledClass = isStar
+			? 'text-yellow-400 dark:text-yellow-600'
+			: 'text-red-500 dark:text-red-500';
+		const unfilledClass =
+			'text-muted-foreground/50 dark:text-muted-foreground/50';
+		const path = isStar ? STAR_SVG : HEART_SVG;
+		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.setAttribute('role', readonly ? 'img' : 'group');
+		container.setAttribute('aria-label', `Rating: ${value} of ${max}`);
+		if (readonly) {
+			container.setAttribute('aria-valuenow', String(value));
+			container.setAttribute('aria-valuemin', '0');
+			container.setAttribute('aria-valuemax', String(max));
+		}
+
+		if (readonly) {
+			for (let i = max; i >= 1; i--) {
+				const filled = i <= value;
+				const span = document.createElement('span');
+				span.className = filled ? filledClass : unfilledClass;
+				span.innerHTML = svg;
+				container.appendChild(span);
+			}
+		} else {
+			container.setAttribute('aria-valuenow', String(value));
+			container.setAttribute('aria-valuemin', '1');
+			container.setAttribute('aria-valuemax', String(max));
+			for (let i = max; i >= 1; i--) {
+				const id = `kt-rating-${this._uid}-${i}`;
+				const radio = document.createElement('input');
+				radio.type = 'radio';
+				radio.name = name;
+				radio.value = String(i);
+				radio.id = id;
+				radio.className =
+					'peer -ms-5 size-5 bg-transparent border-0 text-transparent cursor-pointer appearance-none checked:bg-none focus:bg-none focus:ring-0 focus:ring-offset-0';
+				radio.setAttribute('aria-label', `Rate ${i} of ${max}`);
+				if (i === value) radio.checked = true;
+
+				const label = document.createElement('label');
+				label.htmlFor = id;
+				label.setAttribute('data-kt-rating-value', String(i));
+				label.className = `cursor-pointer kt-rating-label ${i <= value ? filledClass : unfilledClass}`;
+				label.innerHTML = svg;
+
+				container.appendChild(radio);
+				container.appendChild(label);
+			}
+			this._updateInteractiveDisplay();
+		}
+
+		this._element.innerHTML = '';
+		this._element.appendChild(container);
+		this._container = container;
+	}
+
+	protected _updateInteractiveDisplay(): void {
+		if (!this._container || this._config.readonly) return;
+		const val = this.getValue();
+		const max = this._getMax();
+		const isStar = (this._config.symbol as string) !== 'heart';
+		const filledClass = isStar
+			? 'text-yellow-400 dark:text-yellow-600'
+			: 'text-red-500 dark:text-red-500';
+		const unfilledClass =
+			'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.setAttribute('aria-label', `Rating: ${val ?? 0} of ${max}`);
+	}
+
+	protected _handlers(): void {
+		if (!this._container) return;
+		this._changeListener = () => {
+			this._updateInteractiveDisplay();
+			const val = this.getValue();
+			this._fireEvent('change', { value: val });
+			this._dispatchEvent('kt.rating.change', { value: val });
+		};
+		this._container.addEventListener('change', this._changeListener);
+	}
+
+	public getValue(): number | null {
+		if (!this._element) return null;
+		if (this._config.readonly) {
+			const v = this._getValue();
+			return v > 0 ? v : null;
+		}
+		const radio = this._container?.querySelector<HTMLInputElement>(
+			'input[type="radio"]:checked',
+		);
+		if (!radio) return null;
+		const n = parseInt(radio.value, 10);
+		return Number.isFinite(n) ? n : null;
+	}
+
+	public setValue(value: number | null): void {
+		if (!this._container) return;
+		const max = this._getMax();
+		if (this._config.readonly) return;
+		if (value !== null && value >= 1 && value <= max) {
+			const radio = this._container.querySelector<HTMLInputElement>(
+				`input[type="radio"][value="${value}"]`,
+			);
+			if (radio) {
+				radio.checked = true;
+				this._updateInteractiveDisplay();
+			}
+		} else {
+			this._container.querySelectorAll<HTMLInputElement>('input[type="radio"]').forEach((r) => {
+				r.checked = false;
+			});
+			this._updateInteractiveDisplay();
+		}
+	}
+
+	public override dispose(): void {
+		if (this._container && this._changeListener) {
+			this._container.removeEventListener('change', this._changeListener);
+			this._changeListener = null;
+		}
+		this._container = null;
+		super.dispose();
+	}
+
+	public static getInstance(element: HTMLElement): KTRating | null {
+		if (!element) return null;
+		if (KTData.has(element, 'rating')) {
+			return KTData.get(element, 'rating') as KTRating;
+		}
+		if (element.getAttribute('data-kt-rating') !== null) {
+			return new KTRating(element);
+		}
+		return null;
+	}
+
+	public static createInstances(): void {
+		const elements = document.querySelectorAll<HTMLElement>('[data-kt-rating]');
+		elements.forEach((el) => {
+			if (el.getAttribute('data-kt-rating-lazy') === 'true') return;
+			new KTRating(el);
+		});
+	}
+
+	public static init(): void {
+		KTRating.createInstances();
+	}
+}
+
+if (typeof window !== 'undefined') {
+	window.KTRating = KTRating;
+}

package/src/components/rating/types.ts

@@ -0,0 +1,27 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+export type KTRatingSymbolType = 'star' | 'heart';
+
+export interface KTRatingConfigInterface {
+	/** Current rating value (1 to max). Omit or 0 for no selection. */
+	value?: number;
+	/** Maximum rating (default 5). */
+	max?: number;
+	/** If true, only display the rating; no user input. */
+	readonly?: boolean;
+	/** Form field name for interactive mode (for form submission). */
+	name?: string;
+	/** Symbol to display: 'star' (default) or 'heart'. */
+	symbol?: KTRatingSymbolType;
+	/** If true, do not auto-initialize; init() must be called programmatically. */
+	lazy?: boolean;
+}
+
+export interface KTRatingInterface {
+	getValue(): number | null;
+	setValue(value: number | null): void;
+	dispose(): void;
+}