kempo-ui 0.4.3 → 0.4.5

package/docs-src/components/voice-selector.page.html

@@ -0,0 +1,125 @@
+<page pageName="Voice Selector" title="Voice Selector - 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="#languageFilter">Language Filter</a><br />
+        <a href="#withTextToSpeech">With TextToSpeech</a><br />
+        <a href="#disabled">Disabled</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="#methods">Methods</a><br />
+        <a href="#events">Events</a><br />
+      </div>
+    </k-accordion-panel>
+    </k-accordion>
+
+    <p>Two cascading <code>&lt;select&gt;</code>s &mdash; the first picks a language, the second lists voices for that language. The chosen voice is persisted via the <a href="../utils/voice.html">voice utility</a>, so every <a href="./text-to-speech.html"><code>&lt;k-text-to-speech&gt;</code></a> on the page (and across reloads) uses it as a default when no <code>voice</code> attribute is set.</p>
+    <p>The language dropdown defaults to the browser's primary language (<code>navigator.language</code>) so a user almost always sees a relevant voice list immediately.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <p>Just drop the element into a settings page or somewhere visible. Voices load asynchronously, so the dropdowns may briefly be empty before the rest populate.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-voice-selector</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-voice-selector</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-voice-selector></k-voice-selector>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="languageFilter"><a href="#languageFilter" class="no-link">Initial Language</a></h3>
+    <p>Set <code>language</code> to override the default browser language. Accepts a primary language code (e.g. <code>"fr"</code>, <code>"es"</code>) or a full BCP&#x2011;47 tag (the primary part is used). The user can still switch via the dropdown afterward.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-voice-selector</span> <span class="hljs-attr">language</span>=<span class="hljs-string">&quot;fr&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-voice-selector</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-voice-selector language="fr"></k-voice-selector>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="withTextToSpeech"><a href="#withTextToSpeech" class="no-link">With TextToSpeech</a></h3>
+    <p>Pick a voice in the dropdown, then click any <code>&lt;k-text-to-speech&gt;</code> on the page that doesn't have its own <code>voice</code> attribute &mdash; it'll use your saved preference. The choice persists across page reloads.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-voice-selector</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-voice-selector</span>&gt;</span><br><span class="hljs-tag">&lt;<span class="hljs-name">k-text-to-speech</span> <span class="hljs-attr">text</span>=<span class="hljs-string">&quot;This will use the voice you picked above&quot;</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-text-to-speech</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-voice-selector class="mr"></k-voice-selector>
+          <k-text-to-speech text="This will use the voice you picked above"></k-text-to-speech>
+        </k-card>
+      </div>
+    </div>
+
+    <h3 id="disabled"><a href="#disabled" class="no-link">Disabled</a></h3>
+    <p>The <code>disabled</code> attribute prevents user interaction. The dropdown also auto-disables when the browser doesn't support the SpeechSynthesis API.</p>
+    <div class="row -mx">
+      <div class="col m-span-12 px">
+        <k-card label="HTML">
+          <pre><code class="hljs xml"><span class="hljs-tag">&lt;<span class="hljs-name">k-voice-selector</span> <span class="hljs-attr">disabled</span>&gt;</span><span class="hljs-tag">&lt;/<span class="hljs-name">k-voice-selector</span>&gt;</span></code></pre>
+        </k-card>
+      </div>
+      <div class="col m-span-12 px">
+        <k-card label="Output">
+          <k-voice-selector disabled></k-voice-selector>
+        </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 VoiceSelector()</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>The <a href="../utils/voice.html">voice utility</a></li>
+      <li>A browser with <code>window.speechSynthesis</code></li>
+    </ul>
+
+    <h3 id="properties"><a href="#properties" class="no-link">Properties</a></h3>
+    <h5><code>language<i>: String</i></code></h5>
+    <p>Optional initial language. If set, overrides the default <code>navigator.language</code> on first render. Accepts a primary language code (<code>"en"</code>, <code>"es"</code>) or a full BCP&#x2011;47 tag (the primary part is used). The user can change the language via the first dropdown afterward. Syncs to <code>language</code> attribute.</p>
+
+    <h5><code>placeholder<i>: String</i></code></h5>
+    <p>Label for the empty-selection option. Default is <code>"Browser default"</code>. Syncs to <code>placeholder</code> attribute.</p>
+
+    <h5><code>disabled<i>: Boolean</i></code></h5>
+    <p>When <code>true</code>, the dropdown cannot be changed. Syncs to <code>disabled</code> attribute.</p>
+
+    <h3 id="methods"><a href="#methods" class="no-link">Methods</a></h3>
+    <h5><code>refresh()<i>: void</i></code></h5>
+    <p>Force a re-read of <code>speechSynthesis.getVoices()</code>. Rarely needed since the component subscribes to the <code>voiceschanged</code> event, but useful if you populate voices dynamically.</p>
+
+    <h3 id="events"><a href="#events" class="no-link">Events</a></h3>
+    <h5><code>change</code></h5>
+    <p>Fires when the user picks a new voice. <code>detail</code> contains <code>{ voice: String }</code> &mdash; the voice name, or empty string for "browser default". The voice utility is updated automatically; this event is for callers that want to react in addition.</p>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/VoiceSelector.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/TextToSpeech.js"></script>
+    <script type="module" src="{{pathToRoot}}src/components/Icon.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/index.page.html

@@ -179,6 +179,12 @@
           <p class="tc-muted">Drag-and-drop lists with reordering and sort events.</p>
         </a>
       </div>
+      <div class="span-12 t-span-6 d-span-4 px">
+        <a href="{{pathToRoot}}components/speech-to-text.html" class="card mb no-link d-b">
+          <h3 class="tc-primary">Speech To Text</h3>
+          <p class="tc-muted">Microphone button that uses the Web Speech API to transcribe spoken input.</p>
+        </a>
+      </div>
       <div class="span-12 t-span-6 d-span-4 px">
         <a href="{{pathToRoot}}components/spinner.html" class="card mb no-link d-b">
           <h3 class="tc-primary">Spinner</h3>
@@ -209,6 +215,12 @@
           <p class="tc-muted">Input field for adding and removing tags with keyboard support.</p>
         </a>
       </div>
+      <div class="span-12 t-span-6 d-span-4 px">
+        <a href="{{pathToRoot}}components/text-to-speech.html" class="card mb no-link d-b">
+          <h3 class="tc-primary">Text To Speech</h3>
+          <p class="tc-muted">Button that speaks the given text aloud using the browser's SpeechSynthesis API.</p>
+        </a>
+      </div>
       <div class="span-12 t-span-6 d-span-4 px">
         <a href="{{pathToRoot}}components/theme-select.html" class="card mb no-link d-b">
           <h3 class="tc-primary">Theme Select</h3>
@@ -251,6 +263,12 @@
           <p class="tc-muted">Hierarchical data visualization with collapsible branches and custom leaf types.</p>
         </a>
       </div>
+      <div class="span-12 t-span-6 d-span-4 px">
+        <a href="{{pathToRoot}}components/voice-selector.html" class="card mb no-link d-b">
+          <h3 class="tc-primary">Voice Selector</h3>
+          <p class="tc-muted">Dropdown of available speech-synthesis voices, persisted via the voice utility for site-wide use.</p>
+        </a>
+      </div>
     </div>
 
     <h2>Base Components</h2>
@@ -337,6 +355,12 @@
           <p class="tc-muted">Functions for manipulating and analyzing JavaScript objects.</p>
         </a>
       </div>
+      <div class="span-12 t-span-6 d-span-4 px">
+        <a href="{{pathToRoot}}utils/voice.html" class="card mb no-link d-b">
+          <h3 class="tc-primary">voice</h3>
+          <p class="tc-muted">Persisted speech-synthesis voice preference with pub/sub, mirroring the theme utility.</p>
+        </a>
+      </div>
       <div class="span-12 t-span-6 d-span-4 px">
         <a href="{{pathToRoot}}utils/wait.html" class="card mb no-link d-b">
           <h3 class="tc-primary">wait</h3>

package/docs-src/nav.fragment.html

@@ -104,6 +104,9 @@
           <k-filter-item filter-keywords="sortable drag drop sort components"><a
               href="{{pathToRoot}}components/sortable.html"
             >Sortable<br><small>Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="speech to text speechtotext microphone voice recognition transcription components"><a
+              href="{{pathToRoot}}components/speech-to-text.html"
+            >Speech To Text<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="spinner loading components"><a
               href="{{pathToRoot}}components/spinner.html">Spinner<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="split pane components"><a
@@ -156,6 +159,9 @@
               href="{{pathToRoot}}components/tabs.html">Tabs<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="tags tag input components"><a
               href="{{pathToRoot}}components/tags.html">Tags<br><small>Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="text to speech texttospeech tts speak voice synthesis components"><a
+              href="{{pathToRoot}}components/text-to-speech.html"
+            >Text To Speech<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="theme select dropdown dark light components"><a
               href="{{pathToRoot}}components/theme-select.html"
             >Theme Select<br><small>Component</small></a></k-filter-item>
@@ -176,6 +182,9 @@
             >Toggle<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="tree treeview components"><a
               href="{{pathToRoot}}components/tree.html">Tree<br><small>Component</small></a></k-filter-item>
+          <k-filter-item filter-keywords="voice selector dropdown speech synthesis preference components"><a
+              href="{{pathToRoot}}components/voice-selector.html"
+            >Voice Selector<br><small>Component</small></a></k-filter-item>
           <k-filter-item filter-keywords="shadow component base"><a
               href="{{pathToRoot}}components/shadow-component.html"
             >Shadow Component<br><small>Base Component</small></a></k-filter-item>
@@ -209,6 +218,8 @@
               href="{{pathToRoot}}utils/theme.html">theme<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="type utils utility"><a
               href="{{pathToRoot}}utils/type.html">type<br><small>Utility</small></a></k-filter-item>
+          <k-filter-item filter-keywords="voice speech synthesis preference utils utility"><a
+              href="{{pathToRoot}}utils/voice.html">voice<br><small>Utility</small></a></k-filter-item>
           <k-filter-item filter-keywords="wait async utils utility"><a
               href="{{pathToRoot}}utils/wait.html">wait<br><small>Utility</small></a></k-filter-item>
         </k-filter-list>
@@ -281,11 +292,13 @@
         <a href="{{pathToRoot}}components/show-more.html">Show More</a>
         <a href="{{pathToRoot}}components/slider.html">Slider</a>
         <a href="{{pathToRoot}}components/sortable.html">Sortable</a>
+        <a href="{{pathToRoot}}components/speech-to-text.html">Speech To Text</a>
         <a href="{{pathToRoot}}components/spinner.html">Spinner</a>
         <a href="{{pathToRoot}}components/split.html">Split</a>
         <a href="{{pathToRoot}}components/table.html">Table</a>
         <a href="{{pathToRoot}}components/tabs.html">Tabs</a>
         <a href="{{pathToRoot}}components/tags.html">Tags</a>
+        <a href="{{pathToRoot}}components/text-to-speech.html">Text To Speech</a>
         <a href="{{pathToRoot}}components/theme-select.html">Theme Select</a>
         <a href="{{pathToRoot}}components/theme-switcher.html">Theme Switcher</a>
         <a href="{{pathToRoot}}components/time.html">Time</a>
@@ -293,6 +306,7 @@
         <a href="{{pathToRoot}}components/toast.html">Toast</a>
         <a href="{{pathToRoot}}components/toggle.html">Toggle</a>
         <a href="{{pathToRoot}}components/tree.html">Tree</a>
+        <a href="{{pathToRoot}}components/voice-selector.html">Voice Selector</a>
       </div>
 
       <h5 class="mb0">Base Components</h5>
@@ -315,6 +329,7 @@
         <a href="{{pathToRoot}}utils/string.html">string</a>
         <a href="{{pathToRoot}}utils/theme.html">theme</a>
         <a href="{{pathToRoot}}utils/type.html">type</a>
+        <a href="{{pathToRoot}}utils/voice.html">voice</a>
         <a href="{{pathToRoot}}utils/wait.html">wait</a>
       </div>
     </menu>

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

@@ -0,0 +1,66 @@
+<page pageName="Voice Utility" title="Voice Utility - Kempo UI">
+  <content location="header"></content>
+  <content>
+    <h1>Voice 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>voice</code> utility manages the user's preferred speech-synthesis voice across the site. It mirrors the <a href="./theme.html">theme</a> utility &mdash; persisting to <code>localStorage</code>, syncing across tabs via the <code>storage</code> event, and exposing a pub/sub API. Pair it with <a href="../components/voice-selector.html"><code>&lt;k-voice-selector&gt;</code></a> for a settings UI; <a href="../components/text-to-speech.html"><code>&lt;k-text-to-speech&gt;</code></a> automatically uses the saved preference when no <code>voice</code> attribute is set.</p>
+
+    <h3 id="basicUsage"><a href="#basicUsage" class="no-link">Basic Usage</a></h3>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> voice <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;./utils/voice.js&#x27;</span>;<br><span class="hljs-comment">// Get current preferred voice (empty string = use browser default)</span><br><span class="hljs-keyword">const</span> current = voice.<span class="hljs-title function_">get</span>();<br><span class="hljs-comment">// Set a preferred voice</span><br>voice.<span class="hljs-title function_">set</span>(<span class="hljs-string">&#x27;Google US English&#x27;</span>);<br><span class="hljs-comment">// Subscribe to changes</span><br><span class="hljs-keyword">const</span> unsubscribe = voice.<span class="hljs-title function_">subscribe</span>(<span class="hljs-function">(<span class="hljs-params">name</span>) =&gt;</span> {<br>  <span class="hljs-variable language_">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">&#x27;Voice preference changed to:&#x27;</span>, name);<br>});<br><span class="hljs-comment">// Enumerate available voices (may need to wait — the list loads async)</span><br><span class="hljs-keyword">const</span> voices = <span class="hljs-keyword">await</span> voice.<span class="hljs-title function_">waitForVoices</span>();</code></pre>
+
+    <h3 id="api"><a href="#api" class="no-link">API Methods</a></h3>
+
+    <h4><code>voice.get()</code></h4>
+    <p>Returns the user's saved voice name. An empty string means "no preference &mdash; use the browser default for the language".</p>
+    <h5>Returns: <code>string</code></h5>
+
+    <h4><code>voice.set(name)</code></h4>
+    <p>Sets the saved voice and persists it to <code>localStorage</code>. Pass an empty string (or a falsy value) to clear the preference.</p>
+    <h5><code>name<i>: string</i></code></h5>
+    <p>The voice <code>name</code> as reported by <code>speechSynthesis.getVoices()</code>, or a comma-separated fallback chain (<code>"Samantha, Google US English"</code>).</p>
+
+    <h4><code>voice.subscribe(callback)</code></h4>
+    <p>Subscribes to preference changes. Fires once immediately with the current value, then on every change (including changes from other tabs).</p>
+    <h5>Returns: <code>Function</code></h5>
+    <p>An unsubscribe function.</p>
+
+    <h4><code>voice.getAvailable()</code></h4>
+    <p>Synchronous shortcut for <code>window.speechSynthesis.getVoices()</code>. May return <code>[]</code> if the browser hasn't populated the list yet.</p>
+    <h5>Returns: <code>SpeechSynthesisVoice[]</code></h5>
+
+    <h4><code>voice.waitForVoices(timeoutMs?)</code></h4>
+    <p>Returns a promise that resolves with the list of available voices, waiting for the browser's <code>voiceschanged</code> event if the list is initially empty.</p>
+    <h5><code>timeoutMs<i>: number</i></code> &mdash; default <code>2000</code></h5>
+    <p>How long to wait before giving up and resolving with whatever the browser has.</p>
+    <h5>Returns: <code>Promise&lt;SpeechSynthesisVoice[]&gt;</code></h5>
+
+    <h4><code>voice.subscribeAvailable(callback)</code></h4>
+    <p>Subscribes to changes in the available voice list (fires on the <code>voiceschanged</code> event). Useful when populating a settings UI.</p>
+    <h5>Returns: <code>Function</code></h5>
+    <p>An unsubscribe function.</p>
+
+    <h3 id="examples"><a href="#examples" class="no-link">Examples</a></h3>
+
+    <h4>Building a Voice Picker by Hand</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> voice <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;./utils/voice.js&#x27;</span>;<br><br><span class="hljs-keyword">const</span> $select = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">getElementById</span>(<span class="hljs-string">&#x27;voice-picker&#x27;</span>);<br><br>voice.<span class="hljs-title function_">subscribeAvailable</span>(<span class="hljs-function">(<span class="hljs-params">voices</span>) =&gt;</span> {<br>  $select.<span class="hljs-property">innerHTML</span> = <span class="hljs-string">&#x27;&lt;option value=&quot;&quot;&gt;Browser default&lt;/option&gt;&#x27;</span>;<br>  <span class="hljs-keyword">for</span>(<span class="hljs-keyword">const</span> v <span class="hljs-keyword">of</span> voices){<br>    <span class="hljs-keyword">const</span> opt = <span class="hljs-variable language_">document</span>.<span class="hljs-title function_">createElement</span>(<span class="hljs-string">&#x27;option&#x27;</span>);<br>    opt.<span class="hljs-property">value</span> = v.<span class="hljs-property">name</span>;<br>    opt.<span class="hljs-property">textContent</span> = <span class="hljs-string">`<span class="hljs-subst">${v.name}</span> (<span class="hljs-subst">${v.lang}</span>)`</span>;<br>    $select.<span class="hljs-title function_">appendChild</span>(opt);<br>  }<br>  $select.<span class="hljs-property">value</span> = voice.<span class="hljs-title function_">get</span>();<br>});<br><br>$select.<span class="hljs-title function_">addEventListener</span>(<span class="hljs-string">&#x27;change&#x27;</span>, <span class="hljs-function">() =&gt;</span> voice.<span class="hljs-title function_">set</span>($select.<span class="hljs-property">value</span>));</code></pre>
+
+    <h4>Reading the Preference Without a Component</h4>
+    <pre><code class="hljs javascript"><span class="hljs-keyword">import</span> voice <span class="hljs-keyword">from</span> <span class="hljs-string">&#x27;./utils/voice.js&#x27;</span>;<br><br><span class="hljs-keyword">const</span> preferred = voice.<span class="hljs-title function_">get</span>();<br><span class="hljs-keyword">if</span>(preferred){<br>  <span class="hljs-built_in">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">`User picked: <span class="hljs-subst">${preferred}</span>`</span>);<br>} <span class="hljs-keyword">else</span> {<br>  <span class="hljs-built_in">console</span>.<span class="hljs-title function_">log</span>(<span class="hljs-string">&#x27;No preference set — using browser default&#x27;</span>);<br>}</code></pre>
+  </content>
+  <content location="scripts">
+    <script type="module" src="{{pathToRoot}}src/components/Accordion.js"></script>
+  </content>
+</page>

package/icons/mic.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path fill="currentColor" d="M395-435q-35-35-35-85v-240q0-50 35-85t85-35q50 0 85 35t35 85v240q0 50-35 85t-85 35q-50 0-85-35Zm85-205Zm-40 520v-123q-104-14-172-93t-68-184h80q0 83 58.5 141.5T480-320q83 0 141.5-58.5T680-520h80q0 105-68 184t-172 93v123h-80Zm68.5-371.5Q520-503 520-520v-240q0-17-11.5-28.5T480-800q-17 0-28.5 11.5T440-760v240q0 17 11.5 28.5T480-480q17 0 28.5-11.5Z"/></svg>

package/icons/record_voice_over.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path fill="currentColor" d="m798-322-62-62q44-41 69-97t25-119q0-63-25-118t-69-96l62-64q56 53 89 125t33 153q0 81-33 153t-89 125ZM670-450l-64-64q18-17 29-38.5t11-47.5q0-26-11-47.5T606-686l64-64q32 29 50 67.5t18 82.5q0 44-18 82.5T670-450Zm-310 10q-66 0-113-47t-47-113q0-66 47-113t113-47q66 0 113 47t47 113q0 66-47 113t-113 47ZM40-120v-112q0-33 17-62t47-44q51-26 115-44t141-18q77 0 141 18t115 44q30 15 47 44t17 62v112H40Zm80-80h480v-32q0-11-5.5-20T580-266q-36-18-92.5-36T360-320q-71 0-127.5 18T140-266q-9 5-14.5 14t-5.5 20v32Zm296.5-343.5Q440-567 440-600t-23.5-56.5Q393-680 360-680t-56.5 23.5Q280-633 280-600t23.5 56.5Q327-520 360-520t56.5-23.5ZM360-600Zm0 400Z"/></svg>

package/icons/stop.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 -960 960 960"><path fill="currentColor" d="M240-240v-480h480v480H240Z"/></svg>

package/llms.txt

@@ -76,11 +76,13 @@ import { html, css, LitElement } from 'kempo-ui/src/lit-all.min.js';
 | `<k-show-more>` | `ShowMore.js` | Truncated content with expand toggle | [show-more.html](https://dustinpoissant.github.io/kempo-ui/components/show-more.html) |
 | `<k-slider>` | `Slider.js` | Slider with min, max, discrete step snap points, vertical orientation, and dual-handle range mode via comma-separated `value` (e.g. `"20,80"`); `format` attribute for value formatting (e.g. `"$0.00"`) applied to change events, form submission, and optional drag `tooltip`; form-associated; fires `change` | [slider.html](https://dustinpoissant.github.io/kempo-ui/components/slider.html) |
 | `<k-sortable>` `<k-sortable-item>` | `Sortable.js` | Drag-to-reorder list | [sortable.html](https://dustinpoissant.github.io/kempo-ui/components/sortable.html) |
+| `<k-speech-to-text>` | `SpeechToText.js` | Microphone button wrapping the Web Speech API; click to start, click again or pause to stop; `language`, `continuous`, `interim`, `min-confidence` (0-1 noise filter), `timeout` (max recording seconds) attrs; fires `start`, `result` (with `{text, isFinal}`), `end` (with `{text}`), `error` | [speech-to-text.html](https://dustinpoissant.github.io/kempo-ui/components/speech-to-text.html) |
 | `<k-spinner>` | `Spinner.js` | Loading indicator; `size` (xs/sm/md/lg/xl), `variant` (spinner/dots/bar) | [spinner.html](https://dustinpoissant.github.io/kempo-ui/components/spinner.html) |
 | `<k-split>` | `Split.js` | Resizable split panes | [split.html](https://dustinpoissant.github.io/kempo-ui/components/split.html) |
 | `<k-table>` | `Table.js` | Data table with sorting, filtering, pagination, row selection, server sync; `placeholder` (default "No Records") shown when empty; `filtered-placeholder` shown when all records are filtered/hidden | [table.html](https://dustinpoissant.github.io/kempo-ui/components/table.html) |
 | `<k-tabs>` `<k-tab>` `<k-tab-content>` `<k-tab-spacer>` | `Tabs.js` | Tabbed interface; `<k-tab for-content="id">` links to `<k-tab-content name="id">` | [tabs.html](https://dustinpoissant.github.io/kempo-ui/components/tabs.html) |
 | `<k-tags>` `<k-tag>` | `Tags.js` | Tag input; add/remove tags; fires `change` | [tags.html](https://dustinpoissant.github.io/kempo-ui/components/tags.html) |
+| `<k-text-to-speech>` | `TextToSpeech.js` | Button that wraps `window.speechSynthesis`; speaks `text` attr or slotted content; `voice`, `language`, `rate`, `pitch`, `volume` attrs; methods `speak(text?)` / `stop()` / `toggle()`; fires `start`, `end`, `error` | [text-to-speech.html](https://dustinpoissant.github.io/kempo-ui/components/text-to-speech.html) |
 | `<k-theme-select>` | `ThemeSelect.js` | Dropdown to pick a theme | [theme-select.html](https://dustinpoissant.github.io/kempo-ui/components/theme-select.html) |
 | `<k-theme-switcher>` | `ThemeSwitcher.js` | Theme switcher with segmented and toggle display modes | [theme-switcher.html](https://dustinpoissant.github.io/kempo-ui/components/theme-switcher.html) |
 | `<k-time>` | `Time.js` | Wraps native `<input type="time">` with segmented hour/minute/AM-PM editing; `value` is 24-hour `HH:MM`; `increment` attr sets minute step (arrow-key granularity); `military` attr forces 24-hour display via `lang="en-GB"`; form-associated; fires `change` | [time.html](https://dustinpoissant.github.io/kempo-ui/components/time.html) |
@@ -88,6 +90,7 @@ import { html, css, LitElement } from 'kempo-ui/src/lit-all.min.js';
 | `<k-toast>` `<k-toast-container>` | `Toast.js` | Toast notifications; use `<k-toast-container>` once in page, call `.addToast(options)` | [toast.html](https://dustinpoissant.github.io/kempo-ui/components/toast.html) |
 | `<k-toggle>` | `Toggle.js` | On/off toggle; `value` (Boolean, reflects); methods: `on()`, `off()`, `toggle()`; fires `change`, `on`, `off` | [toggle.html](https://dustinpoissant.github.io/kempo-ui/components/toggle.html) |
 | `<k-tree>` `<k-tree-node>` | `Tree.js` | Expandable tree; nodes have `label`, `icon`, `href`, `expanded` | [tree.html](https://dustinpoissant.github.io/kempo-ui/components/tree.html) |
+| `<k-voice-selector>` | `VoiceSelector.js` | `<select>` populated with `speechSynthesis.getVoices()`; persists choice via the `voice` utility so any `<k-text-to-speech>` without an explicit `voice` attr uses the saved preference; `language` (BCP-47 prefix) attr filters the list; fires `change` | [voice-selector.html](https://dustinpoissant.github.io/kempo-ui/components/voice-selector.html) |
 
 ---
 
@@ -243,6 +246,7 @@ Located in `src/utils/`. Import individually.
 | `debounce.js` | `default` | `debounce(fn, ms)` — delay fn until calls stop | [debounce.html](https://dustinpoissant.github.io/kempo-ui/utils/debounce.html) |
 | `wait.js` | `wait`, `waitFrames` | `wait(ms)` → Promise; `waitFrames(n)` → Promise after n animation frames | [wait.html](https://dustinpoissant.github.io/kempo-ui/utils/wait.html) |
 | `theme.js` | `setTheme`, `getTheme`, `subscribeToTheme`, `initTheme`, `getCalculatedTheme` | Manage light/dark/auto theme; persists to localStorage | [theme.html](https://dustinpoissant.github.io/kempo-ui/utils/theme.html) |
+| `voice.js` | `getVoice`, `setVoice`, `subscribeToVoice`, `getAvailableVoices`, `waitForVoices`, `subscribeToAvailableVoices` | Persisted speech-synthesis voice preference (mirrors `theme`); used by `<k-voice-selector>` and consumed by `<k-text-to-speech>` when no explicit `voice` attr is set | [voice.html](https://dustinpoissant.github.io/kempo-ui/utils/voice.html) |
 | `propConverters.js` | `boolExists`, `boolTrueFalse` | Lit property converters for boolean attributes | [propConverters.html](https://dustinpoissant.github.io/kempo-ui/utils/propConverters.html) |
 | `context.js` | `default` | `createContext(key, initialValue)` → `{ get, set, subscribe }` pub/sub state | [context.html](https://dustinpoissant.github.io/kempo-ui/utils/context.html) |
 | `cookie.js` | `saveCookie`, `getCookie`, `deleteCookie` | Get/set/delete browser cookies | [cookie.html](https://dustinpoissant.github.io/kempo-ui/utils/cookie.html) |

package/package.json

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

package/src/components/SpeechToText.js

@@ -0,0 +1,252 @@
+import { html, css } from '../lit-all.min.js';
+import ShadowComponent from './ShadowComponent.js';
+import './Icon.js';
+
+export default class SpeechToText extends ShadowComponent {
+  static properties = {
+    language: { type: String, reflect: true },
+    continuous: { type: Boolean, reflect: true },
+    interim: { type: Boolean, reflect: true },
+    minConfidence: { type: Number, reflect: true, attribute: 'min-confidence' },
+    timeout: { type: Number, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    listening: { type: Boolean, reflect: true }
+  };
+
+  #recognition = null;
+  #buffer = '';
+  #interim = '';
+  #unsupported = false;
+  #timeoutId = null;
+
+  /*
+    Lifecycle Callbacks
+  */
+  constructor() {
+    super();
+    this.language = 'en-US';
+    this.continuous = false;
+    this.interim = false;
+    this.minConfidence = 0;
+    this.timeout = 0;
+    this.disabled = false;
+    this.listening = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    const SR = window.SpeechRecognition || window.webkitSpeechRecognition;
+    if(!SR){
+      this.#unsupported = true;
+      return;
+    }
+    this.#recognition = new SR();
+    this.#recognition.lang = this.language;
+    this.#recognition.continuous = this.continuous;
+    // Always enable interim internally so the `end` event has a fallback
+    // transcript when the engine doesn't finalize. The public `interim` attr
+    // controls whether `result` events fire for unfinalized chunks.
+    this.#recognition.interimResults = true;
+    this.#recognition.onstart = this.handleStart;
+    this.#recognition.onend = this.handleEnd;
+    this.#recognition.onresult = this.handleResult;
+    this.#recognition.onerror = this.handleError;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#clearTimeout();
+    if(this.#recognition){
+      try { this.#recognition.stop(); } catch(e) {}
+      this.#recognition.onstart = null;
+      this.#recognition.onend = null;
+      this.#recognition.onresult = null;
+      this.#recognition.onerror = null;
+      this.#recognition = null;
+    }
+  }
+
+  updated(changedProperties) {
+    super.updated(changedProperties);
+    if(this.#recognition){
+      if(changedProperties.has('language')) this.#recognition.lang = this.language;
+      if(changedProperties.has('continuous')) this.#recognition.continuous = this.continuous;
+    }
+  }
+
+  /*
+    Event Handlers
+  */
+  handleStart = () => {
+    this.#buffer = '';
+    this.#interim = '';
+    this.listening = true;
+    this.#armTimeout();
+    this.dispatchEvent(new CustomEvent('start', { bubbles: true }));
+  };
+
+  handleResult = (e) => {
+    let final = '';
+    let interim = '';
+    for(let i = e.resultIndex; i < e.results.length; i++){
+      const res = e.results[i];
+      const alt = res[0];
+      const confidence = typeof alt.confidence === 'number' ? alt.confidence : 0;
+      if(confidence < this.minConfidence) continue;
+      if(res.isFinal) final += alt.transcript;
+      else interim += alt.transcript;
+    }
+    if(final) this.#buffer += final;
+    // Only overwrite the cached interim when this event actually carries text.
+    // Chrome occasionally fires a "settling" result event where final/interim
+    // are both empty — wiping #interim in that case loses the last transcript
+    // and the `end` event ends up with nothing to report.
+    if(final || interim){
+      this.#interim = interim;
+    }
+    if(final || this.interim){
+      this.dispatchEvent(new CustomEvent('result', {
+        detail: {
+          text: (this.#buffer + (interim || this.#interim)).trim(),
+          isFinal: !!final && !interim
+        },
+        bubbles: true
+      }));
+    }
+  };
+
+  handleEnd = () => {
+    this.listening = false;
+    this.#clearTimeout();
+    // Include any unfinalized interim text — Chrome occasionally fires `end`
+    // without finalizing the last utterance.
+    const text = (this.#buffer + this.#interim).trim();
+    this.dispatchEvent(new CustomEvent('end', {
+      detail: { text },
+      bubbles: true
+    }));
+  };
+
+  handleError = (e) => {
+    this.listening = false;
+    this.#clearTimeout();
+    this.dispatchEvent(new CustomEvent('error', {
+      detail: { error: e.error, message: e.message },
+      bubbles: true
+    }));
+  };
+
+  #armTimeout = () => {
+    this.#clearTimeout();
+    if(this.timeout > 0){
+      this.#timeoutId = setTimeout(() => this.stop(), this.timeout * 1000);
+    }
+  };
+
+  #clearTimeout = () => {
+    if(this.#timeoutId){
+      clearTimeout(this.#timeoutId);
+      this.#timeoutId = null;
+    }
+  };
+
+  handleClick = () => {
+    if(this.disabled) return;
+    if(this.listening) this.stop();
+    else this.start();
+  };
+
+  /*
+    Public Methods
+  */
+  start = () => {
+    if(this.disabled || !this.#recognition || this.listening) return;
+    try { this.#recognition.start(); } catch(e) {}
+  };
+
+  stop = () => {
+    if(!this.#recognition || !this.listening) return;
+    try { this.#recognition.stop(); } catch(e) {}
+  };
+
+  toggle = () => {
+    this.handleClick();
+  };
+
+  /*
+    Rendering
+  */
+  render() {
+    const supported = !this.#unsupported;
+    const label = !supported
+      ? 'Speech recognition not supported in this browser'
+      : this.listening ? 'Stop listening' : 'Start listening';
+    return html`
+      <button
+        type="button"
+        class="no-btn btn ${this.listening ? 'listening' : ''}"
+        ?disabled=${this.disabled || !supported}
+        @click=${this.handleClick}
+        aria-label=${label}
+        title=${label}
+      >
+        <k-icon name=${this.listening ? 'stop' : 'mic'}></k-icon>
+      </button>
+    `;
+  }
+
+  /*
+    Styles
+  */
+  static styles = css`
+    :host {
+      --btn_size: 2.5rem;
+      --btn_bg: var(--c_bg);
+      --btn_bg__listening: var(--c_danger, #d32f2f);
+      --btn_tc__listening: white;
+      display: inline-block;
+    }
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+    }
+    .btn {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--btn_size);
+      height: var(--btn_size);
+      padding: 0;
+      border: 1px solid var(--c_border);
+      border-radius: 50%;
+      background: var(--btn_bg);
+      color: var(--tc);
+      cursor: pointer;
+      transition: background var(--animation_ms), color var(--animation_ms), border-color var(--animation_ms);
+    }
+    .btn:hover:not(:disabled) {
+      background: var(--c_bg__alt);
+    }
+    .btn:focus-visible {
+      outline: none;
+      box-shadow: var(--focus_shadow);
+    }
+    :host([listening]) .btn,
+    :host([listening]) .btn:hover,
+    :host([listening]) .btn:focus-visible {
+      background: var(--btn_bg__listening);
+      color: var(--btn_tc__listening);
+      border-color: transparent;
+      animation: pulse 1.4s infinite;
+    }
+    .btn:disabled {
+      cursor: not-allowed;
+    }
+    @keyframes pulse {
+      0%, 100% { box-shadow: 0 0 0 0 rgba(211, 47, 47, 0.5); }
+      50% { box-shadow: 0 0 0 10px rgba(211, 47, 47, 0); }
+    }
+  `;
+}
+
+customElements.define('k-speech-to-text', SpeechToText);