kempo-ui 0.3.5 → 0.3.7

package/docs-src/components/theme-select.page.html

@@ -0,0 +1,106 @@
+<page pageName="ThemeSelect" title="ThemeSelect - Components - Kempo Docs - A Web Components Solution">
+  <content>
+    <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 pl">
+        <h6>Examples</h6>
+        <a href="#basicUsage">Basic Usage</a><br />
+        <a href="#withLabel">With Label</a><br />
+
+        <h6 class="mt"><a href="#jsRef" class="no-link">JavaScript Reference</a></h6>
+        <a href="#constructor">Constructor</a><br />
+        <a href="#requirements">Requirements</a><br />
+        <a href="#properties">Properties</a><br />
+        <a href="#slots">Slots</a><br />
+        <a href="#staticMethods">Static Methods</a><br />
+      </div>
+    </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>ThemeSelect</code> component provides a dropdown select for users to choose between Light, Dark, and System Default themes. It extends the <a href="./shadow-component.html">ShadowComponent</a> class and uses the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> internally for state management, persistence, and synchronization.</p>
+    <p>If child content is provided, it renders as a label above the select. If no children are provided, no label is rendered.</p>
+    <p><strong>Note:</strong> You can manage theme state without this component by directly importing the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Use the <code>ThemeSelect</code> component without any children to render just the select dropdown.</p>
+
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-theme-select</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-theme-select</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Output">
+          <k-theme-select></k-theme-select>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="withLabel"><a href="#withLabel" class="no-link">With Label</a></h3>
+    <p>Provide child content to render a label above the select.</p>
+
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-theme-select</span>&gt;</span>Theme<span class="hljs-tag">&lt;/<span class="hljs-name">k-theme-select</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Output">
+          <k-theme-select>Theme</k-theme-select>
+        </k-card>
+      </div>
+    </div>
+
+    <h2 id="jsRef"><a href="#jsRef" class="no-link">JavaScript Reference</a></h2>
+
+    <h3 id="constructor"><a href="#constructor" class="no-link">Constructor</a></h3>
+    <h6>Extends <a href="./shadow-component.html">ShadowComponent</a></h6>
+    <h5>
+      <code>new ThemeSelect()</code>
+    </h5>
+
+    <h3 id="requirements"><a href="#requirements" class="no-link">Requirements</a></h3>
+    <ul>
+      <li><a href="./shadow-component.html">ShadowComponent</a></li>
+      <li><a href="{{pathToRoot}}utils/theme.html">theme</a> utility</li>
+    </ul>
+
+    <h3 id="properties"><a href="#properties" class="no-link">Properties</a></h3>
+    <h5><code>currentTheme<i>: string</i></code></h5>
+    <p>Gets or sets the current theme. Possible values are <code>"auto"</code>, <code>"light"</code>, or <code>"dark"</code>. This property is reactive and will trigger a re-render when changed. Syncs to <code>current-theme</code> attribute.</p>
+
+    <h3 id="slots"><a href="#slots" class="no-link">Slots</a></h3>
+    <h5><code>default</code></h5>
+    <p>The default slot renders as a label above the select. If no content is provided, no label is rendered.</p>
+
+    <h3 id="staticMethods"><a href="#staticMethods" class="no-link">Static Methods</a></h3>
+    <p><strong>Note:</strong> These static methods are convenience wrappers around the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>. For direct theme management without the component, use the theme utility directly.</p>
+    <h5><code>static setTheme(theme)<i>: void</i></code></h5>
+    <p>Sets the specified theme. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> which handles persistence and DOM updates.</p>
+    <ul>
+      <li><strong>theme</strong> <code>string</code> - The theme to set. Must be one of: <code>"auto"</code>, <code>"light"</code>, or <code>"dark"</code></li>
+    </ul>
+    <pre><code class="hljs javascript"><span class="hljs-title class_">ThemeSelect</span>.<span class="hljs-title function_">setTheme</span>(<span class="hljs-string">&#x27;dark&#x27;</span>);</code></pre>
+
+    <h5><code>static getCurrentTheme()<i>: string</i></code></h5>
+    <p>Gets the current theme. Returns <code>"auto"</code> if no theme is set. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> currentTheme = <span class="hljs-title class_">ThemeSelect</span>.<span class="hljs-title function_">getCurrentTheme</span>();<br><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(currentTheme);</code></pre>
+
+    <h5><code>static getCalculatedCurrentTheme()<i>: string</i></code></h5>
+    <p>Returns the effective theme, always <code>"dark"</code> or <code>"light"</code>. If the current theme is <code>"auto"</code>, this method uses the user's system preference (<code>prefers-color-scheme</code> media query) to determine the theme. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">const</span> effectiveTheme = <span class="hljs-title class_">ThemeSelect</span>.<span class="hljs-title function_">getCalculatedCurrentTheme</span>();<br><span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(effectiveTheme);</code></pre>
+
+    <h3>Related</h3>
+    <p>See the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> documentation for programmatic theme management without using this component.</p>
+    <p>See the <a href="./theme-switcher.html">ThemeSwitcher</a> component for a button-based toggle alternative.</p>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/ThemeSelect.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+  </content>
+</page>

package/docs-src/components/theme-switcher.page.html

@@ -0,0 +1,122 @@
+<page pageName="ThemeSwitcher" title="ThemeSwitcher - Components - Kempo Docs - A Web Components Solution">
+  <content>
+    <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 pl">
+        <h6>Examples</h6>
+        <a href="#basicUsage">Basic Usage</a><br />
+        <a href="#customPadding">Custom Padding</a><br />
+        
+        <h6 class="mt"><a href="#jsRef" class="no-link">JavaScript Reference</a></h6>
+        <a href="#constructor">Constructor</a><br />
+        <a href="#requirements">Requirements</a><br />
+        <a href="#properties">Properties</a><br />
+        <a href="#cssCustomProperties">CSS Custom Properties</a><br />
+        <a href="#methods">Methods</a><br />
+        <a href="#staticMethods">Static Methods</a><br />
+      </div>
+    </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>ThemeSwitcher</code> component provides a UI control for users to switch between different themes (auto, light, dark). It extends the <a href="./shadow-component.html">ShadowComponent</a> class and uses the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> internally for state management, persistence, and synchronization.</p>
+    <p><strong>Note:</strong> You can manage theme state without this component by directly importing the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Use the <code>ThemeSwitcher</code> component to allow users to cycle through themes. Clicking the button cycles through auto → light → dark → auto. The component automatically detects the user's system preference when in auto mode.</p>
+    
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-theme-switcher</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-theme-switcher</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Output">
+          <k-theme-switcher></k-theme-switcher>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="customPadding"><a href="#customPadding" class="no-link">Custom Padding</a></h3>
+    <p>You can customize the button padding by setting the <code>--padding</code> CSS custom property. The default padding uses <code>var(--spacer, 1rem)</code>.</p>
+    
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-theme-switcher</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"--padding: 0.5rem;"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-theme-switcher</span>&gt;</span><br/><span class="hljs-tag">&lt;<span class="hljs-name">k-theme-switcher</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"--padding: 2rem;"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-theme-switcher</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Output">
+          <k-theme-switcher style="--padding: 0.5rem;"></k-theme-switcher>
+          <k-theme-switcher style="--padding: 2rem;"></k-theme-switcher>
+        </k-card>
+      </div>
+    </div>
+
+    <h2 id="jsRef"><a href="jsRef" class="no-link">JavaScript Reference</a></h2>
+
+    <h3 id="constructor"><a href="#constructor" class="no-link">Constructor</a></h3>
+    <h6>Extends <a href="./shadow-component.html">ShadowComponent</a></h6>
+    <h5>
+      <code>new ThemeSwitcher()</code>
+    </h5>
+
+    <h3 id="requirements"><a href="#requirements" class="no-link">Requirements</a></h3>
+    <ul>
+      <li><a href="./shadow-component.html">ShadowComponent</a></li>
+      <li><a href="./icon.html">Icon</a></li>
+      <li><a href="{{pathToRoot}}utils/theme.html">theme</a> utility</li>
+    </ul>
+
+    <h3 id="properties"><a href="#properties" class="no-link">Properties</a></h3>
+    <h5><code>currentTheme<i>: string</i></code></h5>
+    <p>Gets or sets the current theme. Possible values are <code>"auto"</code>, <code>"light"</code>, or <code>"dark"</code>. This property is reactive and will trigger a re-render when changed. Syncs to <code>current-theme</code> attribute.</p>
+
+    <h3 id="cssCustomProperties"><a href="#cssCustomProperties" class="no-link">CSS Custom Properties</a></h3>
+    <h5><code>--padding<i>: length</i></code></h5>
+    <p>Controls the padding of the theme switcher button. Defaults to <code>var(--spacer, 1rem)</code>. You can override this to customize the button's spacing.</p>
+    <pre><code class="hljs css"><span class="hljs-selector-tag">k-theme-switcher</span> {
+  <span class="hljs-attribute">--padding</span>: <span class="hljs-number">0.5rem</span>;
+}</code></pre>
+
+    <h3 id="methods"><a href="#methods" class="no-link">Methods</a></h3>
+    <p>The <code>ThemeSwitcher</code> class does not introduce any new public methods beyond those provided by the <a href="./shadow-component.html">ShadowComponent</a> class.</p>
+
+    <h3 id="staticMethods"><a href="#staticMethods" class="no-link">Static Methods</a></h3>
+    <p><strong>Note:</strong> These static methods are convenience wrappers around the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>. For direct theme management without the component, use the theme utility directly.</p>
+    <h5><code>static setTheme(theme)<i>: void</i></code></h5>
+    <p>Sets the specified theme. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> which handles persistence and DOM updates.</p>
+    <ul>
+      <li><strong>theme</strong> <code>string</code> - The theme to set. Must be one of: <code>"auto"</code>, <code>"light"</code>, or <code>"dark"</code></li>
+    </ul>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// Programmatically set theme to dark mode</span>
+<span class="hljs-title class_">ThemeSwitcher</span>.<span class="hljs-title function_">setTheme</span>(<span class="hljs-string">'dark'</span>);</code></pre>
+
+    <h5><code>static getCurrentTheme()<i>: string</i></code></h5>
+    <p>Gets the current theme. Returns <code>"auto"</code> if no theme is set. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// Get the current theme</span>
+<span class="hljs-keyword">const</span> currentTheme = <span class="hljs-title class_">ThemeSwitcher</span>.<span class="hljs-title function_">getCurrentTheme</span>();
+<span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(currentTheme); <span class="hljs-comment">// "auto", "light", or "dark"</span></code></pre>
+    
+    <h5><code>static getCalculatedCurrentTheme()<i>: string</i></code></h5>
+    <p>Returns the effective theme, always <code>"dark"</code> or <code>"light"</code>. If the current theme is <code>"auto"</code>, this method uses the user's system preference (<code>prefers-color-scheme</code> media query) to determine the theme. Internally calls the <a href="{{pathToRoot}}utils/theme.html">theme utility</a>.</p>
+    <pre><code class="hljs javascript"><span class="hljs-comment">// Get the calculated current theme</span>
+  <span class="hljs-keyword">const</span> effectiveTheme = <span class="hljs-title class_">ThemeSwitcher</span>.<span class="hljs-title function_">getCalculatedCurrentTheme</span>();
+  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(effectiveTheme); <span class="hljs.comment">// "dark" or "light"</span></code></pre>
+
+    <h3 id="themeDetection"><a href="#themeDetection" class="no-link">Automatic Theme Detection</a></h3>
+    <p>When the theme is set to <code>"auto"</code>, the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> automatically detects the user's system preference using <code>prefers-color-scheme</code> media query. The detected theme is applied to the document element as an <code>auto-theme</code> attribute.</p>
+    <p>The theme utility handles persistence via localStorage and ensures theme changes are reflected in the DOM, providing a consistent user experience.</p>
+    
+    <h3>Related</h3>
+    <p>See the <a href="{{pathToRoot}}utils/theme.html">theme utility</a> documentation for programmatic theme management without using this component.</p>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/ThemeSwitcher.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+  </content>
+</page>

package/docs-src/components/timestamp.page.html

@@ -0,0 +1,109 @@
+<page pageName="Timestamp" title="Timestamp - Components - Kempo Docs - A Web Components Solution">
+  <content>
+    <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>Examples</h6>
+          <a href="#basicUsage">Basic Usage</a><br />
+          <a href="#customFormat">Custom Format</a><br />
+          <ul>
+            <li><a href="#timeFormat">Time Format</a></li>
+          </ul>
+
+          <h6 class="mt"><a href="#jsRef" class="no-link">JavaScript Reference</a></h6>
+          <a href="#constructor">Constructor</a><br />
+          <a href="#requirements">Requirements</a><br />
+          <a href="#properties">Properties</a><br />
+          <a href="#methods">Methods</a><br />
+        </div>
+      </k-accordion-panel>
+    </k-accordion>
+
+    <h3>Description</h3>
+    <p>The <code>Timestamp</code> component displays a formatted timestamp using custom format tokens. It extends the
+      ShadowComponent class for encapsulated styling.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Use the <code>Timestamp</code> component to display a formatted timestamp. The component will automatically
+      format the timestamp using the default format or a custom format with tokens.</p>
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-timestamp</span> <span class="hljs-attr">timestamp</span>=<span class="hljs-string">"1633024800000"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-timestamp</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Results">
+          <k-timestamp timestamp="1633024800000"></k-timestamp>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="customFormat"><a href="#customFormat" class="no-link">Custom Format</a></h3>
+    <p>Use the <code>format</code> attribute to specify a custom format using tokens like <code>YYYY</code> (4-digit
+      year), <code>MM</code> (2-digit month), <code>DD</code> (2-digit day), <code>hh</code> (2-digit hour),
+      <code>mm</code> (2-digit minute), and <code>ss</code> (2-digit second).
+    </p>
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-timestamp</span> <span class="hljs-attr">timestamp</span>=<span class="hljs-string">"1633024800000"</span> <span class="hljs-attr">format</span>=<span class="hljs-string">"MM/DD/YYYY"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-timestamp</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Results">
+          <k-timestamp timestamp="1633024800000" format="MM/DD/YYYY"></k-timestamp>
+        </k-card>
+      </div>
+    </div>
+
+
+
+    <h4 id="timeFormat"><a href="#timeFormat" class="no-link">Time Format</a></h4>
+    <p>Display time with custom formatting using hour, minute, and second tokens.</p>
+    <div class="row -mx mb">
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-timestamp</span> <span class="hljs-attr">timestamp</span>=<span class="hljs-string">"1633024800000"</span> <span class="hljs-attr">format</span>=<span class="hljs-string">"hh:mm:ss"</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-timestamp</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col d-span-6 m-span-12 px">
+        <k-card label="Results">
+          <k-timestamp timestamp="1633024800000" format="hh:mm:ss"></k-timestamp>
+        </k-card>
+      </div>
+    </div>
+
+
+
+    <h2 id="jsRef"><a href="#jsRef" class="no-link">JavaScript Reference</a></h2>
+
+    <h3 id="constructor"><a href="#constructor" class="no-link">Constructor</a></h3>
+    <h6>Extends ShadowComponent</h6>
+
+    <h3 id="requirements"><a href="#requirements" class="no-link">Requirements</a></h3>
+    <ul>
+      <li>ShadowComponent</li>
+      <li><a href="{{pathToRoot}}utils/formatTimestamp.js">formatTimestamp Utility Function</a></li>
+    </ul>
+
+    <h3 id="properties"><a href="#properties" class="no-link">Properties</a></h3>
+    <h5><code>timestamp<i>: number</i></code></h5>
+    <p>The timestamp to be formatted and displayed. Syncs to <code>timestamp</code> attribute.</p>
+    <h5><code>format<i>: string</i></code></h5>
+    <p>The format to be used for formatting the timestamp using tokens like YYYY, MM, DD, hh, mm, ss. If not provided,
+      uses the default format. Syncs to <code>format</code> attribute.</p>
+    <h5><code>locale<i>: string</i></code></h5>
+    <p>The locale to be used for formatting the timestamp. Syncs to <code>locale</code> attribute.</p>
+
+    <h3 id="methods"><a href="#methods" class="no-link">Methods</a></h3>
+    <p>The <code>Timestamp</code> class does not introduce any new methods beyond those provided by the ShadowComponent
+      class.</p>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Timestamp.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Card.js"></script>
+  </content>
+</page>