kempo-ui 0.4.3 → 0.4.5

package/src/components/TextToSpeech.js

@@ -0,0 +1,205 @@
+import { html, css } from '../lit-all.min.js';
+import ShadowComponent from './ShadowComponent.js';
+import { getVoice as getPreferredVoice } from '../utils/voice.js';
+import './Icon.js';
+
+export default class TextToSpeech extends ShadowComponent {
+  static properties = {
+    text: { type: String, reflect: true },
+    voice: { type: String, reflect: true },
+    language: { type: String, reflect: true },
+    rate: { type: Number, reflect: true },
+    pitch: { type: Number, reflect: true },
+    volume: { type: Number, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    speaking: { type: Boolean, reflect: true }
+  };
+
+  #unsupported = false;
+  #utterance = null;
+
+  /*
+    Lifecycle Callbacks
+  */
+  constructor() {
+    super();
+    this.text = '';
+    this.voice = '';
+    this.language = '';
+    this.rate = 1;
+    this.pitch = 1;
+    this.volume = 1;
+    this.disabled = false;
+    this.speaking = false;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if(typeof window === 'undefined' || !window.speechSynthesis || typeof window.SpeechSynthesisUtterance !== 'function'){
+      this.#unsupported = true;
+    }
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.stop();
+  }
+
+  /*
+    Utility
+  */
+  get effectiveText() {
+    if(this.text) return this.text;
+    return this.textContent.trim();
+  }
+
+  resolveVoice = () => {
+    if(this.#unsupported) return null;
+    // Use the explicit `voice` attribute first; if none is set, fall back to
+    // the user's saved preference from the voice utility (so a site-wide
+    // VoiceSelector can drive every TextToSpeech that hasn't opted out).
+    const source = this.voice || getPreferredVoice() || '';
+    if(!source) return null;
+    const voices = window.speechSynthesis.getVoices();
+    const candidates = source.split(',').map(s => s.trim()).filter(Boolean);
+    for(const name of candidates){
+      const match = voices.find(v => v.name === name);
+      if(match) return match;
+    }
+    return null;
+  };
+
+  /*
+    Public Methods
+  */
+  speak = (override) => {
+    if(this.disabled || this.#unsupported) return;
+    const text = (override !== undefined ? String(override) : this.effectiveText).trim();
+    if(!text) return;
+    // Cancel any in-flight speech (ours or otherwise) before queuing this one
+    window.speechSynthesis.cancel();
+    const utterance = new window.SpeechSynthesisUtterance(text);
+    utterance.rate = this.rate;
+    utterance.pitch = this.pitch;
+    utterance.volume = this.volume;
+    if(this.language) utterance.lang = this.language;
+    const voice = this.resolveVoice();
+    if(voice) utterance.voice = voice;
+    utterance.onstart = this.handleStart;
+    utterance.onend = this.handleEnd;
+    utterance.onerror = this.handleError;
+    this.#utterance = utterance;
+    window.speechSynthesis.speak(utterance);
+  };
+
+  stop = () => {
+    if(this.#unsupported) return;
+    window.speechSynthesis.cancel();
+  };
+
+  toggle = () => {
+    if(this.speaking) this.stop();
+    else this.speak();
+  };
+
+  /*
+    Event Handlers
+  */
+  handleStart = () => {
+    this.speaking = true;
+    this.dispatchEvent(new CustomEvent('start', { bubbles: true }));
+  };
+
+  handleEnd = () => {
+    this.speaking = false;
+    this.#utterance = null;
+    this.dispatchEvent(new CustomEvent('end', { bubbles: true }));
+  };
+
+  handleError = (e) => {
+    this.speaking = false;
+    this.#utterance = null;
+    this.dispatchEvent(new CustomEvent('error', {
+      detail: { error: e.error || 'unknown' },
+      bubbles: true
+    }));
+  };
+
+  handleClick = () => {
+    if(this.disabled) return;
+    this.toggle();
+  };
+
+  /*
+    Rendering
+  */
+  render() {
+    const supported = !this.#unsupported;
+    const label = !supported
+      ? 'Text-to-speech not supported in this browser'
+      : this.speaking ? 'Stop speaking' : 'Speak';
+    return html`
+      <button
+        type="button"
+        class="no-btn btn"
+        ?disabled=${this.disabled || !supported}
+        @click=${this.handleClick}
+        aria-label=${label}
+        title=${label}
+      >
+        <k-icon name=${this.speaking ? 'stop' : 'record_voice_over'}></k-icon>
+      </button>
+      <slot style="display:none"></slot>
+    `;
+  }
+
+  /*
+    Styles
+  */
+  static styles = css`
+    :host {
+      --btn_size: 2.5rem;
+      --btn_bg: var(--c_bg);
+      --btn_bg__speaking: var(--c_primary);
+      --btn_tc__speaking: 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([speaking]) .btn,
+    :host([speaking]) .btn:hover,
+    :host([speaking]) .btn:focus-visible {
+      background: var(--btn_bg__speaking);
+      color: var(--btn_tc__speaking);
+      border-color: transparent;
+    }
+    .btn:disabled {
+      cursor: not-allowed;
+    }
+  `;
+}
+
+customElements.define('k-text-to-speech', TextToSpeech);

package/src/components/VoiceSelector.js

@@ -0,0 +1,271 @@
+import { html, css } from '../lit-all.min.js';
+import ShadowComponent from './ShadowComponent.js';
+import {
+  getVoice,
+  setVoice,
+  subscribeToVoice,
+  subscribeToAvailableVoices
+} from '../utils/voice.js';
+
+const primaryLang = (tag) => (tag || '').split('-')[0].toLowerCase();
+
+const browserLanguage = () => {
+  if(typeof navigator === 'undefined') return 'en';
+  return primaryLang(navigator.language || 'en') || 'en';
+};
+
+let displayNames = null;
+try {
+  if(typeof Intl !== 'undefined' && Intl.DisplayNames){
+    const locale = (typeof navigator !== 'undefined' && navigator.language) || 'en';
+    displayNames = new Intl.DisplayNames([locale], { type: 'language' });
+  }
+} catch(e) {}
+
+// Cache for native-name lookups (Intl.DisplayNames in the language's own locale)
+// so we don't construct a new instance per option per render.
+const nativeNameCache = new Map();
+const getNativeName = (code) => {
+  if(nativeNameCache.has(code)) return nativeNameCache.get(code);
+  let native = '';
+  try {
+    if(typeof Intl !== 'undefined' && Intl.DisplayNames){
+      const dn = new Intl.DisplayNames([code], { type: 'language' });
+      native = dn.of(code) || '';
+    }
+  } catch(e) {}
+  // Capitalize the first character so dropdown labels look consistent —
+  // Intl.DisplayNames returns "español"/"français" lowercase, which looks
+  // off next to the capitalized localized name.
+  if(native){
+    native = native.charAt(0).toUpperCase() + native.slice(1);
+  }
+  nativeNameCache.set(code, native);
+  return native;
+};
+
+// Render a language code as "Localized (Native)" — e.g. "Spanish (Español)",
+// "Japanese (日本語)". The native name is a deliberate accessibility escape
+// hatch: if the user accidentally has the page in a language they can't read,
+// they can still recognize their own language by its native name. When the
+// localized and native names match (user already in that language) we skip
+// the duplicate.
+const formatLanguage = (code) => {
+  let localized = code;
+  if(displayNames){
+    try {
+      localized = displayNames.of(code) || code;
+    } catch(e) {}
+  }
+  const native = getNativeName(code);
+  if(native && native.toLowerCase() !== localized.toLowerCase()){
+    return `${localized} (${native})`;
+  }
+  return localized;
+};
+
+// Strip the parenthetical "(language (region))" that OS-level voices often
+// append to their name (e.g. "Eddy (German (Germany))" → "Eddy"). The actual
+// `value` we submit to SpeechSynthesis still uses the full name.
+const displayVoiceName = (name) => {
+  const cleaned = name.split('(')[0].trim();
+  return cleaned || name;
+};
+
+export default class VoiceSelector extends ShadowComponent {
+  static properties = {
+    language: { type: String, reflect: true },
+    placeholder: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    voices: { state: true },
+    selected: { state: true },
+    currentLang: { state: true }
+  };
+
+  #unsubVoices = null;
+  #unsubSelected = null;
+  #unsupported = false;
+  #langInitialized = false;
+
+  /*
+    Lifecycle Callbacks
+  */
+  constructor() {
+    super();
+    this.language = '';
+    this.placeholder = 'Browser default';
+    this.disabled = false;
+    this.voices = [];
+    this.selected = '';
+    this.currentLang = '';
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if(typeof window === 'undefined' || !window.speechSynthesis){
+      this.#unsupported = true;
+      return;
+    }
+    this.#unsubVoices = subscribeToAvailableVoices(list => {
+      this.voices = list;
+      this.#initLanguageOnce();
+    });
+    this.#unsubSelected = subscribeToVoice(name => {
+      this.selected = name || '';
+      // Keep the language dropdown in sync with externally-set voices
+      if(name){
+        const match = this.voices.find(v => v.name === name);
+        if(match && match.lang){
+          this.currentLang = primaryLang(match.lang);
+        }
+      }
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if(this.#unsubVoices) this.#unsubVoices();
+    if(this.#unsubSelected) this.#unsubSelected();
+    this.#unsubVoices = null;
+    this.#unsubSelected = null;
+  }
+
+  /*
+    Utility
+  */
+  #initLanguageOnce = () => {
+    if(this.#langInitialized || this.voices.length === 0) return;
+    this.#langInitialized = true;
+    // Priority: existing voice's language > attribute > navigator > first available
+    const fromVoice = this.selected
+      ? this.voices.find(v => v.name === this.selected)
+      : null;
+    if(fromVoice && fromVoice.lang){
+      this.currentLang = primaryLang(fromVoice.lang);
+      return;
+    }
+    if(this.language){
+      this.currentLang = primaryLang(this.language);
+      return;
+    }
+    const navLang = browserLanguage();
+    const langs = this.availableLanguages;
+    if(langs.includes(navLang)){
+      this.currentLang = navLang;
+    } else if(langs.length > 0){
+      this.currentLang = langs[0];
+    }
+  };
+
+  get availableLanguages() {
+    const langs = new Set();
+    for(const v of this.voices){
+      if(v.lang) langs.add(primaryLang(v.lang));
+    }
+    return [...langs].sort();
+  }
+
+  get voicesForCurrentLanguage() {
+    if(!this.currentLang) return this.voices;
+    return this.voices.filter(v => primaryLang(v.lang) === this.currentLang);
+  }
+
+  /*
+    Event Handlers
+  */
+  handleLanguageChange = (e) => {
+    if(this.disabled) return;
+    this.currentLang = e.target.value;
+    // If the saved voice no longer exists in this language, clear it
+    const stillValid = this.voicesForCurrentLanguage.some(v => v.name === this.selected);
+    if(!stillValid){
+      setVoice('');
+    }
+  };
+
+  handleVoiceChange = (e) => {
+    if(this.disabled) return;
+    const value = e.target.value;
+    setVoice(value);
+    this.dispatchEvent(new CustomEvent('change', {
+      detail: { voice: value, language: this.currentLang },
+      bubbles: true
+    }));
+  };
+
+  /*
+    Public Methods
+  */
+  refresh = () => {
+    if(this.#unsupported) return;
+    this.voices = window.speechSynthesis.getVoices();
+    this.#initLanguageOnce();
+  };
+
+  /*
+    Rendering
+  */
+  render() {
+    if(this.#unsupported){
+      return html`
+        <select disabled aria-label="Voice selector (unsupported)">
+          <option>Speech synthesis not supported</option>
+        </select>
+      `;
+    }
+    const langs = this.availableLanguages;
+    const voicesInLang = this.voicesForCurrentLanguage;
+    return html`
+      <div class="row">
+        <div class="col" style="min-width: 10rem; flex: 0 0 auto">
+          <select
+            class="lang"
+            aria-label="Language"
+            ?disabled=${this.disabled || langs.length === 0}
+            .value=${this.currentLang}
+            @change=${this.handleLanguageChange}
+          >
+            ${langs.map(code => html`
+              <option value=${code} ?selected=${code === this.currentLang}>${formatLanguage(code)}</option>
+            `)}
+          </select>
+        </div>
+        <div class="col">
+          <select
+            class="voice"
+            aria-label="Voice"
+            ?disabled=${this.disabled}
+            .value=${this.selected}
+            @change=${this.handleVoiceChange}
+          >
+            <option value="">${this.placeholder}</option>
+            ${voicesInLang.map(v => html`
+              <option
+                value=${v.name}
+                ?selected=${v.name === this.selected}
+              >${displayVoiceName(v.name)}</option>
+            `)}
+          </select>
+        </div>
+      </div>
+    `;
+  }
+
+  /*
+    Styles
+  */
+  static styles = css`
+    :host {
+      display: block;
+    }
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+    }
+    select {
+      width: 100%;
+    }
+  `;
+}
+
+customElements.define('k-voice-selector', VoiceSelector);

package/src/utils/voice.js

@@ -0,0 +1,103 @@
+/*
+  Voice Utility
+  - Manage the user's preferred speech-synthesis voice
+  - Subscribe to voice changes
+  - Persist voice to localStorage
+  - Sync across tabs via the storage event
+*/
+
+import createContext from './context.js';
+
+const STORAGE_KEY = 'k-voice';
+
+const getInitialVoice = () => {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    return stored || '';
+  } catch(e){
+    return '';
+  }
+};
+
+const voiceContext = createContext('voice', getInitialVoice());
+
+const persist = voice => {
+  try {
+    if(voice) localStorage.setItem(STORAGE_KEY, voice);
+    else localStorage.removeItem(STORAGE_KEY);
+  } catch(e) {}
+};
+
+voiceContext.subscribe(persist);
+
+if(typeof window !== 'undefined'){
+  window.addEventListener('storage', event => {
+    if(event.key === STORAGE_KEY){
+      voiceContext.set(event.newValue || '');
+    }
+  });
+}
+
+export const setVoice = name => voiceContext.set(name || '');
+
+export const getVoice = () => voiceContext.get();
+
+export const subscribeToVoice = callback => voiceContext.subscribe(callback);
+
+/*
+  Helpers for enumerating available voices from the browser.
+  getVoices() may return [] on the first call; the browser fires a
+  `voiceschanged` event when the list is ready. waitForVoices() returns a
+  promise that resolves once the list is populated (or after a small timeout
+  if the browser never fires the event).
+*/
+export const getAvailableVoices = () => {
+  if(typeof window === 'undefined' || !window.speechSynthesis) return [];
+  return window.speechSynthesis.getVoices();
+};
+
+export const waitForVoices = (timeoutMs = 2000) => {
+  if(typeof window === 'undefined' || !window.speechSynthesis){
+    return Promise.resolve([]);
+  }
+  const synth = window.speechSynthesis;
+  const initial = synth.getVoices();
+  if(initial.length > 0) return Promise.resolve(initial);
+  return new Promise(resolve => {
+    let settled = false;
+    const handler = () => {
+      if(settled) return;
+      settled = true;
+      synth.removeEventListener('voiceschanged', handler);
+      resolve(synth.getVoices());
+    };
+    synth.addEventListener('voiceschanged', handler);
+    setTimeout(() => {
+      if(settled) return;
+      settled = true;
+      synth.removeEventListener('voiceschanged', handler);
+      resolve(synth.getVoices());
+    }, timeoutMs);
+  });
+};
+
+export const subscribeToAvailableVoices = callback => {
+  if(typeof window === 'undefined' || !window.speechSynthesis){
+    callback([]);
+    return () => {};
+  }
+  const synth = window.speechSynthesis;
+  const fire = () => callback(synth.getVoices());
+  synth.addEventListener('voiceschanged', fire);
+  fire();
+  return () => synth.removeEventListener('voiceschanged', fire);
+};
+
+export default {
+  get: getVoice,
+  set: setVoice,
+  subscribe: subscribeToVoice,
+  getAvailable: getAvailableVoices,
+  waitForVoices,
+  subscribeAvailable: subscribeToAvailableVoices
+};