kempo-css 1.0.8 → 1.0.10

package/.github/copilot-instructions.md

@@ -0,0 +1,165 @@
+# 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
+
+### Local Development Server
+- **DO NOT** start a development server - one is already running
+- Default port: **8083**
+- Base URL: `http://localhost:8083`
+- Documentation URLs follow the directory/file structure in `docs/` (e.g., `docs/components/color-picker.html` → `http://localhost:8083/components/color-picker.html`)
+- Use this server for all testing and verification
+
+### Testing and Verification
+- **ALWAYS** verify changes using the live documentation on the running server
+- Use Chrome DevTools Protocol (chrome-devtools-mcp) for interactive testing
+- **DO NOT** create one-off test files or framework-less tests
+- Test components in their natural documentation environment
+- Validate both functionality and visual appearance

package/docs/.config.json

@@ -0,0 +1,15 @@
+{
+  "customRoutes": {
+    "/kempo.min.css": "../src/kempo.css",
+    "/kempo-hljs.min.css": "../src/kempo-hljs.css"
+  },
+  "middleware": {
+    "logging": {
+      "enabled": true,
+      "includeResponseTime": true
+    },
+    "security": {
+      "enabled": false
+    }
+  }
+}

package/docs/components/ThemePropertyInput.js

@@ -0,0 +1,47 @@
+import ShadowComponent from"https://cdn.jsdelivr.net/npm/kempo-ui@0.0.36/dist/components/ShadowComponent.js";import{html,css}from"https://cdn.jsdelivr.net/npm/kempo-ui@0.0.36/dist/lit-all.min.js";export default class ThemePropertyInput extends ShadowComponent{static properties={propName:{type:String,attribute:"prop-name"},value:{type:String},availableProperties:{type:Array,attribute:"available-properties"},mode:{type:String},initialColor:{type:String,attribute:"initial-color"}};static styles=css`
+    :host {
+      display: block;
+    }
+    label {
+      display: block;
+      margin-bottom: 0.25rem;
+    }
+    .input-wrapper {
+      display: flex;
+      gap: 0.5rem;
+      align-items: center;
+    }
+    .mode-select {
+      width: 100px;
+      flex-shrink: 0;
+    }
+    .value-input {
+      flex: 1;
+    }
+  `;constructor(){super(),this.propName="",this.value="",this.availableProperties=[],this.mode="color",this.initialColor=""}connectedCallback(){super.connectedCallback(),this.value?.startsWith("var(")&&(this.mode="var")}firstUpdated(){this.attachColorPickerListener()}updated(e){super.updated?.(e),this.attachColorPickerListener()}attachColorPickerListener(){if("color"===this.mode){const e=this.shadowRoot?.querySelector("k-color-picker");e&&!e._hasChangeListener&&(e._hasChangeListener=!0,e.addEventListener("change",this.handleColorChange),e.addEventListener("input",this.handleColorChange))}}handleModeChange=e=>{this.mode=e.target.value,"var"!==this.mode||this.value.startsWith("var(")?"color"===this.mode&&this.value.startsWith("var(")&&(this.value=this.initialColor||"#000000"):this.value=this.availableProperties[0]?`var(${this.availableProperties[0]})`:"",this.emitChange()};handleVarInput=e=>{const t=e.target.value;this.value=t.startsWith("var(")?t:`var(${t})`,this.emitChange()};handleColorChange=e=>{this.value=e.target.value,this.emitChange()};emitChange(){this.dispatchEvent(new CustomEvent("value-change",{detail:{propName:this.propName,value:this.value},bubbles:!0,composed:!0}))}render(){const e=`${this.propName}-datalist`,t=this.value?.startsWith("var(")?this.value.slice(4,-1).trim():"";return html`
+      <label>${this.propName}</label>
+      <div class="input-wrapper">
+        <select class="mode-select" .value=${this.mode} @change=${this.handleModeChange}>
+          <option value="var">Var</option>
+          <option value="color">Color</option>
+        </select>
+
+        ${"var"===this.mode?html`
+            <input 
+              class="value-input"
+              list=${e}
+              .value=${t}
+              @input=${this.handleVarInput}
+              placeholder="--property-name"
+            />
+            <datalist id=${e}>
+              ${this.availableProperties.map(e=>html`<option value=${e}></option>`)}
+            </datalist>
+          `:html`
+            <k-color-picker 
+              class="value-input"
+              value=${this.value}
+            ></k-color-picker>
+          `}
+      </div>
+    `}}customElements.define("k-theme-property-input",ThemePropertyInput);

package/docs/demo.inc.html

@@ -0,0 +1,182 @@
+<h1>Colors</h1>
+<h2>Background Colors</h2>
+<div class="d-f gap fw mb">
+  <div class="p bg-alt">bg-alt</div>
+  <div class="p bg-inv">bg-inv</div>
+  <div class="p bg-primary tc-on_primary">bg-primary</div>
+  <div class="p bg-secondary tc-on_secondary">bg-secondary</div>
+  <div class="p bg-success tc-on_success">bg-success</div>
+  <div class="p bg-warning tc-on_warning">bg-warning</div>
+  <div class="p bg-danger tc-on_danger">bg-danger</div>
+</div>
+<h2>Text Colors</h2>
+<div class="mb">
+  <p>Normal text color</p>
+  <p class="tc-muted">Muted text color</p>
+  <p class="tc-primary">Primary text color</p>
+  <p class="tc-secondary">Secondary text color</p>
+  <p class="tc-success">Success text color</p>
+  <p class="tc-warning">Warning text color</p>
+  <p class="tc-danger">Danger text color</p>
+</div>
+<div class="p bg-inv mb">
+  <p class="tc-inv">Inverse text color on inverse background</p>
+</div>
+
+<h1>Border Colors</h1>
+<div class="d-f gap fw mb">
+  <div class="p b">Default border</div>
+  <div class="p b bg-inv" style="border-color: var(--c_border__inv);">Inverse border</div>
+</div>
+
+<h1>Link Colors</h1>
+<p>
+  <a href="#">This is a link</a> - normal link styling
+</p>
+<div class="p bg-inv mb">
+  <a href="#" class="tc-link__inv">Inverse link</a> - for use on dark backgrounds
+</div>
+
+<h1>Buttons</h1>
+<h2>Button Types</h2>
+<div class="mb">
+  <button class="mb mr">button</button>
+  <input type="button" value="input" class="mb mr" />
+  <input type="submit" value="submit" class="mb mr" />
+  <a href="#" class="btn mb mr">a.btn</a>
+</div>
+
+<h2>Button Colors</h2>
+<div class="mb">
+  <button class="mb mr">Default</button>
+  <button class="primary mb mr">Primary</button>
+  <button class="secondary mb mr">Secondary</button>
+  <button class="success mb mr">Success</button>
+  <button class="warning mb mr">Warning</button>
+  <button class="danger mb mr">Danger</button>
+</div>
+
+<h2>Button Sizes</h2>
+<div class="d-f fw ai-center mb">
+  <button class="small mb mr">Small</button>
+  <button class="mb mr">Normal</button>
+  <button class="large mb mr">Large</button>
+</div>
+
+<h2>Button Groups</h2>
+<div class="btn-grp mb">
+  <button>One</button>
+  <button>Two</button>
+  <button>Three</button>
+</div>
+
+<h1>Inputs</h1>
+<div class="mb">
+  <label>Text Input</label>
+  <input type="text" placeholder="Enter text..." />
+</div>
+<div class="mb">
+  <label>Textarea</label>
+  <textarea placeholder="Enter longer text..."></textarea>
+</div>
+<div class="mb">
+  <label>Select</label>
+  <select>
+    <option>Option 1</option>
+    <option>Option 2</option>
+    <option>Option 3</option>
+  </select>
+</div>
+<div class="mb">
+  <input type="checkbox" id="demo-check1" />
+  <label for="demo-check1" class="checkbox">Checkbox 1</label>
+  <input type="checkbox" id="demo-check2" />
+  <label for="demo-check2" class="checkbox">Checkbox 2</label>
+</div>
+<div class="mb">
+  <input type="radio" name="demo-radios" id="demo-rad1" />
+  <label for="demo-rad1" class="checkbox">Radio 1</label>
+  <input type="radio" name="demo-radios" id="demo-rad2" />
+  <label for="demo-rad2" class="checkbox">Radio 2</label>
+</div>
+
+<h1>Focus & Effects</h1>
+<p>Click or tab to inputs and buttons to see focus styles.</p>
+<div class="mb">
+  <input type="text" class="mb mr" placeholder="Focus me..." />
+  <button class="mb mr">Focus me</button>
+  <button class="primary mb mr">Focus me</button>
+</div>
+<div class="p bg-alt drop-shadow mb" style="display: inline-block;">
+  Drop shadow effect
+</div>
+
+<h1>Typography</h1>
+<h2>Headings</h2>
+<h1>Heading 1</h1>
+<h2>Heading 2</h2>
+<h3>Heading 3</h3>
+<h4>Heading 4</h4>
+<h5>Heading 5</h5>
+<h6>Heading 6</h6>
+
+<h2>Paragraph Text</h2>
+<p>This is a paragraph of text demonstrating the base font family and size. The quick brown fox jumps over the lazy dog. Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+<p><small>This is small text.</small></p>
+<p><strong>This is bold text.</strong></p>
+
+<h2>Monospace</h2>
+<p><code>Inline code uses the monospace font family.</code></p>
+<pre>Preformatted text also uses monospace.</pre>
+
+<h1>Spacing & Layout</h1>
+<h2>Key</h2>
+<ul class="mb">
+  <li><strong class="tc-success">Green</strong> = Padding</li>
+  <li><strong class="tc-warning">Orange</strong> = Margins</li>
+</ul>
+
+<h2>Padding</h2>
+<div class="mb">
+  <div class="d-ib bg-success mr mb p"><div class="d-ib bg-alt pq">p</div></div>
+  <div class="d-ib bg-success mr mb pt"><div class="d-ib bg-alt pq">pt</div></div>
+  <div class="d-ib bg-success mr mb pr"><div class="d-ib bg-alt pq">pr</div></div>
+  <div class="d-ib bg-success mr mb pb"><div class="d-ib bg-alt pq">pb</div></div>
+  <div class="d-ib bg-success mr mb pl"><div class="d-ib bg-alt pq">pl</div></div>
+  <div class="d-ib bg-success mr mb px"><div class="d-ib bg-alt pq">px</div></div>
+  <div class="d-ib bg-success mr mb py"><div class="d-ib bg-alt pq">py</div></div>
+</div>
+
+<h2>Margins</h2>
+<div class="mb">
+  <div class="d-ib bg-warning mr mb p"><div class="d-ib bg-alt pq">m</div></div>
+  <div class="d-ib bg-warning mr mb pt"><div class="d-ib bg-alt pq">mt</div></div>
+  <div class="d-ib bg-warning mr mb pr"><div class="d-ib bg-alt pq">mr</div></div>
+  <div class="d-ib bg-warning mr mb pb"><div class="d-ib bg-alt pq">mb</div></div>
+  <div class="d-ib bg-warning mr mb pl"><div class="d-ib bg-alt pq">ml</div></div>
+  <div class="d-ib bg-warning mr mb px"><div class="d-ib bg-alt pq">mx</div></div>
+  <div class="d-ib bg-warning mr mb py"><div class="d-ib bg-alt pq">my</div></div>
+</div>
+
+<h2>Container</h2>
+<p>The <code>.container</code> class limits content width.</p>
+
+<h1>Effects & Animation</h1>
+<h2>Border Radius</h2>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b r">r</div>
+  <div class="d-ib bg-alt p mr mb b round">round</div>
+</div>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b rtl">rtl</div>
+  <div class="d-ib bg-alt p mr mb b rtr">rtr</div>
+  <div class="d-ib bg-alt p mr mb b rbr">rbr</div>
+  <div class="d-ib bg-alt p mr mb b rbl">rbl</div>
+</div>
+<div class="mb">
+  <div class="d-ib bg-alt p mr mb b rt">rt</div>
+  <div class="d-ib bg-alt p mr mb b rb">rb</div>
+  <div class="d-ib bg-alt p mr mb b rl">rl</div>
+  <div class="d-ib bg-alt p mr mb b rr">rr</div>
+</div>
+<p><small><strong>Note:</strong> Add <code>0</code> suffix (e.g., <code>r0</code>, <code>rt0</code>) to cancel border radius.</small></p>