@keenthemes/ktui 1.1.6 → 1.2.1

package/src/components/rating/rating.ts

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

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

@@ -0,0 +1,321 @@
+/**
+ * Tests for KTRepeater component
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { KTRepeater } from '../repeater';
+
+function createFixture(options?: {
+	withInitialChild?: boolean;
+	limit?: number;
+	hiddenTemplate?: boolean;
+	withDeleteInTarget?: boolean;
+}) {
+	document.body.innerHTML = '';
+	const container = document.createElement('div');
+	container.id = 'repeater-test-container';
+
+	const wrapper = document.createElement('div');
+	wrapper.id = 'repeater-wrapper';
+	wrapper.className = 'space-y-3';
+	container.appendChild(wrapper);
+
+	const target = document.createElement('div');
+	target.id = 'repeater-target';
+	const input = document.createElement('input');
+	input.type = 'text';
+	input.placeholder = 'Enter Name';
+	target.appendChild(input);
+	if (options?.withDeleteInTarget) {
+		const removeBtn = document.createElement('span');
+		removeBtn.setAttribute('data-kt-repeater-delete', '');
+		removeBtn.className = 'remove-btn';
+		target.appendChild(removeBtn);
+	}
+
+	if (options?.hiddenTemplate) {
+		const hidden = document.createElement('div');
+		hidden.id = 'repeater-template-container';
+		hidden.className = 'hidden';
+		hidden.style.display = 'none';
+		hidden.appendChild(target);
+		container.appendChild(hidden);
+	} else if (options?.withInitialChild !== false) {
+		wrapper.appendChild(target);
+	}
+
+	const trigger = document.createElement('button');
+	trigger.type = 'button';
+	trigger.setAttribute('data-kt-repeater', '');
+	trigger.setAttribute('data-kt-repeater-target', '#repeater-target');
+	trigger.setAttribute('data-kt-repeater-wrapper', '#repeater-wrapper');
+	if (options?.limit != null) {
+		trigger.setAttribute('data-kt-repeater-limit', String(options.limit));
+	}
+	trigger.textContent = 'Add';
+	container.appendChild(trigger);
+
+	document.body.appendChild(container);
+	return { container, wrapper, target, trigger };
+}
+
+describe('KTRepeater', () => {
+	afterEach(() => {
+		document.body.innerHTML = '';
+	});
+
+	describe('initialization', () => {
+		it('initializes on trigger element with data-kt-repeater and valid target/wrapper', () => {
+			const { trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			expect(instance).toBeInstanceOf(KTRepeater);
+			expect(instance.getElement()).toBe(trigger);
+			instance.dispose();
+		});
+
+		it('reads target, wrapper, limit from data attributes', () => {
+			const { trigger } = createFixture({ limit: 5 });
+			const instance = new KTRepeater(trigger);
+			expect(instance.getOption('target')).toBe('#repeater-target');
+			expect(instance.getOption('wrapper')).toBe('#repeater-wrapper');
+			expect(Number(instance.getOption('limit'))).toBe(5);
+			instance.dispose();
+		});
+
+		it('does not double-initialize when constructor called twice on same trigger', () => {
+			const { trigger, wrapper } = createFixture();
+			new KTRepeater(trigger);
+			new KTRepeater(trigger);
+			expect(KTRepeater.getInstance(trigger)).not.toBeNull();
+			KTRepeater.getInstance(trigger)!.add();
+			expect(wrapper.children.length).toBe(2);
+			KTRepeater.getInstance(trigger)!.dispose();
+		});
+
+		it('accepts config object when wrapper has no id (config overrides)', () => {
+			const { trigger, wrapper } = createFixture();
+			wrapper.id = 'custom-wrapper';
+			trigger.removeAttribute('data-kt-repeater-wrapper');
+			const instance = new KTRepeater(trigger, {
+				target: '#repeater-target',
+				wrapper: '#custom-wrapper',
+				limit: 0,
+			});
+			expect(instance).toBeInstanceOf(KTRepeater);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			instance.dispose();
+		});
+	});
+
+	describe('add behavior', () => {
+		it('clones target into wrapper when trigger is clicked', () => {
+			const { wrapper, trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			expect(wrapper.children.length).toBe(1);
+			trigger.click();
+			expect(wrapper.children.length).toBe(2);
+			trigger.click();
+			expect(wrapper.children.length).toBe(3);
+			instance.dispose();
+		});
+
+		it('add() method has the same effect as clicking the trigger', () => {
+			const { wrapper, trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			expect(wrapper.children.length).toBe(1);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			instance.add();
+			expect(wrapper.children.length).toBe(3);
+			instance.dispose();
+		});
+
+		it('fires add event with cloned element in payload', () => {
+			const { trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			const addedElements: HTMLElement[] = [];
+			instance.on('add', (payload: { element: HTMLElement }) => {
+				addedElements.push(payload.element);
+			});
+			instance.add();
+			instance.add();
+			expect(addedElements.length).toBe(2);
+			expect(addedElements[0]).toBeInstanceOf(HTMLElement);
+			expect(addedElements[0].querySelector('input')).not.toBeNull();
+			instance.dispose();
+		});
+
+		it('dispatches DOM add event with detail.payload.element', () => {
+			const { trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			const events: CustomEvent[] = [];
+			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);
+			instance.dispose();
+		});
+	});
+
+	describe('limit', () => {
+		it('does not add more clones when at limit', () => {
+			const { wrapper, trigger } = createFixture({ limit: 2 });
+			const instance = new KTRepeater(trigger);
+			expect(wrapper.children.length).toBe(1);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			trigger.click();
+			expect(wrapper.children.length).toBe(2);
+			instance.dispose();
+		});
+
+		it('disables trigger when at limit', () => {
+			const { wrapper, trigger } = createFixture({ limit: 2 });
+			const instance = new KTRepeater(trigger);
+			expect(trigger.hasAttribute('disabled')).toBe(false);
+			instance.add();
+			expect(trigger.hasAttribute('disabled')).toBe(true);
+			instance.dispose();
+		});
+
+		it('re-enables trigger when a clone is removed (delete) and count drops below limit', () => {
+			const { wrapper, trigger } = createFixture({
+				limit: 2,
+				withDeleteInTarget: true,
+			});
+			const instance = new KTRepeater(trigger);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			expect(trigger.hasAttribute('disabled')).toBe(true);
+			const secondClone = wrapper.children[1];
+			const deleteBtn = secondClone.querySelector('[data-kt-repeater-delete]');
+			expect(deleteBtn).not.toBeNull();
+			(deleteBtn as HTMLElement).click();
+			expect(wrapper.children.length).toBe(1);
+			expect(trigger.hasAttribute('disabled')).toBe(false);
+			instance.dispose();
+		});
+
+		it('allows unlimited clones when limit is 0 or omitted', () => {
+			const { wrapper, trigger } = createFixture();
+			trigger.removeAttribute('data-kt-repeater-limit');
+			const instance = new KTRepeater(trigger);
+			for (let i = 0; i < 5; i++) instance.add();
+			expect(wrapper.children.length).toBe(6);
+			instance.dispose();
+		});
+	});
+
+	describe('delete', () => {
+		it('removes clone when clicking element with data-kt-repeater-delete', () => {
+			const { wrapper, trigger } = createFixture({ withDeleteInTarget: true });
+			const instance = new KTRepeater(trigger);
+			instance.add();
+			expect(wrapper.children.length).toBe(2);
+			const firstClone = wrapper.children[1];
+			const deleteBtn = firstClone.querySelector(
+				'[data-kt-repeater-delete]',
+			) as HTMLElement;
+			deleteBtn.click();
+			expect(wrapper.children.length).toBe(1);
+			instance.dispose();
+		});
+
+		it('does not remove the last row (keeps at least one for template)', () => {
+			const { wrapper, trigger } = createFixture({ withDeleteInTarget: true });
+			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;
+			deleteBtn.click();
+			expect(wrapper.children.length).toBe(1);
+			instance.dispose();
+		});
+	});
+
+	describe('predefined (hidden) template', () => {
+		it('clones from hidden template and appends to wrapper', () => {
+			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();
+			instance.dispose();
+		});
+	});
+
+	describe('getInstance and static methods', () => {
+		it('getInstance returns null for element without data-kt-repeater', () => {
+			const { trigger } = createFixture();
+			trigger.removeAttribute('data-kt-repeater');
+			expect(KTRepeater.getInstance(trigger)).toBeNull();
+		});
+
+		it('getInstance returns instance for initialized trigger', () => {
+			const { trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			expect(KTRepeater.getInstance(trigger)).toBe(instance);
+			instance.dispose();
+		});
+
+		it('getOrCreateInstance returns existing instance or creates new one', () => {
+			const { trigger } = createFixture();
+			const a = KTRepeater.getOrCreateInstance(trigger);
+			const b = KTRepeater.getOrCreateInstance(trigger);
+			expect(a).toBe(b);
+			a.dispose();
+		});
+
+		it('createInstances initializes all data-kt-repeater elements', () => {
+			const { container, wrapper, trigger } = createFixture();
+			const trigger2 = document.createElement('button');
+			trigger2.setAttribute('data-kt-repeater', '');
+			trigger2.setAttribute('data-kt-repeater-target', '#repeater-target');
+			trigger2.setAttribute('data-kt-repeater-wrapper', '#repeater-wrapper');
+			container.appendChild(trigger2);
+			KTRepeater.createInstances();
+			expect(KTRepeater.getInstance(trigger)).not.toBeNull();
+			expect(KTRepeater.getInstance(trigger2)).not.toBeNull();
+			KTRepeater.getInstance(trigger)!.dispose();
+			KTRepeater.getInstance(trigger2)!.dispose();
+		});
+
+		it('init calls createInstances', () => {
+			const { trigger } = createFixture();
+			KTRepeater.init();
+			expect(KTRepeater.getInstance(trigger)).not.toBeNull();
+			KTRepeater.getInstance(trigger)!.dispose();
+		});
+	});
+
+	describe('dispose', () => {
+		it('removes listeners and allows re-initialization', () => {
+			const { wrapper, trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			instance.dispose();
+			const instance2 = new KTRepeater(trigger);
+			instance2.add();
+			expect(wrapper.children.length).toBe(2);
+			instance2.dispose();
+		});
+
+		it('dispose is idempotent', () => {
+			const { trigger } = createFixture();
+			const instance = new KTRepeater(trigger);
+			instance.dispose();
+			expect(() => instance.dispose()).not.toThrow();
+		});
+	});
+});

package/src/components/repeater/index.ts

@@ -0,0 +1,7 @@
+/**
+ * KTUI - Free & Open-Source Tailwind UI Components by Keenthemes
+ * Copyright 2025 by Keenthemes Inc
+ */
+
+export { KTRepeater } from './repeater';
+export type { KTRepeaterConfigInterface, KTRepeaterInterface } from './types';