kempo-ui 0.0.81 → 0.0.83

package/.github/skills/new-component/SKILL.md

@@ -13,12 +13,13 @@ Use this skill any time you are asked to create a new component or add a new cus
 
 ## Overview
 
-Creating a component involves four steps:
+Creating a component involves five steps:
 
 1. **Choose the base component** — pick the right rendering strategy
 2. **Write the source file** in `src/components/`
 3. **Register the custom element** at the bottom of the source file
 4. **Add documentation** in `docs/components/`
+5. **Write and run unit tests** in `tests/components/`
 
 ---
 
@@ -193,6 +194,72 @@ Key requirements:
 
 ---
 
+## Step 5: Write and Run Unit Tests
+
+Create `tests/components/MyComponent.browser-test.js`. Use an existing test file (e.g. `tests/components/Toggle.browser-test.js`) as a reference.
+
+Key conventions:
+- Import the component class at the top.
+- Define an async `createMyComponent()` helper that builds the DOM, appends it to `document.body`, awaits `el.updateComplete`, and returns `{ container, el }`.
+- Define a `cleanup(container)` helper that removes the container from the DOM.
+- Export a default plain object where each key is a test description and each value is an `async ({pass, fail}) => {}` function.
+- Always call `cleanup(container)` before every `pass()` or `fail()` call.
+- Use multi-line comments to group related tests (e.g. `/* Element Creation */`, `/* Properties */`).
+
+Tests to include at minimum:
+- Element is created and is an instance of the component class
+- Element has a shadow root
+- Default property values are correct
+- Attribute reflection works (if applicable)
+- Public methods behave correctly
+- Events are dispatched correctly (if applicable)
+
+Example skeleton:
+
+```javascript
+import MyComponent from '../../src/components/MyComponent.js';
+
+const createMyComponent = async () => {
+  const container = document.createElement('div');
+  container.innerHTML = `<k-my-component></k-my-component>`;
+  document.body.appendChild(container);
+  const el = container.querySelector('k-my-component');
+  await el.updateComplete;
+  return { container, el };
+};
+
+const cleanup = (container) => {
+  if(container && container.parentNode){
+    container.parentNode.removeChild(container);
+  }
+};
+
+export default {
+  /*
+    Element Creation
+  */
+  'should create my-component element': async ({pass, fail}) => {
+    const { container, el } = await createMyComponent();
+    if(!(el instanceof MyComponent)){
+      cleanup(container);
+      return fail('Element should be instance of MyComponent');
+    }
+    cleanup(container);
+    pass('MyComponent element created correctly');
+  },
+};
+```
+
+After writing the tests, run them to confirm they all pass:
+
+```
+npm run test -- MyComponent
+```
+
+The partial string `MyComponent` will match any test file whose path contains that string. Fix any failures before considering the component complete.
+
+---
+
 ## Component Architecture and Communication
 
 - Use **methods** to trigger actions. Events notify that something already happened; they should not be used to trigger logic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-ui",
-  "version": "0.0.81",
+  "version": "0.0.83",
   "type": "module",
   "description": "A Lit based web-component library",
   "main": "index.js",

package/tests/components/FilterItem.browser-test.js

@@ -0,0 +1,104 @@
+import FilterItem from '../../src/components/FilterItem.js';
+
+const createFilterItem = async (content = 'item') => {
+	const container = document.createElement('div');
+	container.innerHTML = `<k-filter-item>${content}</k-filter-item>`;
+	document.body.appendChild(container);
+	const el = container.querySelector('k-filter-item');
+	await el.updateComplete;
+	return { container, el };
+};
+
+const cleanup = (container) => {
+	if(container && container.parentNode){
+		container.parentNode.removeChild(container);
+	}
+};
+
+export default {
+	/*
+		Element Creation
+	*/
+	'should create filter-item element': async ({pass, fail}) => {
+		const { container, el } = await createFilterItem();
+		if(!el){
+			cleanup(container);
+			return fail('k-filter-item element should be created');
+		}
+		if(!(el instanceof FilterItem)){
+			cleanup(container);
+			return fail('Element should be instance of FilterItem');
+		}
+		cleanup(container);
+		pass('FilterItem element created correctly');
+	},
+
+	'should have shadow root': async ({pass, fail}) => {
+		const { container, el } = await createFilterItem();
+		if(!el.shadowRoot){
+			cleanup(container);
+			return fail('FilterItem should have shadow root');
+		}
+		cleanup(container);
+		pass('FilterItem has shadow root');
+	},
+
+	/*
+		Visibility
+	*/
+	'should be visible by default': async ({pass, fail}) => {
+		const { container, el } = await createFilterItem();
+		if(el.hidden){
+			cleanup(container);
+			return fail('FilterItem should be visible by default');
+		}
+		cleanup(container);
+		pass('FilterItem is visible by default');
+	},
+
+	'setting hidden should hide the element': async ({pass, fail}) => {
+		const { container, el } = await createFilterItem();
+		el.hidden = true;
+		await el.updateComplete;
+		const style = getComputedStyle(el);
+		if(style.display !== 'none'){
+			cleanup(container);
+			return fail(`Expected display:none when hidden, got ${style.display}`);
+		}
+		cleanup(container);
+		pass('FilterItem is hidden when hidden attribute is set');
+	},
+
+	'removing hidden should show the element': async ({pass, fail}) => {
+		const { container, el } = await createFilterItem();
+		el.hidden = true;
+		await el.updateComplete;
+		el.hidden = false;
+		await el.updateComplete;
+		const style = getComputedStyle(el);
+		if(style.display === 'none'){
+			cleanup(container);
+			return fail('FilterItem should be visible after removing hidden');
+		}
+		cleanup(container);
+		pass('FilterItem is visible after removing hidden');
+	},
+
+	/*
+		filter-keywords attribute
+	*/
+	'should accept filter-keywords attribute': async ({pass, fail}) => {
+		const container = document.createElement('div');
+		container.innerHTML = `<k-filter-item filter-keywords="foo bar">content</k-filter-item>`;
+		document.body.appendChild(container);
+		const el = container.querySelector('k-filter-item');
+		await el.updateComplete;
+		const kw = el.getAttribute('filter-keywords');
+		if(kw !== 'foo bar'){
+			cleanup(container);
+			return fail(`Expected filter-keywords "foo bar", got "${kw}"`);
+		}
+		cleanup(container);
+		pass('filter-keywords attribute set correctly');
+	},
+};

package/tests/components/FilterList.browser-test.js

@@ -0,0 +1,162 @@
+import FilterList from '../../src/components/FilterList.js';
+import '../../src/components/FilterItem.js';
+
+const createFilterList = async (items = []) => {
+	const container = document.createElement('div');
+	container.innerHTML = `<k-filter-list>${items.map(kw => `<k-filter-item filter-keywords="${kw}">${kw}</k-filter-item>`).join('')}</k-filter-list>`;
+	document.body.appendChild(container);
+	const el = container.querySelector('k-filter-list');
+	await el.updateComplete;
+	return { container, el };
+};
+
+const cleanup = (container) => {
+	if(container && container.parentNode){
+		container.parentNode.removeChild(container);
+	}
+};
+
+export default {
+	/*
+		Element Creation
+	*/
+	'should create filter-list element': async ({pass, fail}) => {
+		const { container, el } = await createFilterList();
+		if(!el){
+			cleanup(container);
+			return fail('k-filter-list element should be created');
+		}
+		if(!(el instanceof FilterList)){
+			cleanup(container);
+			return fail('Element should be instance of FilterList');
+		}
+		cleanup(container);
+		pass('FilterList element created correctly');
+	},
+
+	'should have shadow root': async ({pass, fail}) => {
+		const { container, el } = await createFilterList();
+		if(!el.shadowRoot){
+			cleanup(container);
+			return fail('FilterList should have shadow root');
+		}
+		cleanup(container);
+		pass('FilterList has shadow root');
+	},
+
+	/*
+		filter() — empty term
+	*/
+	'filter("") should show all items': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['apple', 'banana', 'cherry']);
+		el.filter('');
+		const items = [...el.querySelectorAll('k-filter-item')];
+		const hidden = items.filter(i => i.hidden);
+		if(hidden.length !== 0){
+			cleanup(container);
+			return fail(`Expected 0 hidden items, got ${hidden.length}`);
+		}
+		cleanup(container);
+		pass('All items visible when term is empty');
+	},
+
+	/*
+		filter() — single word
+	*/
+	'filter("apple") should hide non-matching items': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['apple', 'banana', 'cherry']);
+		el.filter('apple');
+		const banana = el.querySelector('[filter-keywords="banana"]');
+		const cherry = el.querySelector('[filter-keywords="cherry"]');
+		if(!banana.hidden || !cherry.hidden){
+			cleanup(container);
+			return fail('Non-matching items should be hidden');
+		}
+		cleanup(container);
+		pass('Non-matching items are hidden');
+	},
+
+	'filter("apple") should show matching item': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['apple', 'banana', 'cherry']);
+		el.filter('apple');
+		const apple = el.querySelector('[filter-keywords="apple"]');
+		if(apple.hidden){
+			cleanup(container);
+			return fail('Matching item should not be hidden');
+		}
+		cleanup(container);
+		pass('Matching item is visible');
+	},
+
+	/*
+		filter() — multi-word (AND logic)
+	*/
+	'filter("apple pie") should require all words to match': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['apple pie', 'apple', 'pie']);
+		el.filter('apple pie');
+		const applePie = el.querySelector('[filter-keywords="apple pie"]');
+		const appleOnly = el.querySelector('[filter-keywords="apple"]');
+		const pieOnly = el.querySelector('[filter-keywords="pie"]');
+		if(applePie.hidden){
+			cleanup(container);
+			return fail('Item matching all words should be visible');
+		}
+		if(!appleOnly.hidden || !pieOnly.hidden){
+			cleanup(container);
+			return fail('Items matching only one word should be hidden');
+		}
+		cleanup(container);
+		pass('Multi-word filter requires all words to match');
+	},
+
+	/*
+		filter() — case insensitivity
+	*/
+	'filter() should be case-insensitive': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['Apple', 'banana']);
+		el.filter('APPLE');
+		const apple = el.querySelector('[filter-keywords="Apple"]');
+		if(apple.hidden){
+			cleanup(container);
+			return fail('Matching should be case-insensitive');
+		}
+		cleanup(container);
+		pass('filter() is case-insensitive');
+	},
+
+	/*
+		filter() — no keywords attribute
+	*/
+	'items with no filter-keywords should be hidden when term is provided': async ({pass, fail}) => {
+		const container = document.createElement('div');
+		container.innerHTML = `<k-filter-list><k-filter-item>no keywords</k-filter-item></k-filter-list>`;
+		document.body.appendChild(container);
+		const el = container.querySelector('k-filter-list');
+		await el.updateComplete;
+		el.filter('something');
+		const item = el.querySelector('k-filter-item');
+		if(!item.hidden){
+			cleanup(container);
+			return fail('Item with no keywords should be hidden when term is given');
+		}
+		cleanup(container);
+		pass('Item with no keywords is hidden when term is provided');
+	},
+
+	/*
+		filter() — restore all after filtering
+	*/
+	'filter("") after filtering should restore all items': async ({pass, fail}) => {
+		const { container, el } = await createFilterList(['apple', 'banana']);
+		el.filter('apple');
+		el.filter('');
+		const items = [...el.querySelectorAll('k-filter-item')];
+		const hidden = items.filter(i => i.hidden);
+		if(hidden.length !== 0){
+			cleanup(container);
+			return fail(`Expected all items visible after clearing filter, got ${hidden.length} hidden`);
+		}
+		cleanup(container);
+		pass('All items restored after clearing filter');
+	},
+};

package/CONTRIBUTING.md

@@ -1,219 +0,0 @@
-# Code Contribution Guidelines
-
-## Project Structure
-
- - All code should be in the `src/` directory, with the exception of npm scripts.
- - All components should be in the `src/components/` directory.
- - All utility function module files should be in the `src/utils/` directory.
- - All documnentation should be in the `docs/` directory. This directory is used by GitHub as the "GitHub Pages", so all links need to be relative, and there will be a build script which copies all code to the `docs/` directory.
-
-## Coding Style Guidelines
-
-### Code Organization
-Use multi-line comments to separate code into logical sections. Group related functionality together.
-  - Example: In Lit components, group lifecycle callbacks, event handlers, public methods, utility functions, and rendering logic separately.
-
-```javascript
-/*
-  Lifecycle Callbacks
-*/
-```
-
-### Avoid single-use variables/functions
-Avoid defining a variable or function to only use it once; inline the logic where needed. Some exceptions include:
-  - recursion
-  - scope encapsulation (IIFE)
-  - context changes
-
-### Minimal Comments, Empty Lines, and Spacing
-
-Use minimal comments. Assume readers understand the language. Some exceptions include:
-  - complex logic
-  - anti-patterns
-  - code organization
-
-Do not put random empty lines within code; put them where they make sense for readability, for example:
-  - above and below definitions for functions and classes.
-  - to help break up large sections of logic to be more readable. If there are 100 lines of code with no breaks, it gets hard to read.
-  - above multi-line comments to indicate the comment belongs to the code below
-
-No  empty lines in css.
-
-End each file with an empty line.
-
-End each line with a `;` when possible, even if it is optional.
-
-Avoid unnecessary spacing, for example:
-  - after the word `if`
-  - within parentheses for conditional statements
-
-```javascript
-let count = 1;
-
-const incrementOdd = (n) => {
-  if(n % 2 !== 0){
-    return n++;
-  }
-  return n;
-};
-
-count = incrementOdd(count);
-```
-
-### Prefer Arrow Functions
-Prefer the use of arrow functions when possible, especially for class methods to avoid binding. Use normal functions if needed for preserving the proper context.
- - For very basic logic, use implicit returns
- - If there is a single parameter, omit the parentheses.
-```javascript
-const addOne = n => n + 1;
-```
-
-### Module Exports
-  - If a module has only one export, use the "default" export, not a named export.
-    - Do not declare the default export as a const or give it a name; just export the value.
-
-```javascript
-export default (n) => n + 1;
-```
-  - If a module has multiple exports, use named exports and do not use a "default" export.
-
-### Code Reuse
-Create utility functions for shared logic.
-  - If the shared logic is used in a single file, define a utility function in that file.
-  - If the shared logic is used in multiple files, create a utility function module file in `src/utils/`.
-
-### Naming
-Do not prefix identifiers with underscores.
-  - Never use leading underscores (`_`) for variable, property, method, or function names.
-  - Use clear, descriptive names without prefixes.
-  - When true privacy is needed inside classes, prefer native JavaScript private fields (e.g., `#myField`) instead of simulated privacy via underscores.
-
-## Components
-
-### Base Component Architecture
-
-The project provides three base components for different rendering strategies. Choose the appropriate base component and extend it:
-
-#### ShadowComponent
-For components that need shadow DOM encapsulation and automatic `/kempo.css` stylesheet injection.
-
-```javascript
-import ShadowComponent from './ShadowComponent.js';
-
-export default class MyComponent extends ShadowComponent {
-  render() {
-    return html`<p>Shadow DOM content with scoped styles</p>`;
-  }
-}
-```
-
-#### LightComponent  
-For components that render directly to light DOM without shadow DOM encapsulation.
-
-```javascript
-import LightComponent from './LightComponent.js';
-
-export default class MyComponent extends LightComponent {
-  renderLightDom() {
-    return html`<p>Light DOM content</p>`;
-  }
-}
-```
-
-#### HybridComponent
-For components that need both shadow DOM (with automatic `/kempo.css`) and light DOM rendering.
-
-```javascript
-import HybridComponent from './HybridComponent.js';
-
-export default class MyComponent extends HybridComponent {
-  render() {
-    return html`<p>Shadow DOM content</p>`;
-  }
-  
-  renderLightDom() {
-    return html`<p>Light DOM content alongside natural children</p>`;
-  }
-}
-```
-
-**Important:** Always call `super.updated()` when overriding the `updated()` method in LightComponent or HybridComponent to ensure proper rendering.
-
-### Component Architecture and Communication
-
-- Use methods to cause actions; do not emit events to trigger logic. Events are for notifying that something already happened.
-  - Prefer `el.closest('ktf-test-framework')?.enqueueSuite({...})` over firing an `enqueue` event.
-
-- Wrap dependent components inside a parent `ktf-test-framework` element. Children find it via `closest('ktf-test-framework')` and call its methods. The framework can query its subtree to orchestrate children.
-
-- Avoid `window` globals and global custom events for coordination. If broadcast is needed, scope events to the framework element; reserve window events for global, non-visual concerns (e.g., settings changes).
-
-## Development Workflow
-
-### NPM Scripts
-
-#### Build
-```bash
-npm run build
-```
-Compiles and minifies source files from `src/` and copies all necessary files to the `docs/` directory for GitHub Pages deployment.
-
-#### Documentation Server
-```bash
-npm run docs
-```
-Starts a local development server and opens the documentation site. Automatically runs the build script first.
-
-**Variants:**
-- `npm run docs:src` - Serves from `src/` instead of `docs/` for development
-- `npm run docs:no-build` - Skips the build step and serves existing `docs/`
-
-#### Testing
-```bash
-npm test              # Run all tests
-npm run test:gui      # Run tests with GUI interface
-npm run test:browser  # Run browser-only tests
-npm run test:node     # Run Node.js-only tests
-```
-
-#### Update Kempo CSS
-```bash
-npm run update-kempo-css
-```
-Downloads the latest version of Kempo CSS from the CDN and updates local files.
-
-### Adding Icons
-
-Use the `geticon` script to download icons from [Google Material Symbols](https://fonts.google.com/icons). The script automatically formats icons and triggers a build.
-
-#### Basic Usage
-```bash
-npm run geticon <icon_name>
-```
-
-Example:
-```bash
-npm run geticon format_bold
-```
-
-This downloads the icon and saves it as `format_bold.svg` in the `icons/` directory.
-
-#### Custom Naming
-
-Rename icons when downloading by providing a second argument:
-```bash
-npm run geticon <icon_name> <custom_name>
-```
-
-Example - download `content_copy` but save as `copy.svg`:
-```bash
-npm run geticon content_copy copy
-```
-
-#### What the Script Does
-
-- Downloads the specified icon from Google's Material Symbols CDN
-- Removes `width` and `height` attributes
-- Adds `fill="currentColor"` to all `<path>` elements
-- Saves the formatted SVG to the `icons/` directory
-- Automatically runs the build script to copy the icon to `docs/`