@octolearn/training-ui 0.0.0-stage → 0.2.0

package/dist/chunks/core-rJUDTpGS.js

@@ -0,0 +1,592 @@
+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 = [];
+    this.selectedVoice = null;
+    this.pending = null;
+    this.requestId = 0;
+    this.connections = 0;
+    this.handleVoicesChanged = () => {
+      if (this.pending) {
+        this.flushWhenVoicesKnown();
+      }
+    };
+    this.preferredVoices = options.preferredVoices ?? ["Google Deutsch"];
+    this.preferredLanguage = (options.preferredLanguage ?? "de").toLowerCase();
+    this.rate = readStoredRate();
+  }
+  static get supported() {
+    return typeof speechSynthesis !== "undefined" && typeof SpeechSynthesisUtterance !== "undefined";
+  }
+  /** Starts listening for the browser's voice list. Call disconnect() as often as connect(). */
+  connect() {
+    if (!SpeechController.supported) {
+      return;
+    }
+    if (this.connections++ === 0) {
+      speechSynthesis.addEventListener("voiceschanged", this.handleVoicesChanged);
+      this.refreshVoices();
+    }
+  }
+  disconnect() {
+    if (!SpeechController.supported || this.connections === 0) {
+      return;
+    }
+    if (--this.connections === 0) {
+      speechSynthesis.removeEventListener("voiceschanged", this.handleVoicesChanged);
+    }
+  }
+  speak(input, options = {}) {
+    const text = (input ?? "").trim();
+    if (text === "" || !SpeechController.supported) {
+      return "unavailable";
+    }
+    this.pending = { text, options };
+    if ("userActivation" in navigator && !navigator.userActivation.hasBeenActive) {
+      return "blocked";
+    }
+    this.flushWhenVoicesKnown();
+    return "spoken";
+  }
+  /** Speaks the text that was blocked; call it from a click. */
+  playPending() {
+    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();
+    }
+  }
+  /** Remembers the voice (by name; the voice objects change when the browser reloads its list) and the speed. */
+  choose(voice, rate = this.rate) {
+    this.selectedVoice = voice;
+    this.rate = clampRate(rate);
+    try {
+      localStorage.setItem(VOICE_STORAGE_KEY, voice?.name ?? "");
+      localStorage.setItem(RATE_STORAGE_KEY, String(this.rate));
+    } 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) {
+      this.voices = available;
+      this.selectedVoice = this.preferredVoice(available);
+    }
+    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 = primaryLanguage(lang);
+    const speaks = (voice) => !!voice && primaryLanguage(voice.lang) === wanted;
+    if (speaks(this.selectedVoice)) {
+      return this.selectedVoice;
+    }
+    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();
+    const byName = (name) => name ? available.find((voice) => voice.name === name) : void 0;
+    return byName(chosen) ?? this.preferredVoices.map(byName).find((voice) => voice !== void 0) ?? available.find((voice) => voice.lang.toLowerCase().startsWith(this.preferredLanguage)) ?? available[0];
+  }
+  flushPending() {
+    if (!this.pending) {
+      return;
+    }
+    const requestId = ++this.requestId;
+    const { text, options } = this.pending;
+    this.pending = null;
+    const lang = options.lang ?? this.preferredLanguage;
+    const voice = this.voiceFor(lang);
+    const speakLatest = () => {
+      if (requestId !== this.requestId) {
+        return;
+      }
+      const utterance = new SpeechSynthesisUtterance(text);
+      if (voice) {
+        utterance.voice = voice;
+      }
+      utterance.lang = voice?.lang ?? lang;
+      utterance.rate = options.rate ?? this.rate;
+      speechSynthesis.speak(utterance);
+    };
+    if (!speechSynthesis.speaking && !speechSynthesis.pending) {
+      speakLatest();
+      return;
+    }
+    speechSynthesis.cancel();
+    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;
+}
+function readStoredRate() {
+  try {
+    const rate = Number.parseFloat(localStorage.getItem(RATE_STORAGE_KEY) ?? "");
+    return Number.isFinite(rate) && rate >= MIN_RATE && rate <= MAX_RATE ? rate : 1;
+  } catch {
+    return 1;
+  }
+}
+function readStoredVoiceName() {
+  try {
+    const name = localStorage.getItem(VOICE_STORAGE_KEY);
+    return name === null || name === "" ? void 0 : name;
+  } catch {
+    return void 0;
+  }
+}
+let defaultController;
+function getSpeechController() {
+  defaultController ??= new SpeechController();
+  return defaultController;
+}
+const ANSWER_EVENT = "octolearn-answer";
+const DONT_KNOW_ANSWER = "?";
+class TransportError extends Error {
+  constructor(status, message, retryAfterSeconds) {
+    super(message);
+    this.status = status;
+    this.retryAfterSeconds = retryAfterSeconds;
+    this.name = "TransportError";
+  }
+}
+function createThirdPartyTransport(options) {
+  const base = options.baseUrl.replace(/\/+$/, "");
+  const fetchFn = options.fetch ?? ((url, init) => fetch(url, init));
+  async function request(path, init = {}) {
+    const headers = { Accept: "application/json", ...await options.headers?.(), ...init.headers };
+    const response = await fetchFn(`${base}${path}`, { ...init, headers });
+    if (!response.ok) {
+      const retryAfter = Number.parseInt(response.headers.get("X-Rate-Limit-Retry-After-Seconds") ?? "", 10);
+      throw new TransportError(
+        response.status,
+        `octolearn API: ${init.method ?? "GET"} ${path} failed with ${response.status}`,
+        Number.isFinite(retryAfter) ? retryAfter : void 0
+      );
+    }
+    return await response.json();
+  }
+  return {
+    nextQuestions() {
+      const params = new URLSearchParams({ numberOfNeededQuestions: String(options.batchSize ?? 5) });
+      if (options.queryFormats?.length) {
+        params.set("filterQueryFormat", options.queryFormats.join(","));
+      }
+      if (options.learningModes?.length) {
+        params.set("filterLearningMode", options.learningModes.join(","));
+      }
+      return request(`/third-party/next-relevant-questions?${params.toString()}`).then((list) => list ?? []);
+    },
+    submitAnswer(content, answer) {
+      return request("/third-party", {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ frontendContent: content, answer })
+      });
+    },
+    todaysStatistic() {
+      return request("/third-party/get-todays-statistic");
+    }
+  };
+}
+class TrainingSession extends EventTarget {
+  constructor(transport, options = {}) {
+    super();
+    this.transport = transport;
+    this.correct = 0;
+    this.wrong = 0;
+    this.practising = false;
+    this.streak = 0;
+    this.feedback = null;
+    this.round = null;
+    this.nextRound = null;
+    this.roundRequested = false;
+    this.answersSinceRound = 0;
+    this.roundResults = [];
+    this.queue = [];
+    this.buffer = null;
+    this.started = false;
+    this.loading = false;
+    this.loadFailed = false;
+    this.prefetching = false;
+    this.prefetchFailed = false;
+    this.finished = false;
+    this.submitting = false;
+    this.recentlyAnswered = [];
+    this.prefetchAt = options.prefetchAt ?? 2;
+    this.recentMemory = options.recentMemory ?? 3;
+    this.holdForFeedback = options.holdForFeedback ?? false;
+    this.roundSize = Math.max(1, options.roundSize ?? 5);
+    this.matchingEvery = Math.max(1, options.matchingEvery ?? 8);
+  }
+  get state() {
+    if (this.loadFailed) {
+      return "error";
+    }
+    if (this.feedback) {
+      return "feedback";
+    }
+    if (this.round) {
+      return "pairs";
+    }
+    if (this.loading) {
+      return "loading";
+    }
+    if (this.queue.length > 0) {
+      return this.dueDone ? "due-done" : "question";
+    }
+    if (!this.started) {
+      return "idle";
+    }
+    if (this.finished) {
+      return "done";
+    }
+    return this.prefetchFailed && !this.prefetching ? "error" : "loading";
+  }
+  /** The question to show. */
+  get current() {
+    return this.queue[0] ?? null;
+  }
+  /** The questions waiting, the current one first. */
+  get upcoming() {
+    return this.queue;
+  }
+  /** Only practice is left (nothing due) and the learner hasn't chosen to go on. */
+  get dueDone() {
+    return !this.practising && this.queue.length > 0 && !this.queue.some((content) => content.learningLevelShallBeChanged);
+  }
+  /** The stars: the current question of the round and the results so far. A new round starts after `roundSize` answers. */
+  get roundProgress() {
+    if (this.feedback) {
+      return { current: this.roundResults.length, total: this.roundSize, results: this.roundResults };
+    }
+    if (this.roundResults.length >= this.roundSize) {
+      return { current: 1, total: this.roundSize, results: [] };
+    }
+    return { current: this.roundResults.length + 1, total: this.roundSize, results: this.roundResults };
+  }
+  /** An answer is being sent; further answers are ignored until it is evaluated. */
+  get busy() {
+    return this.submitting;
+  }
+  /** Loads the first questions and today's counts. */
+  async start() {
+    this.started = true;
+    await Promise.all([this.load(), this.loadStatistic(), this.requestRound()]);
+  }
+  /** Asks for questions again, e.g. after an error ("Erneut versuchen"). */
+  async reload() {
+    this.started = true;
+    await this.load();
+  }
+  startPractising() {
+    this.practising = true;
+    this.changed();
+  }
+  /** With `holdForFeedback`: leaves the feedback and shows the next question ("Weiter"). */
+  continue() {
+    if (!this.feedback) {
+      return;
+    }
+    this.feedback = null;
+    this.changed();
+  }
+  /**
+   * Sends the answer to the current question and moves on to the next one (with `holdForFeedback`: to the feedback).
+   * Returns null when there is no question, the answer is blank or another answer is still being sent. Pass
+   * `{ dontKnow: true }` for "Weiß ich nicht" (the `octolearn-answer` event's detail).
+   */
+  async answer(text, details = {}) {
+    const content = this.queue[0];
+    const answer = text.trim();
+    if (!content || answer === "" || this.submitting || this.feedback || this.round) {
+      return null;
+    }
+    this.submitting = true;
+    this.changed();
+    if (content.id !== void 0) {
+      this.rememberAnswered(content.id);
+    }
+    let evaluation = null;
+    try {
+      evaluation = await this.transport.submitAnswer(content, answer);
+    } catch {
+      evaluation = null;
+    }
+    const correct = evaluation?.isCorrect === true;
+    if (correct) {
+      this.correct++;
+      this.streak++;
+    } else {
+      this.wrong++;
+      this.streak = 0;
+    }
+    this.submitting = false;
+    if (this.roundResults.length >= this.roundSize) {
+      this.roundResults = [];
+    }
+    this.roundResults = [...this.roundResults, correct ? "right" : "wrong"];
+    const counts = content.learningLevelShallBeChanged !== false;
+    const multipleChoice = content.queryFormat === "MultipleChoice";
+    const outcome = {
+      content,
+      answer,
+      evaluation,
+      correct,
+      feedback: {
+        result: correct ? "correct" : "wrong",
+        answer,
+        correctAnswer: correct ? void 0 : evaluation?.correctAnswer,
+        typo: correct && evaluation?.acceptedWithTypo === true,
+        note: correct && evaluation?.acceptedWithTypo ? evaluation.feedbackMessage : void 0,
+        dontKnow: details.dontKnow === true,
+        unchecked: evaluation === null,
+        // a typed answer moves the learning level two steps, every other format one (OC-120); practice moves nothing
+        points: correct && counts ? content.queryFormat === "TextInput" ? 2 : 1 : 0,
+        streak: this.streak,
+        options: multipleChoice ? content.options ?? null : null,
+        word: content.learningMode === "Dictation" || content.isItVocabulary === true,
+        listenable: content.learningMode === "Dictation" && !multipleChoice,
+        queryFormat: content.queryFormat
+      }
+    };
+    if (this.holdForFeedback) {
+      this.feedback = outcome;
+    }
+    this.advance();
+    this.answersSinceRound++;
+    if (this.nextRound) {
+      this.round = this.nextRound;
+      this.nextRound = null;
+    } else if (this.answersSinceRound >= this.matchingEvery) {
+      void this.requestRound();
+    }
+    this.dispatchEvent(new CustomEvent("answered", { detail: outcome }));
+    this.changed();
+    return outcome;
+  }
+  /**
+   * Checks one pair of the current round, like an answer to that question; counts it and fires `pair-checked`. Null when
+   * the pair is not part of the round or could not be checked (the pair then stays open).
+   */
+  async checkPair(item, answer) {
+    if (!this.round?.items.some((roundItem) => roundItem.id === item.id)) {
+      return null;
+    }
+    let evaluation;
+    try {
+      evaluation = await this.transport.submitAnswer(
+        { id: item.id, learningMode: item.learningMode, learningLevelShallBeChanged: item.learningLevelShallBeChanged },
+        answer
+      );
+    } catch {
+      return null;
+    }
+    const correct = evaluation.isCorrect;
+    this.rememberAnswered(item.id);
+    if (correct) {
+      this.correct++;
+      this.streak++;
+    } else {
+      this.wrong++;
+      this.streak = 0;
+    }
+    this.dispatchEvent(new CustomEvent("pair-checked", { detail: { item, answer, evaluation, correct } }));
+    this.changed();
+    return evaluation;
+  }
+  /** After a round ("Weiter"): the single questions go on; the ones the round just asked are dropped from the queue. */
+  finishRound() {
+    if (!this.round) {
+      return;
+    }
+    const asked = new Set(this.round.items.map((item) => item.id));
+    const notAsked = (content) => content.id === void 0 || !asked.has(content.id);
+    this.round = null;
+    this.answersSinceRound = 0;
+    this.queue = this.queue.filter(notAsked);
+    if (this.buffer) {
+      this.buffer = this.buffer.filter(notAsked);
+    }
+    if (this.queue.length === 0) {
+      if (this.buffer === null && !this.prefetching) {
+        void this.prefetch();
+      } else {
+        this.drainBuffer();
+      }
+    }
+    this.changed();
+  }
+  /** The answer of a Karteikarte (for `<octolearn-flashcard>`.reveal); rejects when the transport can't. */
+  revealFlashcard(content = this.current) {
+    if (!content || !this.transport.revealFlashcard) {
+      return Promise.reject(new Error("This transport cannot reveal flashcards."));
+    }
+    return this.transport.revealFlashcard(content);
+  }
+  /**
+   * Asks for a round of "Paare finden" (OC-125). Before the first answer it is shown at once; later it waits until the
+   * question on screen is answered. A round without items, or an error, just means single questions go on.
+   */
+  async requestRound() {
+    if (!this.transport.matchingRound || this.roundRequested || this.round || this.nextRound) {
+      return;
+    }
+    this.roundRequested = true;
+    try {
+      const round = await this.transport.matchingRound();
+      if (round.items.length === 0) {
+        this.answersSinceRound = 0;
+      } else if (this.answersSinceRound === 0 && !this.feedback) {
+        this.round = round;
+      } else {
+        this.nextRound = round;
+      }
+    } catch {
+      this.answersSinceRound = 0;
+    } finally {
+      this.roundRequested = false;
+      this.changed();
+    }
+  }
+  async load() {
+    this.loading = true;
+    this.loadFailed = false;
+    this.changed();
+    try {
+      const batch = await this.transport.nextQuestions();
+      this.queue = this.preferNotRecentlyAnswered(batch);
+      this.buffer = null;
+      this.prefetchFailed = false;
+      this.finished = this.queue.length === 0;
+    } catch {
+      this.loadFailed = true;
+    } finally {
+      this.loading = false;
+      this.changed();
+    }
+  }
+  async loadStatistic() {
+    if (!this.transport.todaysStatistic) {
+      return;
+    }
+    try {
+      const statistic = await this.transport.todaysStatistic();
+      this.correct = statistic.correctAnswerCount ?? this.correct;
+      this.wrong = statistic.wrongAnswerCount ?? this.wrong;
+      this.changed();
+    } catch {
+    }
+  }
+  advance() {
+    this.queue.shift();
+    if (this.queue.length <= this.prefetchAt && !this.prefetching && this.buffer === null) {
+      void this.prefetch();
+    }
+    if (this.queue.length === 0) {
+      this.drainBuffer();
+    }
+  }
+  async prefetch() {
+    this.prefetching = true;
+    this.prefetchFailed = false;
+    const onScreenAtStart = new Set(this.queue.map((content) => content.id));
+    let droppedOnScreen = false;
+    try {
+      const received = await this.transport.nextQuestions();
+      const notOnScreen = received.filter((content) => !onScreenAtStart.has(content.id) && !this.queue.some((open) => open.id === content.id));
+      droppedOnScreen = notOnScreen.length < received.length;
+      this.buffer = notOnScreen.length === 0 && droppedOnScreen ? null : this.preferNotRecentlyAnswered(notOnScreen);
+    } catch {
+      this.prefetchFailed = true;
+      this.buffer = null;
+    }
+    this.prefetching = false;
+    if (this.buffer === null && droppedOnScreen) {
+      if (this.queue.length === 0) {
+        void this.prefetch();
+      }
+    } else if (this.queue.length === 0) {
+      this.drainBuffer();
+    }
+    this.changed();
+  }
+  drainBuffer() {
+    if (this.buffer === null) {
+      return;
+    }
+    if (this.buffer.length > 0) {
+      this.queue = this.buffer;
+    } else {
+      this.finished = true;
+    }
+    this.buffer = null;
+  }
+  rememberAnswered(id) {
+    this.recentlyAnswered = [...this.recentlyAnswered.filter((known) => known !== id), id].slice(-this.recentMemory);
+  }
+  /**
+   * Puts what was answered a moment ago behind the other questions of the batch (OC-224). It is not left out: a wrongly
+   * answered question comes back in the same session on purpose, and a batch that lost its only due question would say
+   * "done" while that question is still waiting (OC-251). A lone question may come back.
+   */
+  preferNotRecentlyAnswered(batch) {
+    const isRecent = (content) => content.id !== void 0 && this.recentlyAnswered.includes(content.id);
+    return [...batch.filter((content) => !isRecent(content)), ...batch.filter(isRecent)];
+  }
+  changed() {
+    this.dispatchEvent(new Event("change"));
+  }
+}
+export {
+  ANSWER_EVENT as A,
+  DONT_KNOW_ANSWER as D,
+  MAX_RATE as M,
+  SpeechController as S,
+  TrainingSession as T,
+  MIN_RATE as a,
+  TransportError as b,
+  createThirdPartyTransport as c,
+  getSpeechController as g
+};