@keenthemes/ktui 1.2.5 → 1.2.7

package/skills/ktui-select/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: ktui-select
+description: >
+  KtUI Select (KTSelect) — rich searchable multi-select dropdown replacing native select.
+  Tags, combobox, remote data, pagination, select-all, events, and programmatic API.
+  Use this skill when building, debugging, or customizing Select components.
+---
+
+# KTSelect — AI Agent Reference
+
+Full reference for the Select component in [KtUI](https://ktui.io).
+Package: `@keenthemes/ktui`. Class: `KTSelect`. Root attribute: `data-kt-select`.
+
+> **Always prefer [ktui.io/docs/select](https://ktui.io/docs/select) docs and examples over guessing markup or options.**
+
+---
+
+## 1. Basic Usage
+
+```html
+<select data-kt-select="true" data-kt-select-enable-search="true">
+  <option value="">Select...</option>
+  <option value="1">Option 1</option>
+  <option value="2">Option 2</option>
+</select>
+```
+
+```ts
+import { KTSelect } from '@keenthemes/ktui';
+
+const select = KTSelect.getInstance(el);
+```
+
+---
+
+## 2. Key Features
+
+| Feature | Attribute | Description |
+|---------|-----------|-------------|
+| Search | `data-kt-select-enable-search="true"` | Adds search input in dropdown |
+| Multi-select | `multiple` attribute on `<select>` | Allow multiple selections |
+| Tags mode | `data-kt-select-tags="true"` | Shows selected items as removable tags |
+| Combobox | `data-kt-select-combobox="true"` | Allows free text input |
+| Remote data | `data-kt-select-remote="true"` | Load options from API |
+| Remote URL | `data-kt-select-remote-url="..."` | API endpoint for remote data |
+| Pagination | `data-kt-select-pagination="true"` | Adds "Load More" button |
+| Placeholder | `data-kt-select-placeholder="Choose..."` | Placeholder text |
+| Select all | `data-kt-select-select-all="true"` | Adds "Select All" button (multi-mode) |
+| Close on Enter | `data-kt-select-close-on-enter="true"` | Close dropdown when Enter pressed |
+| Close on other open | `data-kt-select-close-on-other-open="true"` | Close when another select opens |
+| Search autofocus | `data-kt-select-search-autofocus="true"` | Focus search input on open |
+| Dispatch global events | `data-kt-select-dispatch-global-events="true"` | Dispatch events on document |
+
+---
+
+## 3. Global Config
+
+Set defaults for all future instances:
+
+```ts
+KTSelect.config({
+  enableSearch: true,
+  searchPlaceholder: 'Type to search...',
+  dropdownZindex: 9999,
+  height: 300,
+  closeOnEnter: true,
+  closeOnOtherOpen: true,
+  searchAutofocus: true,
+  dispatchGlobalEvents: true,
+});
+```
+
+---
+
+## 4. Programmatic API
+
+```ts
+const select = KTSelect.getInstance(el);
+
+// Dropdown control
+select.openDropdown();
+select.closeDropdown();
+select.toggleSelection(value);
+
+// Selection
+select.getSelectedOptions();      // array of selected option objects
+select.setSelectedOptions([opt]); // set selection programmatically
+select.clearSelection();          // clear all
+
+// Lifecycle
+select.dispose();
+```
+
+### Instance management
+
+| Static method | Returns |
+|--------------|---------|
+| `KTSelect.getInstance(el)` | Existing instance or `null` |
+| `KTSelect.getOrCreateInstance(el, config?)` | Existing or new instance |
+| `KTSelect.init()` | Scans DOM, creates instances |
+| `KTSelect.config(opts)` | Set global defaults |
+
+---
+
+## 5. Events
+
+Events fire through dual channel:
+1. **Internal callbacks** (`.on()`) — bare name
+2. **DOM CustomEvents** — dispatched on both element and document
+
+### Confirmed events (from source)
+
+| Event | When |
+|-------|------|
+| `show` | Dropdown opening |
+| `close` | Dropdown closing |
+| `change` | Selection changed |
+| `enabled` | Component enabled |
+| `disabled` | Component disabled |
+| `updated` | Options updated |
+| `updateError` | Options update failed |
+| `reloadStart` | Remote reload started |
+| `reloadComplete` | Remote reload finished |
+| `reloadError` | Remote reload failed |
+| `refreshed` | Options refreshed |
+| `refreshError` | Options refresh failed |
+
+### Namespaced events on document
+
+```ts
+document.addEventListener('kt-select:change', (e) => {
+  console.log(e.detail.instance.getSelectedOptions());
+});
+
+document.addEventListener('kt-select:show', (e) => {
+  console.log('Select opened', e.detail.element);
+});
+```
+
+### Element-level events
+
+```ts
+el.addEventListener('change', (e) => {
+  console.log(e.detail.instance.getSelectedOptions());
+});
+```
+
+### Event detail shape
+
+```ts
+{
+  instance: KTSelect,   // the select instance
+  element: HTMLElement,  // the root element
+  payload: { ... }       // event-specific data
+}
+```
+
+---
+
+## 6. Remote Data
+
+```html
+<select data-kt-select="true"
+        data-kt-select-remote="true"
+        data-kt-select-remote-url="https://api.example.com/options"
+        data-kt-select-pagination="true">
+</select>
+```
+
+The remote provider fetches options from the URL. Use `pagination: true` for paginated APIs.
+
+---
+
+## 7. Tags Mode
+
+```html
+<select data-kt-select="true"
+        data-kt-select-tags="true"
+        multiple>
+  <option value="1">Tag 1</option>
+  <option value="2">Tag 2</option>
+  <option value="3">Tag 3</option>
+</select>
+```
+
+Selected items appear as removable tag chips. Works with search and remote data.
+
+---
+
+## 8. Combobox Mode
+
+```html
+<input type="text"
+       data-kt-select="true"
+       data-kt-select-combobox="true"
+       data-kt-select-remote="true"
+       data-kt-select-remote-url="https://api.example.com/search" />
+```
+
+Allows free text input alongside selecting from dropdown options.
+
+---
+
+## 9. Select All
+
+```html
+<select data-kt-select="true"
+        data-kt-select-select-all="true"
+        data-kt-select-enable-search="true"
+        multiple>
+  <option value="1">Option 1</option>
+  <option value="2">Option 2</option>
+  <option value="3">Option 3</option>
+</select>
+```
+
+Adds a "Select All" button at the top of the dropdown in multi-select mode.
+
+---
+
+## 10. Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Select focused option, close dropdown (if `closeOnEnter` enabled) |
+| `ArrowDown` | Focus next option |
+| `ArrowUp` | Focus previous option |
+| `Escape` | Close dropdown |
+| `Backspace` | Remove last tag (tags mode) |
+
+---
+
+## 11. Architecture
+
+Source: `src/components/select/`
+
+| File | Purpose |
+|------|---------|
+| `select.ts` | Main class — `openDropdown()`, `closeDropdown()`, `clearSelection()`, `dispose()` |
+| `dropdown.ts` | Dropdown positioning and visibility |
+| `search.ts` | Search input filtering |
+| `tags.ts` | Tags mode rendering and removal |
+| `combobox.ts` | Free text input mode |
+| `remote.ts` | Remote data provider |
+| `option.ts` | Option element management |
+| `templates.ts` | HTML template generation |
+| `config.ts` | Default config constants |
+| `utils.ts` | Shared utilities |
+| `types.ts` | Type definitions |
+| `index.ts` | Barrel exports |
+
+---
+
+## 12. Common Pitfalls
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Select not searchable | Missing `enable-search` attribute | Add `data-kt-select-enable-search="true"` |
+| No tags shown | Missing `tags` attribute | Add `data-kt-select-tags="true"` |
+| Remote not loading | Missing remote attributes | Add both `data-kt-select-remote="true"` and `data-kt-select-remote-url="..."` |
+| Dropdown wrong position | Container overflow hidden | Use `data-kt-dropdown-container="body"` to portal |
+| Select All not appearing | Not in multi-mode | Add `multiple` attribute to `<select>` |
+| Events not firing on document | `dispatchGlobalEvents` disabled | Enable via config or attribute |
+| `shown`/`hide`/`hidden` events not working | Wrong event names | Use `show`, `close`, `change` (actual events from source) |
+
+---
+
+## 13. Documentation
+
+- **Select docs:** [ktui.io/docs/select](https://ktui.io/docs/select)
+- **Changelog:** [ktui.io/docs/changelog](https://ktui.io/docs/changelog)

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

@@ -0,0 +1,347 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import KTComponent from '../component';
+import KTData from '../../helpers/data';
+
+class TestComponent extends KTComponent {
+	protected _name = 'test';
+	protected _defaultConfig = {};
+	protected _config = {};
+
+	constructor(element: HTMLElement | null) {
+		super();
+		this._init(element);
+	}
+
+	public testFireEvent(eventType: string, payload?: object | null) {
+		return this._fireEvent(eventType, payload);
+	}
+
+	public testDispatchEvent(eventType: string, payload?: object | null) {
+		this._dispatchEvent(eventType, payload);
+	}
+
+	public testGetOption(name: string) {
+		return this._getOption(name);
+	}
+
+	public testBuildConfig(config: object = {}) {
+		this._buildConfig(config);
+	}
+
+	public testMergeConfig(config: object) {
+		this._mergeConfig(config);
+	}
+
+	public testGetGlobalConfig() {
+		return this._getGlobalConfig();
+	}
+
+	public testShouldSkipInit(element: HTMLElement) {
+		return this._shouldSkipInit(element);
+	}
+}
+
+describe('KTComponent', () => {
+	beforeEach(() => {
+		document.body.innerHTML = '';
+	});
+
+	describe('constructor / _init', () => {
+		it('stores element and generates namespace', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			expect(comp.getElement()).toBe(el);
+		});
+
+		it('sets data-kt-test-initialized attribute on element', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			new TestComponent(el);
+			expect(el.getAttribute('data-kt-test-initialized')).toBe('true');
+		});
+
+		it('stores instance in KTData', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			expect(KTData.get(el, 'test')).toBe(comp);
+		});
+
+		it('handles null element gracefully', () => {
+			const comp = new TestComponent(null);
+			expect(comp.getElement()).toBeNull();
+		});
+	});
+
+	describe('dispose', () => {
+		it('removes initialized attribute from element', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			comp.dispose();
+			expect(el.hasAttribute('data-kt-test-initialized')).toBe(false);
+		});
+
+		it('removes instance from KTData', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			comp.dispose();
+			expect(KTData.get(el, 'test')).toBeNull();
+		});
+
+		it('does nothing when element is null', () => {
+			const comp = new TestComponent(null);
+			expect(() => comp.dispose()).not.toThrow();
+		});
+	});
+
+	describe('on / _fireEvent', () => {
+		it('registers and fires event handler', async () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const handler = vi.fn();
+
+			comp.on('myEvent', handler);
+			await comp.testFireEvent('myEvent', { data: 123 });
+			expect(handler).toHaveBeenCalledWith({ data: 123 });
+		});
+
+		it('returns unique eventId from on()', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+
+			const id1 = comp.on('evt', () => {});
+			const id2 = comp.on('evt', () => {});
+			expect(id1).not.toBe(id2);
+		});
+
+		it('fires multiple handlers for the same event', async () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const h1 = vi.fn();
+			const h2 = vi.fn();
+
+			comp.on('evt', h1);
+			comp.on('evt', h2);
+			await comp.testFireEvent('evt');
+			expect(h1).toHaveBeenCalled();
+			expect(h2).toHaveBeenCalled();
+		});
+
+		it('does not throw when no handlers registered', async () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			await expect(comp.testFireEvent('nonexistent')).resolves.not.toThrow();
+		});
+
+		it('calls handlers with null when no payload', async () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const handler = vi.fn();
+
+			comp.on('evt', handler);
+			await comp.testFireEvent('evt');
+			expect(handler).toHaveBeenCalledWith(null);
+		});
+	});
+
+	describe('off', () => {
+		it('removes a specific event handler', async () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const handler = vi.fn();
+
+			const id = comp.on('evt', handler);
+			comp.off('evt', id);
+			await comp.testFireEvent('evt');
+			expect(handler).not.toHaveBeenCalled();
+		});
+
+		it('does not throw when removing non-existent handler', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			expect(() => comp.off('evt', 'nonexistent-id')).not.toThrow();
+		});
+	});
+
+	describe('_dispatchEvent', () => {
+		it('dispatches CustomEvent on element', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const listener = vi.fn();
+			el.addEventListener('kt.test.myEvent', listener);
+
+			comp.testDispatchEvent('kt.test.myEvent', { foo: 'bar' });
+			expect(listener).toHaveBeenCalled();
+			const event = listener.mock.calls[0][0] as CustomEvent;
+			expect(event.detail).toEqual({ payload: { foo: 'bar' } });
+			expect(event.bubbles).toBe(true);
+		});
+
+		it('does not throw when element is null', () => {
+			const comp = new TestComponent(null);
+			expect(() =>
+				comp.testDispatchEvent('kt.test.evt'),
+			).not.toThrow();
+		});
+
+		it('dispatches with null payload when not provided', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			const listener = vi.fn();
+			el.addEventListener('kt.test.evt', listener);
+
+			comp.testDispatchEvent('kt.test.evt');
+			expect(listener).toHaveBeenCalled();
+			const event = listener.mock.calls[0][0] as CustomEvent;
+			expect(event.detail).toEqual({ payload: null });
+		});
+	});
+
+	describe('getElement', () => {
+		it('returns element', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			expect(comp.getElement()).toBe(el);
+		});
+
+		it('returns null when not initialized', () => {
+			const comp = new TestComponent(null);
+			expect(comp.getElement()).toBeNull();
+		});
+	});
+
+	describe('_shouldSkipInit', () => {
+		it('returns false when element has no existing instance', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(document.createElement('span'));
+			expect(comp.testShouldSkipInit(el)).toBe(false);
+		});
+
+		it('returns true when element has existing instance and is connected', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			new TestComponent(el); // first init
+			const comp2 = new TestComponent(document.createElement('span'));
+			expect(comp2.testShouldSkipInit(el)).toBe(true);
+		});
+
+		it('returns false when element has existing instance but is disconnected', () => {
+			const el = document.createElement('div');
+			// Don't append to document — element is disconnected
+			const comp1 = new TestComponent(el);
+			const comp2 = new TestComponent(document.createElement('span'));
+			// The old instance should be disposed, so this returns false (allowing reinit)
+			expect(comp2.testShouldSkipInit(el)).toBe(false);
+		});
+	});
+
+	describe('_getOption', () => {
+		it('returns config value', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._config = { myOption: 'value' };
+			expect(comp.testGetOption('myOption')).toBe('value');
+		});
+
+		it('returns undefined for missing option', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._config = {};
+			expect(comp.testGetOption('missing')).toBeUndefined();
+		});
+	});
+
+	describe('_buildConfig', () => {
+		it('merges default config, global config, data attributes, and passed config', () => {
+			const el = document.createElement('div');
+			el.setAttribute('data-kt-test-foo', 'bar');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._defaultConfig = { defaultOpt: 1 };
+
+			window.KTGlobalComponentsConfig = {
+				test: { globalOpt: 2 },
+			};
+
+			comp.testBuildConfig({ extraOpt: 3 });
+			const config = (comp as any)._config;
+			expect(config.defaultOpt).toBe(1);
+			expect(config.globalOpt).toBe(2);
+			expect(config.foo).toBe('bar');
+			expect(config.extraOpt).toBe(3);
+
+			delete (window as any).KTGlobalComponentsConfig;
+		});
+
+		it('does nothing when element is null', () => {
+			const comp = new TestComponent(null);
+			expect(() => comp.testBuildConfig()).not.toThrow();
+		});
+	});
+
+	describe('_mergeConfig', () => {
+		it('merges config into existing _config', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._config = { a: 1 };
+			comp.testMergeConfig({ b: 2 });
+			expect((comp as any)._config).toEqual({ a: 1, b: 2 });
+		});
+
+		it('does nothing for empty config', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._config = { a: 1 };
+			comp.testMergeConfig({});
+			expect((comp as any)._config).toEqual({ a: 1 });
+		});
+
+		it('does nothing for null config', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			(comp as any)._config = { a: 1 };
+			comp.testMergeConfig(null as unknown as object);
+			expect((comp as any)._config).toEqual({ a: 1 });
+		});
+	});
+
+	describe('_getGlobalConfig', () => {
+		it('returns global config for component name', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			window.KTGlobalComponentsConfig = {
+				test: { global: true },
+			};
+			expect(comp.testGetGlobalConfig()).toEqual({ global: true });
+			delete (window as any).KTGlobalComponentsConfig;
+		});
+
+		it('returns empty object when no global config', () => {
+			const el = document.createElement('div');
+			document.body.appendChild(el);
+			const comp = new TestComponent(el);
+			delete (window as any).KTGlobalComponentsConfig;
+			expect(comp.testGetGlobalConfig()).toEqual({});
+		});
+	});
+});

package/src/components/collapse/collapse.css

@@ -4,11 +4,11 @@
  */
 
 @custom-variant kt-collapse-active {
-	[data-kt-collapse-initialized].active & {
+	&[data-kt-collapse-initialized].active {
 		@slot;
 	}
 
-	[data-kt-collapse-initialized].active {
+	[data-kt-collapse-initialized].active & {
 		@slot;
 	}
 }