kempo-ui 0.3.4 → 0.3.6

package/docs-src/utils/context.page.html

@@ -0,0 +1,143 @@
+<page pageName="Context Utility" title="Context Utility - Kempo UI">
+  <content location="header"></content>
+  <content>
+    <h1>Context Utility</h1>
+    
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <div class="m ">
+          <h6>Usage</h6>
+          <a href="#basicUsage">Basic Usage</a><br />
+          <a href="#api">API Methods</a><br />
+          <a href="#examples">Examples</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>createContext</code> utility provides a simple way to create global or named shared state that components can subscribe to. It enables reactive state management with automatic subscriber notifications on value changes.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Import and create a context to manage shared state:</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> createContext <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/context.js'</span>;<br /><br /><span class="hljs-comment">// Create a named context with initial value</span><br /><span class="hljs-keyword">const</span> userContext = createContext(<span class="hljs-string">'user'</span>, { <span class="hljs-attr">name</span>: <span class="hljs-string">'Guest'</span> });<br /><br /><span class="hljs-comment">// Subscribe to changes</span><br />userContext.subscribe(<span class="hljs-function">(<span class="hljs-params">user</span>) =&gt;</span> {<br />  <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'User changed:'</span>, user);<br />});<br /><br /><span class="hljs-comment">// Update the context value</span><br />userContext.set({ <span class="hljs-attr">name</span>: <span class="hljs-string">'John Doe'</span> });</code></pre>
+
+    <h3 id="api"><a href="#api" class="no-link">API Methods</a></h3>
+
+    <h4><code>createContext(name, initialValue)</code></h4>
+    <p>Creates or retrieves a context with the specified name.</p>
+    <h5><code>name<i>: string</i></code> (optional)</h5>
+    <p>The name of the context. Defaults to <code>'global'</code>. Using the same name returns the same context instance.</p>
+    <h5><code>initialValue<i>: any</i></code> (optional)</h5>
+    <p>The initial value for the context. Only set if the context doesn't already have a value.</p>
+    <h5>Returns: <code>Object</code></h5>
+    <p>An object with the following methods:</p>
+
+    <h4><code>get()</code></h4>
+    <p>Returns the current value of the context.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> currentValue = userContext.get();</code></pre>
+
+    <h4><code>set(value)</code></h4>
+    <p>Updates the context value and notifies all subscribers.</p>
+    <pre><code class="hljs javascript">userContext.set({ <span class="hljs-attr">name</span>: <span class="hljs-string">'Jane Doe'</span>, <span class="hljs-attr">role</span>: <span class="hljs-string">'admin'</span> });</code></pre>
+
+    <h4><code>subscribe(callback)</code></h4>
+    <p>Subscribes to context changes. The callback is immediately invoked with the current value, then called again whenever the value changes.</p>
+    <h5><code>callback<i>: Function</i></code></h5>
+    <p>Function to call when the context value changes. Receives the new value as an argument.</p>
+    <h5>Returns: <code>Function</code></h5>
+    <p>An unsubscribe function to remove the subscription.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> unsubscribe = userContext.subscribe(<span class="hljs-function">(<span class="hljs-params">value</span>) =&gt;</span> {<br />  <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'New value:'</span>, value);<br />});<br /><br /><span class="hljs-comment">// Later, stop listening</span><br />unsubscribe();</code></pre>
+
+    <h4><code>unsubscribe(callback)</code></h4>
+    <p>Removes a subscriber callback from the context.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> handler = <span class="hljs-function">(<span class="hljs-params">value</span>) =&gt;</span> <span class="hljs-built_in">console</span>.log(value);<br />userContext.subscribe(handler);<br />userContext.unsubscribe(handler);</code></pre>
+
+    <h3 id="examples"><a href="#examples" class="no-link">Examples</a></h3>
+
+    <h4>Theme Management</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> createContext <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/context.js'</span>;<br /><br /><span class="hljs-keyword">const</span> themeContext = createContext(<span class="hljs-string">'theme'</span>, <span class="hljs-string">'light'</span>);<br /><br /><span class="hljs-comment">// Components can subscribe to theme changes</span><br />themeContext.subscribe(<span class="hljs-function">(<span class="hljs-params">theme</span>) =&gt;</span> {<br />  <span class="hljs-built_in">document</span>.body.className = theme;<br />});<br /><br /><span class="hljs-comment">// Toggle theme from anywhere</span><br /><span class="hljs-keyword">const</span> toggleTheme = <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {<br />  <span class="hljs-keyword">const</span> current = themeContext.get();<br />  themeContext.set(current === <span class="hljs-string">'light'</span> ? <span class="hljs-string">'dark'</span> : <span class="hljs-string">'light'</span>);<br />};</code></pre>
+
+    <h4>Component State Sharing</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> createContext <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/context.js'</span>;<br /><br /><span class="hljs-keyword">const</span> cartContext = createContext(<span class="hljs-string">'cart'</span>, []);<br /><br /><span class="hljs-comment">// Add item from one component</span><br /><span class="hljs-keyword">const</span> addToCart = <span class="hljs-function">(<span class="hljs-params">item</span>) =&gt;</span> {<br />  <span class="hljs-keyword">const</span> items = cartContext.get();<br />  cartContext.set([...items, item]);<br />};<br /><br /><span class="hljs-comment">// Display cart in another component</span><br />cartContext.subscribe(<span class="hljs-function">(<span class="hljs-params">items</span>) =&gt;</span> {<br />  <span class="hljs-built_in">document</span>.querySelector(<span class="hljs-string">'.cart-count'</span>).textContent = items.length;<br />});</code></pre>
+
+    <h4>Global vs Named Contexts</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> createContext <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/context.js'</span>;<br /><br /><span class="hljs-comment">// Use default global context</span><br /><span class="hljs-keyword">const</span> globalCtx = createContext();<br />globalCtx.set({ <span class="hljs-attr">appReady</span>: <span class="hljs-literal">true</span> });<br /><br /><span class="hljs-comment">// Named contexts are isolated</span><br /><span class="hljs-keyword">const</span> userCtx = createContext(<span class="hljs-string">'user'</span>);<br /><span class="hljs-keyword">const</span> settingsCtx = createContext(<span class="hljs-string">'settings'</span>);<br /><br /><span class="hljs-comment">// Same name returns the same context instance</span><br /><span class="hljs-keyword">const</span> userCtx2 = createContext(<span class="hljs-string">'user'</span>);<br /><span class="hljs-built_in">console</span>.log(userCtx === userCtx2); <span class="hljs-comment">// true</span></code></pre>
+
+    <h4>Working Example</h4>
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML & JavaScript">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"context-demo"</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">p</span>&gt;</span>Current count: <span class="hljs-tag">&lt;<span class="hljs-name">strong</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"count-display"</span>&gt;</span>0<span class="hljs-tag">&lt;/<span class="hljs-name">strong</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">p</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">button</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"increment"</span>&gt;</span>Increment<span class="hljs-tag">&lt;/<span class="hljs-name">button</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">button</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"decrement"</span>&gt;</span>Decrement<span class="hljs-tag">&lt;/<span class="hljs-name">button</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">button</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"reset"</span>&gt;</span>Reset<span class="hljs-tag">&lt;/<span class="hljs-name">button</span>&gt;</span>
+<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
+
+<span class="hljs-tag">&lt;<span class="hljs-name">script</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"module"</span>&gt;</span><span class="javascript">
+<span class="hljs-keyword">import</span> createContext <span class="hljs-keyword">from</span> <span class="hljs-string">'../src/utils/context.js'</span>;
+
+<span class="hljs-keyword">const</span> counterContext = createContext(<span class="hljs-string">'counter'</span>, <span class="hljs-number">0</span>);
+
+<span class="hljs-comment">// Subscribe to updates</span>
+counterContext.subscribe(<span class="hljs-function">(<span class="hljs-params">count</span>) =&gt;</span> {
+  <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">'count-display'</span>).textContent = count;
+});
+
+<span class="hljs-comment">// Button handlers</span>
+<span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">'increment'</span>)
+  .<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
+    counterContext.<span class="hljs-title function_">set</span>(counterContext.<span class="hljs-title function_">get</span>() + <span class="hljs-number">1</span>);
+  });
+
+<span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">'decrement'</span>)
+  .<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
+    counterContext.<span class="hljs-title function_">set</span>(counterContext.<span class="hljs-title function_">get</span>() - <span class="hljs-number">1</span>);
+  });
+
+<span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">'reset'</span>)
+  .<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">'click'</span>, <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {
+    counterContext.<span class="hljs-title function_">set</span>(<span class="hljs-number">0</span>);
+  });
+</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Results">
+          <div id="context-demo">
+            <p>Current count: <strong id="count-display">0</strong></p>
+            <button id="increment" class="primary">Increment</button>
+            <button id="decrement">Decrement</button>
+            <button id="reset" class="danger">Reset</button>
+          </div>
+        </k-card>
+      </div>
+    </div>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+    <script type="module">
+    import createContext from '{{pathToRoot}}src/utils/context.js';
+
+    const counterContext = createContext('counter-demo', 0);
+
+    counterContext.subscribe(count => {
+      document.getElementById('count-display').textContent = count;
+    });
+
+    document.getElementById('increment').addEventListener('click', () => {
+      counterContext.set(counterContext.get() + 1);
+    });
+
+    document.getElementById('decrement').addEventListener('click', () => {
+      counterContext.set(counterContext.get() - 1);
+    });
+
+    document.getElementById('reset').addEventListener('click', () => {
+      counterContext.set(0);
+    });
+  </script>
+  </content>
+</page>

package/docs-src/utils/cookie.page.html

@@ -0,0 +1,128 @@
+<page pageName="Cookie Utilities" title="Cookie Utilities - Kempo UI">
+  <content location="header"></content>
+  <content>
+		<h1>Cookie Utilities</h1>
+
+		<k-accordion persistent-id="toc" class="b r mb">
+			<k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+			<k-accordion-panel name="toc-panel">
+				<div class="m ">
+					<h6>Functions</h6>
+					<a href="#saveCookie">saveCookie</a><br />
+					<a href="#getCookie">getCookie</a><br />
+					<a href="#deleteCookie">deleteCookie</a><br />
+				</div>
+			</k-accordion-panel>
+		</k-accordion>
+
+		<h3>Description</h3>
+		<p>The cookie utilities module provides functions for managing browser cookies, including saving, retrieving, and
+			deleting cookie values.</p>
+
+		<h3>Working Example</h3>
+		<div class="row -mx mb">
+			<div class="col d-span-6 m-span-12 px">
+				<k-card label="HTML & JavaScript">
+					<pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"cookie-example"</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">p</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"saved-message"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">p</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">form</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"cookie-form"</span>&gt;</span>
+    <span class="hljs-tag">&lt;<span class="hljs-name">label</span> <span class="hljs-attr">for</span>=<span class="hljs-string">"cookie-value"</span>&gt;</span>Value to save:<span class="hljs-tag">&lt;/<span class="hljs-name">label</span>&gt;</span>
+    <span class="hljs-tag">&lt;<span class="hljs-name">input</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"text"</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"cookie-value"</span> <span class="hljs-attr">name</span>=<span class="hljs-string">"cookie-value"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"mb"</span> <span class="hljs-attr">placeholder</span>=<span class="hljs-string">"Enter a value"</span>&gt;</span>
+    <span class="hljs-tag">&lt;<span class="hljs-name">button</span> <span class="hljs-attr">type</span>=<span class="hljs-string">"submit"</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"primary"</span>&gt;</span>Save to Cookie<span class="hljs-tag">&lt;/<span class="hljs-name">button</span>&gt;</span>
+  <span class="hljs-tag">&lt;/<span class="hljs-name">form</span>&gt;</span>
+  <span class="hljs-tag">&lt;<span class="hljs-name">button</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"delete-btn"</span>&gt;</span>Delete Cookie<span class="hljs-tag">&lt;/<span class="hljs-name">button</span>&gt;</span>
+<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span>
+
+<span class="hljs-tag">&lt;<span class="hljs-name">script</span>&gt;</span><span class="javascript">
+<span class="hljs-keyword">import</span> { saveCookie, getCookie, deleteCookie } <span class="hljs-keyword">from</span> <span class="hljs-string">'../src/utils/cookie.js'</span>;
+
+<span class="hljs-comment">// Load saved value on page load</span>
+<span class="hljs-keyword">const</span> savedValue = getCookie(<span class="hljs-string">'example'</span>);
+<span class="hljs-keyword">if</span> (savedValue) {
+  document.getElementById(<span class="hljs-string">'saved-message'</span>).textContent = 
+    `Saved value from cookie: ${savedValue}`;
+}
+
+<span class="hljs-comment">// Handle form submission</span>
+document.getElementById(<span class="hljs-string">'cookie-form'</span>).addEventListener(<span class="hljs-string">'submit'</span>, (e) => {
+  e.preventDefault();
+  <span class="hljs-keyword">const</span> value = document.getElementById(<span class="hljs-string">'cookie-value'</span>).value;
+  saveCookie(<span class="hljs-string">'example'</span>, value);
+  <span class="hljs-comment">// Page will refresh due to form submission</span>
+  window.location.reload();
+});
+
+<span class="hljs-comment">// Delete cookie when delete button is clicked</span>
+document.getElementById(<span class="hljs-string">'delete-btn'</span>).addEventListener(<span class="hljs-string">'click'</span>, () => {
+  deleteCookie(<span class="hljs-string">'example'</span>);
+  window.location.reload();
+});
+</span><span class="hljs-tag">&lt;/<span class="hljs-name">script</span>&gt;</span></code></pre>
+				</k-card>
+			</div>
+			<div class="col d-span-6 m-span-12 px">
+				<k-card label="Results">
+					<div id="cookie-example">
+						<p id="saved-message"></p>
+						<form id="cookie-form">
+							<label for="cookie-value">"example" Cookie value:</label>
+							<input type="text" id="cookie-value" name="cookie-value" class="mb" placeholder="Enter a value">
+							<div class="d-f">
+								<div class="flex"></div>
+								<button id="delete-btn" class="danger mr" type="button">Delete Cookie</button>
+								<button type="submit" class="primary">Save to Cookie</button>
+							</div>
+						</form>
+					</div>
+				</k-card>
+			</div>
+		</div>
+
+		<h3 id="saveCookie"><a href="#saveCookie" class="no-link">saveCookie</a></h3>
+		<p>Saves a cookie with an optional expiration time and path.</p>
+		<pre><code class="hljs javascript"><span class="hljs-keyword">import</span> { saveCookie } <span class="hljs-keyword">from</span> <span class="hljs-string">'../src/utils/cookie.js'</span>;<br /><br /><span class="hljs-comment">// Save a cookie that expires in 30 minutes</span><br />saveCookie(<span class="hljs-string">'userId'</span>, <span class="hljs-string">'12345'</span>);<br /><br /><span class="hljs-comment">// Save a cookie that expires in 1 hour</span><br />saveCookie(<span class="hljs-string">'session'</span>, <span class="hljs-string">'abc123'</span>, <span class="hljs-number">60</span>);</code></pre>
+
+		<h3 id="getCookie"><a href="#getCookie" class="no-link">getCookie</a></h3>
+		<p>Retrieves the value of a cookie by name.</p>
+		<pre><code class="hljs javascript"><span class="hljs-keyword">import</span> { getCookie } <span class="hljs-keyword">from</span> <span class="hljs-string">'../src/utils/cookie.js'</span>;<br /><br /><span class="hljs-keyword">const</span> userId = getCookie(<span class="hljs-string">'userId'</span>); <span class="hljs-comment">// "12345" or null if not found</span></code></pre>
+
+		<h3 id="deleteCookie"><a href="#deleteCookie" class="no-link">deleteCookie</a></h3>
+		<p>Deletes a cookie by setting its expiration to a past date.</p>
+		<pre><code class="hljs javascript"><span class="hljs-keyword">import</span> { deleteCookie } <span class="hljs-keyword">from</span> <span class="hljs-string">'../src/utils/cookie.js'</span>;<br /><br />deleteCookie(<span class="hljs-string">'userId'</span>);</code></pre>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+    <script type="module">
+		import { saveCookie, getCookie, deleteCookie } from '{{pathToRoot}}src/utils/cookie.js';
+
+		// Load saved value on page load
+		const savedValue = getCookie('example');
+		const messageElement = document.getElementById('saved-message');
+		if (savedValue && messageElement) {
+			messageElement.textContent = `Saved value from cookie: ${savedValue}`;
+		}
+
+		// Handle form submission
+		const form = document.getElementById('cookie-form');
+		if (form) {
+			form.addEventListener('submit', (e) => {
+				e.preventDefault();
+				const value = document.getElementById('cookie-value').value;
+				saveCookie('example', value);
+				// Page will refresh due to form submission
+				window.location.reload();
+			});
+		}
+
+		// Delete cookie when delete button is clicked
+		const deleteBtn = document.getElementById('delete-btn');
+		if (deleteBtn) {
+			deleteBtn.addEventListener('click', () => {
+				deleteCookie('example');
+				window.location.reload();
+			});
+		}
+	</script>
+  </content>
+</page>

package/docs-src/utils/debounce.page.html

@@ -0,0 +1,42 @@
+<page pageName="debounce" title="debounce - Kempo UI">
+  <content location="header"></content>
+  <content>
+    <h1>debounce</h1>
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <div class="m ">
+          <h6>Usage</h6>
+          <a href="#basicUsage">Basic Usage</a><br />
+          <a href="#parameters">Parameters</a><br />
+          <a href="#examples">Examples</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>debounce</code> utility function limits the rate at which a function can be executed. It delays the
+      execution of a function until after a specified timeout has passed since the last time it was invoked.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Import and use the debounce function to limit function execution frequency:</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> debounce <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/debounce.js'</span>;<br /><br /><span class="hljs-keyword">const</span> handleSearch = debounce(<span class="hljs-function">(<span class="hljs-params">query</span>) =&gt;</span> {<br />  <span class="hljs-built_in">console</span>.log(<span class="hljs-string">'Searching for:'</span>, query);<br />}, <span class="hljs-number">300</span>);<br /><br /><span class="hljs-comment">// Will only execute after 300ms of no calls</span><br />handleSearch(<span class="hljs-string">'test'</span>);</code></pre>
+
+    <h3 id="parameters"><a href="#parameters" class="no-link">Parameters</a></h3>
+    <h5><code>func<i>: Function</i></code></h5>
+    <p>The function to debounce.</p>
+    <h5><code>timeout<i>: number</i></code> (optional)</h5>
+    <p>The number of milliseconds to delay execution. Defaults to 300ms.</p>
+
+    <h3 id="examples"><a href="#examples" class="no-link">Examples</a></h3>
+
+    <h4>Search Input Debouncing</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> debouncedSearch = debounce(<span class="hljs-function">(<span class="hljs-params">searchTerm</span>) =&gt;</span> {<br />  <span class="hljs-comment">// API call or expensive search operation</span><br />  performSearch(searchTerm);<br />}, <span class="hljs-number">500</span>);<br /><br />searchInput.addEventListener(<span class="hljs-string">'input'</span>, (e) =&gt; {<br />  debouncedSearch(e.target.value);<br />});</code></pre>
+
+    <h4>Window Resize Handler</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> debouncedResize = debounce(<span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> {<br />  <span class="hljs-comment">// Expensive layout calculations</span><br />  recalculateLayout();<br />}, <span class="hljs-number">250</span>);<br /><br /><span class="hljs-built_in">window</span>.addEventListener(<span class="hljs-string">'resize'</span>, debouncedResize);</code></pre>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+  </content>
+</page>

package/docs-src/utils/drag.page.html

@@ -0,0 +1,64 @@
+<page pageName="drag" title="drag - Kempo UI">
+  <content location="header"></content>
+  <content>
+    <h1>drag</h1>
+
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <div class="m ">
+          <a href="#basicUsage">Basic Usage</a><br />
+          <a href="#options">Options</a><br />
+          <a href="#callbacks">Callbacks</a><br />
+          <a href="#returnValue">Return Value</a><br />
+          <a href="#examples">Examples</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>drag</code> utility function enables drag interactions on DOM elements. It handles both mouse and touch
+      events, providing callbacks for drag start, move, and end events.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Import and use the drag function to make elements draggable. The function returns a cleanup function that should
+      be called to remove all event listeners:</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> drag <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/drag.js'</span>;<br /><br /><span class="hljs-keyword">const</span> element = <span class="hljs-built_in">document</span>.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.draggable'</span>);<br /><span class="hljs-keyword">const</span> cleanup = <span class="hljs-title function_">drag</span>({<br />  element,<br />  <span class="hljs-attr">callback</span>: <span class="hljs-function">(<span class="hljs-params">diff</span>) =&gt;</span> {<br />    <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">'Dragged:'</span>, diff.x, diff.y);<br />  }<br />});<br /><br /><span class="hljs-comment">// Later, when you need to remove the drag functionality</span><br /><span class="hljs-title function_">cleanup</span>();</code></pre>
+
+    <h3 id="options"><a href="#options" class="no-link">Options</a></h3>
+    <h5><code>element<i>: HTMLElement</i></code></h5>
+    <p>The DOM element to make draggable.</p>
+    <h5><code>preventScroll<i>: boolean</i></code> (optional)</h5>
+    <p>Whether to prevent scroll behavior during drag. Defaults to false.</p>
+
+    <h3 id="callbacks"><a href="#callbacks" class="no-link">Callbacks</a></h3>
+    <h5><code>callback<i>: Function</i></code> (optional)</h5>
+    <p>Called on every drag move. Receives a diff object with x, y coordinates and original options.</p>
+    <h5><code>startCallback<i>: Function</i></code> (optional)</h5>
+    <p>Called when drag starts. Receives a diff object with x: 0, y: 0 and original options.</p>
+    <h5><code>moveCallback<i>: Function</i></code> (optional)</h5>
+    <p>Called on every drag move (in addition to callback). Receives a diff object.</p>
+    <h5><code>endCallback<i>: Function</i></code> (optional)</h5>
+    <p>Called when drag ends. Receives a diff object with the final position.</p>
+
+    <h3 id="returnValue"><a href="#returnValue" class="no-link">Return Value</a></h3>
+    <h5><code>cleanup<i>: Function</i></code></h5>
+    <p>The drag function returns a cleanup function. Call this function to remove all event listeners and stop the drag
+      functionality. This is important for preventing memory leaks when removing or destroying components.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> cleanup = <span class="hljs-title function_">drag</span>({ element, callback });<br /><br /><span class="hljs-comment">// Later, when component is destroyed or drag is no longer needed</span><br /><span class="hljs-title function_">cleanup</span>();</code></pre>
+
+    <h3 id="examples"><a href="#examples" class="no-link">Examples</a></h3>
+
+    <h4>Draggable Element</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> box = <span class="hljs-built_in">document</span>.querySelector(<span class="hljs-string">'.box'</span>);<br /><span class="hljs-keyword">let</span> position = { <span class="hljs-attr">x</span>: <span class="hljs-number">0</span>, <span class="hljs-attr">y</span>: <span class="hljs-number">0</span> };<br /><br />drag({<br />  <span class="hljs-attr">element</span>: box,<br />  <span class="hljs-attr">callback</span>: <span class="hljs-function">(<span class="hljs-params">diff</span>) =&gt;</span> {<br />    position.x += diff.x;<br />    position.y += diff.y;<br />    box.style.transform = <span class="hljs-string">`translate(<span class="hljs-subst">${position.x}</span>px, <span class="hljs-subst">${position.y}</span>px)`</span>;<br />  }<br />});</code></pre>
+
+    <h4>Resize Handle</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> resizeHandle = <span class="hljs-built_in">document</span>.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.resize-handle'</span>);<br /><span class="hljs-keyword">const</span> panel = <span class="hljs-built_in">document</span>.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.panel'</span>);<br /><br /><span class="hljs-title function_">drag</span>({<br />  <span class="hljs-attr">element</span>: resizeHandle,<br />  <span class="hljs-attr">preventScroll</span>: <span class="hljs-literal">true</span>,<br />  <span class="hljs-attr">callback</span>: <span class="hljs-function">(<span class="hljs-params">diff</span>) =&gt;</span> {<br />    <span class="hljs-keyword">const</span> newWidth = panel.offsetWidth + diff.x;<br />    panel.style.width = <span class="hljs-title class_">Math</span>.<span class="hljs-title function_">max</span>(<span class="hljs-number">100</span>, newWidth) + <span class="hljs-string">'px'</span>;<br />  },<br />  <span class="hljs-attr">startCallback</span>: <span class="hljs-function">() =&gt;</span> {<br />    panel.classList.<span class="hljs-title function_">add</span>(<span class="hljs-string">'resizing'</span>);<br />  },<br />  <span class="hljs-attr">endCallback</span>: <span class="hljs-function">() =&gt;</span> {<br />    panel.classList.<span class="hljs-title function_">remove</span>(<span class="hljs-string">'resizing'</span>);<br />  }<br />});</code></pre>
+
+    <h4>Component with Cleanup</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> ShadowComponent <span class="hljs-keyword">from</span> <span class="hljs-string">'./ShadowComponent.js'</span>;<br /><span class="hljs-keyword">import</span> drag <span class="hljs-keyword">from</span> <span class="hljs-string">'./utils/drag.js'</span>;<br /><br /><span class="hljs-keyword">class</span> <span class="hljs-title class_">DraggableComponent</span> <span class="hljs-keyword">extends</span> <span class="hljs-title class_">ShadowComponent</span> {<br />  <span class="hljs-title function_">constructor</span>() {<br />    <span class="hljs-variable language_">super</span>();<br />    <span class="hljs-variable language_">this</span>.cleanupDrag = <span class="hljs-literal">null</span>;<br />  }<br /><br />  <span class="hljs-title function_">firstUpdated</span>() {<br />    <span class="hljs-keyword">const</span> handle = <span class="hljs-variable language_">this</span>.shadowRoot.<span class="hljs-title function_">querySelector</span>(<span class="hljs-string">'.drag-handle'</span>);<br />    <span class="hljs-variable language_">this</span>.cleanupDrag = <span class="hljs-title function_">drag</span>({<br />      <span class="hljs-attr">element</span>: handle,<br />      <span class="hljs-attr">moveCallback</span>: <span class="hljs-function">(<span class="hljs-params">diff</span>) =&gt;</span> {<br />        <span class="hljs-variable language_">this</span>.style.transform = <span class="hljs-string">`translate(<span class="hljs-subst">${diff.x}</span>px, <span class="hljs-subst">${diff.y}</span>px)`</span>;<br />      }<br />    });<br />  }<br /><br />  <span class="hljs-title function_">disconnectedCallback</span>() {<br />    <span class="hljs-variable language_">super</span>.<span class="hljs-title function_">disconnectedCallback</span>();<br />    <span class="hljs-keyword">if</span>(<span class="hljs-variable language_">this</span>.cleanupDrag) {<br />      <span class="hljs-variable language_">this</span>.<span class="hljs-title function_">cleanupDrag</span>();<br />      <span class="hljs-variable language_">this</span>.cleanupDrag = <span class="hljs-literal">null</span>;<br />    }<br />  }<br />}</code></pre>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+  </content>
+</page>

package/docs-src/utils/elevation.page.html

@@ -0,0 +1,144 @@
+<page pageName="elevation" title="elevation - Kempo UI">
+  <content location="header"></content>
+  <content>
+
+    <h1>elevation</h1>
+    <k-accordion persistent-id="toc" class="b r mb">
+      <k-accordion-header for-panel="toc-panel">Table of Contents</k-accordion-header>
+      <k-accordion-panel name="toc-panel">
+        <div class="m">
+          <a href="#overview">Overview</a><br />
+          <a href="#levels">Elevation Levels</a><br />
+          <a href="#components">Component Assignments</a><br />
+          <a href="#customizing">Customizing</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3 id="overview"><a href="#overview" class="no-link">Overview</a></h3>
+    <p>
+      Kempo UI follows the <a href="https://dustinpoissant.github.io/kempo-css/#elevation" target="_blank">kempo-css elevation system</a>.
+      Elevation defines a component's position in the stacking order using a simple formula:
+    </p>
+    <p class="tc-primary fw-bold">z-index = level × 10</p>
+    <p>
+      There are 11 levels (0–10). Level 2 is the page default for normal document flow — most components do not need a
+      <code>z-index</code> at all. Fixed-position components that must appear above or below other layers each occupy a
+      dedicated level, with intentional gaps between them so user-defined elements (like a site navbar) always have a
+      clear, unambiguous home.
+    </p>
+    <p>
+      kempo-css provides three companion utilities that work alongside a component's elevation level:
+    </p>
+    <ul>
+      <li><code>elevation-<i>N</i></code> — sets <code>z-index: N * 10</code></li>
+      <li><code>shadow</code> — adds a depth shadow matching the elevation</li>
+      <li><code>bg-elevation</code> — adjusts the background color to the matching elevation tint</li>
+    </ul>
+
+    <h3 id="levels"><a href="#levels" class="no-link">Elevation Levels</a></h3>
+    <div class="table-wrapper mb">
+    <table>
+      <thead>
+        <tr>
+          <th>Level</th>
+          <th>z-index</th>
+          <th>Intended use</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr><td>0</td><td>0</td><td>Behind the page — sunken or background elements</td></tr>
+        <tr><td>1</td><td>10</td><td><em>Buffer zone — reserved for customization</em></td></tr>
+        <tr><td>2</td><td>20</td><td>Page default — normal document flow</td></tr>
+        <tr><td>3</td><td>30</td><td>Fixed panels that sit below a navbar (push drawers)</td></tr>
+        <tr><td>4</td><td>40</td><td><em>Buffer zone — reserved for customization</em></td></tr>
+        <tr><td>5</td><td>50</td><td>Fixed navbar (user-defined)</td></tr>
+        <tr><td>6</td><td>60</td><td>Overlay drawers — above a fixed navbar</td></tr>
+        <tr><td>7</td><td>70</td><td>Floating menus (dropdowns, popovers)</td></tr>
+        <tr><td>8</td><td>80</td><td>Full-screen modals and lightboxes</td></tr>
+        <tr><td>9</td><td>90</td><td>Notification toasts</td></tr>
+        <tr><td>10</td><td>100</td><td><em>Reserved — use only when absolutely necessary</em></td></tr>
+      </tbody>
+    </table>
+    </div>
+
+    <h3 id="components"><a href="#components" class="no-link">Component Assignments</a></h3>
+    <p>Every Kempo UI component that uses <code>position: fixed</code> is assigned an elevation level:</p>
+    <div class="table-wrapper mb">
+    <table>
+      <thead>
+        <tr>
+          <th>Level</th>
+          <th>z-index</th>
+          <th>Kempo UI Components</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>3</td>
+          <td>30</td>
+          <td>
+            <a href="{{pathToRoot}}components/aside.html">Aside</a> (<code>main="push"</code>),
+            <a href="{{pathToRoot}}components/side-panel.html">Side Panel</a>
+          </td>
+        </tr>
+        <tr>
+          <td>6</td>
+          <td>60</td>
+          <td>
+            <a href="{{pathToRoot}}components/aside.html">Aside</a> (<code>main="overlay"</code>)
+          </td>
+        </tr>
+        <tr>
+          <td>7</td>
+          <td>70</td>
+          <td>
+            <a href="{{pathToRoot}}components/dropdown.html">Dropdown</a>
+          </td>
+        </tr>
+        <tr>
+          <td>8</td>
+          <td>80</td>
+          <td>
+            <a href="{{pathToRoot}}components/dialog.html">Dialog</a>,
+            <a href="{{pathToRoot}}components/photo-viewer.html">Photo Viewer</a>
+          </td>
+        </tr>
+        <tr>
+          <td>9</td>
+          <td>90</td>
+          <td>
+            <a href="{{pathToRoot}}components/toast.html">Toast</a>
+          </td>
+        </tr>
+      </tbody>
+    </table>
+    </div>
+    <p>
+      The <strong>Aside</strong> component uses two different levels depending on its <code>main</code> attribute.
+      When <code>main="push"</code>, it shifts the page layout and should sit <em>below</em> your site navbar (level 3).
+      When <code>main="overlay"</code>, it floats over the page and needs to appear <em>above</em> the navbar (level 6).
+    </p>
+
+    <h3 id="customizing"><a href="#customizing" class="no-link">Customizing</a></h3>
+    <p>
+      To override a component's elevation, target its host element with a CSS custom property or a direct
+      <code>z-index</code> rule. For example, to raise the Toast to the very top:
+    </p>
+    <pre><code class="hljs css"><span class="hljs-selector-tag">k-toast</span> {
+  <span class="hljs-attribute">z-index</span>: <span class="hljs-number">100</span>;
+}</code></pre>
+    <p>
+      Levels 1 and 4 are intentionally empty buffer zones. Use them for custom fixed elements (e.g. a cookie banner at
+      level 4, or a persistent sticky bar at level 1) that need a guaranteed home relative to Kempo UI components.
+    </p>
+    <p>
+      Apply elevation classes from kempo-css directly to custom elements when you want them to participate in the same
+      system without writing raw <code>z-index</code> values:
+    </p>
+    <pre><code class="hljs html"><span class="hljs-tag">&lt;<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"elevation-5 shadow bg-elevation"</span>&gt;</span>My fixed navbar<span class="hljs-tag">&lt;/<span class="hljs-name">div</span>&gt;</span></code></pre>
+  </content>
+  <content location="scripts">
+    <script src="{{pathToRoot}}src/components/Accordion.js" type="module"></script>
+  </content>
+</page>