kempo-ui 0.4.4 → 0.4.5

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
+};

package/tests/components/TextToSpeech.browser-test.js

@@ -1,4 +1,5 @@
 import TextToSpeech from '../../src/components/TextToSpeech.js';
+import { setVoice } from '../../src/utils/voice.js';
 
 const createTextToSpeech = async (attrs = {}, slot = '') => {
   const container = document.createElement('div');
@@ -26,7 +27,7 @@ const cleanup = (container) => {
 // Stub window.speechSynthesis (which is a read-only getter in Chrome) by
 // patching its methods on the live object. SpeechSynthesisUtterance is a
 // constructor, swapped via Object.defineProperty.
-const installSynthesisStub = () => {
+const installSynthesisStub = (voicesList = []) => {
   const captured = {
     spoken: [],
     cancelled: 0
@@ -34,6 +35,7 @@ const installSynthesisStub = () => {
   const synth = window.speechSynthesis;
   const originalSpeak = synth.speak.bind(synth);
   const originalCancel = synth.cancel.bind(synth);
+  const originalGetVoices = synth.getVoices.bind(synth);
   synth.speak = (utterance) => {
     captured.spoken.push(utterance);
     queueMicrotask(() => {
@@ -41,6 +43,7 @@ const installSynthesisStub = () => {
     });
   };
   synth.cancel = () => { captured.cancelled++; };
+  synth.getVoices = () => voicesList;
 
   const OriginalUtterance = window.SpeechSynthesisUtterance;
   function StubUtterance(text){
@@ -65,6 +68,7 @@ const installSynthesisStub = () => {
     restore: () => {
       synth.speak = originalSpeak;
       synth.cancel = originalCancel;
+      synth.getVoices = originalGetVoices;
       Object.defineProperty(window, 'SpeechSynthesisUtterance', {
         value: OriginalUtterance,
         configurable: true,
@@ -407,6 +411,151 @@ export default {
     pass('error event fires with detail.error');
   },
 
+  /*
+    Voice Fallback Chain
+  */
+  'should pick first matching voice from a fallback chain': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Google US English' },
+      { name: 'Microsoft Zira' }
+    ]);
+    const { container, el } = await createTextToSpeech({
+      text: 'hi',
+      voice: 'Samantha, Google US English, Microsoft Zira'
+    });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Google US English'){
+      stub.restore();
+      cleanup(container);
+      return fail(`Expected voice "Google US English", got ${u.voice ? u.voice.name : 'null'}`);
+    }
+    stub.restore();
+    cleanup(container);
+    pass('First installed voice in chain is selected');
+  },
+
+  'should fall through earlier missing entries in the chain': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Microsoft Zira' }
+    ]);
+    const { container, el } = await createTextToSpeech({
+      text: 'hi',
+      voice: 'Samantha, Google US English, Microsoft Zira'
+    });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Microsoft Zira'){
+      stub.restore();
+      cleanup(container);
+      return fail(`Expected voice "Microsoft Zira", got ${u.voice ? u.voice.name : 'null'}`);
+    }
+    stub.restore();
+    cleanup(container);
+    pass('Falls through to a later installed voice');
+  },
+
+  'should not set voice when no candidate matches': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Karen' }
+    ]);
+    const { container, el } = await createTextToSpeech({
+      text: 'hi',
+      voice: 'Samantha, Google US English'
+    });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(u.voice !== null){
+      stub.restore();
+      cleanup(container);
+      return fail(`Expected voice null when no chain entry matches, got ${u.voice && u.voice.name}`);
+    }
+    stub.restore();
+    cleanup(container);
+    pass('voice stays null when no chain entry is installed');
+  },
+
+  'should ignore extra whitespace around chain entries': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Google US English' }
+    ]);
+    const { container, el } = await createTextToSpeech({
+      text: 'hi',
+      voice: '  Samantha ,   Google US English  '
+    });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Google US English'){
+      stub.restore();
+      cleanup(container);
+      return fail(`Expected voice "Google US English" after trim, got ${u.voice && u.voice.name}`);
+    }
+    stub.restore();
+    cleanup(container);
+    pass('Whitespace around comma-separated entries is ignored');
+  },
+
+  'should fall back to saved voice preference when no voice attr is set': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Karen', lang: 'en-AU' }
+    ]);
+    setVoice('Karen');
+    const { container, el } = await createTextToSpeech({ text: 'hi' });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Karen'){
+      stub.restore();
+      setVoice('');
+      cleanup(container);
+      return fail(`Expected fallback to saved voice "Karen", got ${u.voice && u.voice.name}`);
+    }
+    stub.restore();
+    setVoice('');
+    cleanup(container);
+    pass('Saved voice preference is used when voice attr is empty');
+  },
+
+  'should ignore saved voice preference when voice attr is set': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Karen', lang: 'en-AU' },
+      { name: 'Samantha', lang: 'en-US' }
+    ]);
+    setVoice('Karen');
+    const { container, el } = await createTextToSpeech({ text: 'hi', voice: 'Samantha' });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Samantha'){
+      stub.restore();
+      setVoice('');
+      cleanup(container);
+      return fail(`Expected explicit voice "Samantha" to win over saved "Karen", got ${u.voice && u.voice.name}`);
+    }
+    stub.restore();
+    setVoice('');
+    cleanup(container);
+    pass('Explicit voice attr overrides saved preference');
+  },
+
+  'should still match a single voice name with no commas': async ({pass, fail}) => {
+    const stub = installSynthesisStub([
+      { name: 'Samantha' }
+    ]);
+    const { container, el } = await createTextToSpeech({
+      text: 'hi',
+      voice: 'Samantha'
+    });
+    el.speak();
+    const u = stub.captured.spoken[0];
+    if(!u.voice || u.voice.name !== 'Samantha'){
+      stub.restore();
+      cleanup(container);
+      return fail(`Expected voice "Samantha", got ${u.voice && u.voice.name}`);
+    }
+    stub.restore();
+    cleanup(container);
+    pass('Single voice name still works');
+  },
+
   /*
     Browser support detection
   */