kempo-css 1.0.8 → 1.0.9

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/.github/prompts/build-theme-editor.prompt.md

@@ -0,0 +1,89 @@
+---
+mode: "agent"
+tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'chromedevtools/chrome-devtools-mcp/*', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos', 'runSubagent']
+---
+
+# Theme Editor
+
+## Background
+kempo-css can be customized by the consumer by creating their own theme file (css) which overwrites the CSS Custom Properties defined in `src/kempo.css`, the file should not overwrite the actual style properties of elements, only overwrite CSS Custom Properties.
+
+## Description
+
+### Page Layout
+The theme editor" is a GUI which allows consumers to create and download a theme file. The page should be spit into 3 sections:
+  1. Navigation: The navbar is on top of the page.
+  2. Theme Editor: A set of inputs on the left side of the page, this should be full height (except the navigation) and be independently scrollable.
+     - This should have two sections, the top is a download / upload buttons, and a theme select.
+  3. Demo: HTML Elements that serve as examples to the user so they can see how their changes will affect the page. This should also be independently scrollable.
+
+### Changing the theme
+There should be two ways to change the theme.
+  - A `k-theme-switcher` component in the navigation bar (supports auto/light/dark) - already in place.
+  - A select dropdown on the top of the theme editor which allows the user to choose between "dark" and "light" (no "auto" option). This controls which theme's colors are being edited in the color pickers below. 
+  - The select dropdown should subscribe to the theme context to stay in sync when the theme changes via the `k-theme-switcher`. When "auto" is detected, resolve it to the actual current theme (light or dark) using the theme util.
+ 
+## Resources
+
+### Kempo-UI
+The theme editor should be built using the kempo-ui component library, which is based on Lit. Kempo-UI has already been installed as an external library.
+  - If new components need to be created for this feature, they should be placed in `src/components/` following the project's base component architecture (ShadowComponent, LightComponent, or HybridComponent).
+  - The "theme" utility should be used to get / set the theme and subscribe to theme changes.
+    - https://dustinpoissant.github.io/kempo-ui/utils/theme.html
+  - The "context" utility should be used to store the theme overwrites and synchronize UI state.
+    - https://dustinpoissant.github.io/kempo-ui/utils/context.html
+  - The "Color Picker" component should be used in the GUI.
+    - https://dustinpoissant.github.io/kempo-ui/components/color-picker.html
+  - The "Dialog" component should be used to allow the user to upload an existing theme for editing.
+    - https://dustinpoissant.github.io/kempo-ui/components/dialog.html
+ 
+### chrome-devtools-mcp
+The page is already running at http://localhost:4048/theme-editor.html there is no need to start a server, just use the chrome-devtools-mcp to verify that the theme editor is working exactly as expected.
+
+## Phases
+
+  0. Create a custom component `k-theme-property-input` in `src/components/` that handles CSS custom property values.
+     - This component should detect if the value is a CSS custom property reference (contains `var(--`).
+     - It should provide a toggle/switch to choose between "Custom Value" and "Reference Property".
+     - When in "Custom Value" mode for colors, show a `k-color-picker`.
+     - When in "Reference Property" mode, show a select dropdown listing all available CSS custom properties (filtered to relevant types, e.g., only color properties for color values).
+     - For properties with `light-dark()`, handle both the light and dark values, which may each independently be either a color or a property reference.
+     - The component should emit a change event with the full value (e.g., `var(--c_primary)` or `rgb(51, 102, 255)`).
+     - Use the chrome-devtools-mcp to verify this component works correctly in isolation before moving on.
+  1. Create a JavaScript object that is the default theme.
+     - This can be determined by looking at `src/kempo.css` and seeing what CSS Custom Properties are defined in the `:root` rule.
+     - The object structure should store light and dark values separately for properties using `light-dark()`, and preserve `var()` references:
+  2. Create the inputs for the CSS Custom Properties, the default values should be the default values from phase 1.
+     - For color CSS Custom Properties that use `light-dark()`, show one `k-theme-property-input` per property. The displayed value should reflect the current editing theme (selected in the theme editor dropdown, not necessarily the applied theme).
+     - The `k-theme-property-input` component should handle both direct color values and `var()` references automatically.
+     - Group inputs logically: Colors first (primary, secondary, danger, warning, success, backgrounds, text colors), then typography (fonts, sizes, weights), then spacing/layout, then other properties.
+     - For each input, add a label showing the CSS variable name (e.g., "Primary Color (--c_primary)").
+     - The demo content is already loaded via `<k-import src="./docs.inc.html">` in the right pane and includes examples of all themed elements.
+     - Use the chrome-devtools-mcp to verify the page looks correct before moving on to the next phase.s-is
+         // ... etc
+       }
+       ```
+     - Log it to the devtools console and verify using the chrome-devtools-mcp before moving on to the next phase.
+  2. Create the inputs for the CSS Custom Properties, the default values should be the default values from phase 1.
+     - For color CSS Custom Properties that use `light-dark()`, show one `k-color-picker` per property. The displayed value should reflect the current editing theme (selected in the theme editor dropdown, not necessarily the applied theme).
+     - Group inputs logically: Colors first (primary, secondary, danger, warning, success, backgrounds, text colors), then typography (fonts, sizes, weights), then spacing/layout, then other properties.
+     - For each color picker, add a label showing the CSS variable name (e.g., "Primary Color (--c_primary)").
+     - The demo content is already loaded via `<k-import src="./docs.inc.html">` in the right pane and includes examples of all themed elements.
+     - Use the chrome-devtools-mcp to verify the page looks correct before moving on to the next phase. 
+  3. Create an event listener that listens for any change on any input, creates a new "theme" object, compares that to the default theme object from phase 1 to create a "diff" object.
+  4. Create a theme css string from the diff object.
+     - Convert the diff object back into CSS custom properties with `light-dark()` functions where appropriate.
+     - The CSS should be wrapped in a `:root` selector.
+     - Apply this theme by injecting it into a `<style id="custom-theme">` tag in the head, replacing any existing custom theme.
+     - Save the CSS string to kempo-ui context for later download.
+     - Log the CSS string to the devtools console.
+     - Use the chrome-devtools-mcp to verify that the page looks correct and the CSS string in the devtools console looks correct:
+       - Change a color input for the light theme, verify the page updates immediately when in light mode.
+       - Switch to dark theme in the editor dropdown, change a dark color, verify the page updates when in dark mode.
+       - Change a non-color input (e.g., font size, spacing) and verify the page updates across both themes.sole looks correct.
+       - Change a color input and verify that the page is updating and looks by looking at the demo.
+       - Change a non-color input and verify that the page is updating and looks correct by looking at the demo. 
+  5. Hookup the "Download" button so that when the user clicks it, it downloads the minimal (diff) theme.
+      - If you have a way to verify this automatically attempt it but I might have to verify this manually, im not sure if AI agents can save the file and verify it. Ask me to save the file, i will then attach the theme file to the chat context so you can verify it looks correct.
+  6. Hookup the "Upload" button, it should use the kempo-ui Dialog to open a dialog that allows the user to upload a theme file, then when they click "Apply" it will will update the inputs on the page.
+      - If you have a way to verify this automatically attempt it, but I might have to verify this manually.

package/docs/.config.json

@@ -0,0 +1,17 @@
+{
+  "customRoutes": {
+    "/kempo.min.css": "../src/kempo.css",
+    "/kempo-hljs.min.css": "../src/kempo-hljs.css",
+    "/kempo-ui/**": "../node_modules/kempo-ui/dist/**",
+    "/icons/**": "../node_modules/kempo-ui/icons/**"
+  },
+  "middleware": {
+    "logging": {
+      "enabled": true,
+      "includeResponseTime": true
+    },
+    "security": {
+      "enabled": false
+    }
+  }
+}

package/docs/components/ThemePropertyInput.js

@@ -0,0 +1,47 @@
+import ShadowComponent from"/kempo-ui/components/ShadowComponent.js";import{html,css}from"/kempo-ui/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>