@octolearn/training-ui 0.1.0 → 0.2.0

package/README.md

@@ -255,9 +255,9 @@ shown as text, never as HTML.
 | --------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `<octolearn-question>`            | any question: picks the element by answer format, then learning mode    | `content`, `settings`, `no-autospeak`, `no-autofocus`, `no-keys`, `revealFlashcard`                                       |
 | `<octolearn-question-answer>`     | Vokabel / question, also Stimmt das? and Karteikarte                    | `content`, `no-autofocus`, `no-keys`, `revealFlashcard`                                                                   |
-| `<octolearn-dictation-question>`  | Diktat: listen, "Langsam anhören", optional "Einstellungen"             | `content`, `settings`, `no-autospeak`, `no-keys`                                                                          |
-| `<octolearn-arithmetic-question>` | Rechnen ("7 · 8 =")                                                     | `content`, `no-keys`                                                                                                      |
-| `<octolearn-picture-question>`    | Bilderrätsel                                                            | `content`, `no-keys`                                                                                                      |
+| `<octolearn-dictation-question>`  | Diktat: listen, "Langsam anhören", optional "Einstellungen"             | `content`, `settings`, `no-autospeak`, `no-autofocus`, `no-keys`                                                          |
+| `<octolearn-arithmetic-question>` | Rechnen ("7 · 8 =")                                                     | `content`, `no-autofocus`, `no-keys`                                                                                      |
+| `<octolearn-picture-question>`    | Bilderrätsel                                                            | `content`, `no-autofocus`, `no-keys`                                                                                      |
 | `<octolearn-multiple-choice>`     | answer tiles, keys 1–9                                                  | `options`, `label`, `no-keys`                                                                                             |
 | `<octolearn-text-answer>`         | the big field, "Weiß ich nicht", Wortfragment hint                      | `label`, `visible-label`, `type`, `input-lang`, `hint`, `no-dont-know`, `value`                                           |
 | `<octolearn-tile-answer>`         | Buchstabensalat / Satzpuzzle                                            | `tiles`, `separator` (`""` letters, `" "` words)                                                                          |
@@ -302,8 +302,13 @@ The texts are German (`de`) or English (`en`), following the `lang` attribute of
 exported as `de` and `en`).
 
 Dictations are read aloud with the browser's speech synthesis; the voice and speed the learner chose are remembered
-(`getSpeechController().choose(voice, rate)`). If the browser blocks speech before the first tap, the question shows an
-"Abspielen" button. To use your own audio, cancel `octolearn-speak` and play `detail.text` yourself.
+(`getSpeechController().choose(voice, rate)`). A word is only read by a voice of its language (`detail.lang`: the
+content's `sourceLanguage`, else `de`): the learner's voice if it speaks that language, else Google Deutsch or the first
+voice of it. Without one the browser gets the language alone, and the dictation shows a note that the device has no
+voice for it (`getSpeechController().hasVoiceFor(lang)`). If the browser blocks speech before the first tap, the
+question shows an "Abspielen" button. To use your own audio, cancel `octolearn-speak` and play `detail.text` in
+`detail.lang` yourself, or pass both to `getSpeechController().speak(text, { lang, rate })`, which waits for the
+browser's voice list (Chrome's first `getVoices()` is often empty).
 
 ## Theming
 
@@ -373,6 +378,17 @@ without dragging, the progress stars say "Frage 3 von 5, richtig", and the hints
 on touch screens. Right answers move on after 3 s; the timer pauses while the pointer rests on the card, and `no-auto` turns it
 off. Reduced motion is respected.
 
+## Phones and the on-screen keyboard
+
+When a phone's keyboard opens it covers about half of the screen. The elements notice this through
+`window.visualViewport` (CSS can't: the layout viewport keeps its size) and set the reflected attribute `short` on
+themselves while less than 520 px (`SHORT_VIEWPORT_PX`) are visible. In that state the card hides its header and Inkie
+(the label and stars stay for screen readers), texts, pictures and buttons get smaller, the answer field carries a
+round send button instead of "Fertig", and "Weiß ich nicht" becomes a small text button. A question whose field has the
+focus then scrolls its card to the top of the visible part, so the word or picture stays above the field. When the
+keyboard closes, everything is back as before. The page can follow the same state, e.g. with
+`.layout:has(octolearn-trainer[short])` or `getViewportWatcher().subscribe(short => …)`.
+
 ## Browser support, CSP and size
 
 Current Chrome, Edge, Firefox and Safari (custom elements, shadow DOM, container queries: Chrome 105+, Firefox 110+,

package/dist/chunks/{core-DR1lxtEg.js → core-rJUDTpGS.js}

@@ -2,6 +2,7 @@ const VOICE_STORAGE_KEY = "octolearn.training.voice";
 const RATE_STORAGE_KEY = "octolearn.training.rate";
 const MIN_RATE = 0.5;
 const MAX_RATE = 1.5;
+const VOICE_WAIT_MS = 1e3;
 class SpeechController {
   constructor(options = {}) {
     this.voices = [];
@@ -10,8 +11,8 @@ class SpeechController {
     this.requestId = 0;
     this.connections = 0;
     this.handleVoicesChanged = () => {
-      if (this.refreshVoices()) {
-        this.flushPending();
+      if (this.pending) {
+        this.flushWhenVoicesKnown();
       }
     };
     this.preferredVoices = options.preferredVoices ?? ["Google Deutsch"];
@@ -48,20 +49,27 @@ class SpeechController {
     if ("userActivation" in navigator && !navigator.userActivation.hasBeenActive) {
       return "blocked";
     }
-    if (this.refreshVoices()) {
-      this.flushPending();
-    }
+    this.flushWhenVoicesKnown();
     return "spoken";
   }
   /** Speaks the text that was blocked; call it from a click. */
   playPending() {
-    if (this.refreshVoices()) {
-      this.flushPending();
+    this.flushWhenVoicesKnown();
+  }
+  /**
+   * Whether the browser has a voice for the language (default: `preferredLanguage`); `undefined` while its voice list
+   * is still loading or without speech synthesis.
+   */
+  hasVoiceFor(lang = this.preferredLanguage) {
+    if (!SpeechController.supported || !this.refreshVoices()) {
+      return void 0;
     }
+    return this.voiceFor(lang) !== void 0;
   }
   stop() {
     this.pending = null;
     this.requestId++;
+    this.stopWaitingForVoices();
     if (SpeechController.supported) {
       speechSynthesis.cancel();
     }
@@ -76,21 +84,41 @@ class SpeechController {
     } catch {
     }
   }
+  /** Speaks the pending text now if the voice list is known, else on voiceschanged or after VOICE_WAIT_MS. */
+  flushWhenVoicesKnown() {
+    this.stopWaitingForVoices();
+    if (this.refreshVoices()) {
+      this.flushPending();
+      return;
+    }
+    this.voiceWait = setTimeout(() => {
+      this.voiceWait = void 0;
+      this.flushPending();
+    }, VOICE_WAIT_MS);
+  }
+  stopWaitingForVoices() {
+    if (this.voiceWait !== void 0) {
+      clearTimeout(this.voiceWait);
+      this.voiceWait = void 0;
+    }
+  }
+  /** Reads the browser's voice list; false while it is still empty. */
   refreshVoices() {
     const available = speechSynthesis.getVoices();
-    if (available.length === 0) {
-      return this.selectedVoice !== null;
+    if (available.length > 0) {
+      this.voices = available;
+      this.selectedVoice = this.preferredVoice(available);
     }
-    this.voices = available;
-    this.selectedVoice = this.preferredVoice(available);
-    return this.selectedVoice !== null;
+    return this.voices.length > 0;
   }
+  /** A voice that speaks the language: the learner's, else a preferred one, else the first; never one of another language. */
   voiceFor(lang) {
-    const wanted = lang.toLowerCase().split(/[-_]/)[0];
-    if (this.selectedVoice?.lang.toLowerCase().startsWith(wanted)) {
+    const wanted = primaryLanguage(lang);
+    const speaks = (voice) => !!voice && primaryLanguage(voice.lang) === wanted;
+    if (speaks(this.selectedVoice)) {
       return this.selectedVoice;
     }
-    return this.voices.find((voice) => voice.lang.toLowerCase().startsWith(wanted));
+    return this.preferredVoices.map((name) => this.voices.find((voice) => voice.name === name)).find(speaks) ?? this.voices.find(speaks);
   }
   preferredVoice(available) {
     const chosen = this.selectedVoice?.name ?? readStoredVoiceName();
@@ -104,7 +132,8 @@ class SpeechController {
     const requestId = ++this.requestId;
     const { text, options } = this.pending;
     this.pending = null;
-    const voice = (options.lang ? this.voiceFor(options.lang) : void 0) ?? this.selectedVoice;
+    const lang = options.lang ?? this.preferredLanguage;
+    const voice = this.voiceFor(lang);
     const speakLatest = () => {
       if (requestId !== this.requestId) {
         return;
@@ -113,9 +142,7 @@ class SpeechController {
       if (voice) {
         utterance.voice = voice;
       }
-      if (options.lang) {
-        utterance.lang = options.lang;
-      }
+      utterance.lang = voice?.lang ?? lang;
       utterance.rate = options.rate ?? this.rate;
       speechSynthesis.speak(utterance);
     };
@@ -127,6 +154,9 @@ class SpeechController {
     setTimeout(speakLatest, 0);
   }
 }
+function primaryLanguage(lang) {
+  return lang.trim().toLowerCase().split(/[-_]/)[0];
+}
 function clampRate(rate) {
   return Number.isFinite(rate) ? Math.min(MAX_RATE, Math.max(MIN_RATE, rate)) : 1;
 }