@intellectif/lk-react 13.0.0 → 14.1.0

package/dist/chunk-TUVEJLOT.js

@@ -0,0 +1,537 @@
+'use client';
+import { localeDirectionOf } from './chunk-YORQQXGO.js';
+import { ActivityErrorBoundary, isDevelopment } from './chunk-B4BCEQNO.js';
+import { useLkStrings } from './chunk-AWQ53DON.js';
+import { ActivitySchemaError, alignReadAloud, validateSpeechAssessment } from '@intellectif/lk-core';
+import { useState, useCallback, useId, useMemo, useRef, useEffect } from 'react';
+import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
+
+function usePlaybackRefusal(url) {
+  const [refusedUrl, setRefusedUrl] = useState(null);
+  const refuse = useCallback((element) => {
+    const source = element.getAttribute("src");
+    if (source !== null) {
+      setRefusedUrl(source);
+    }
+  }, []);
+  return { refused: url !== null && url !== void 0 && url === refusedUrl, refuse };
+}
+function isSourceRefusal(error) {
+  return typeof error === "object" && error !== null && error.name === "NotSupportedError";
+}
+
+// src/components/shared/read-grade.ts
+var DIMENSIONS = [
+  "accuracy",
+  "fluency",
+  "completeness",
+  "prosody"
+];
+var OUTCOMES = [
+  "correct",
+  "incorrect",
+  "correct-omission",
+  "incorrect-omission"
+];
+var OVERSHOOT = 1e-9;
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function isAbsent(value) {
+  return value === void 0 || value === null;
+}
+function withinMax(score, max) {
+  if (!isFiniteNumber(score) || score < 0) {
+    return null;
+  }
+  if (score <= max) {
+    return score;
+  }
+  return score - max <= max * OVERSHOOT ? max : null;
+}
+function isResponse(value) {
+  return typeof value === "string" || Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function guarded(read, refused) {
+  try {
+    return read();
+  } catch {
+    return refused;
+  }
+}
+function readCriterion(value) {
+  if (!isRecord(value) || typeof value.name !== "string") {
+    return null;
+  }
+  const { maxScore, notApplicable } = value;
+  if (!isAbsent(maxScore) && !(isFiniteNumber(maxScore) && maxScore > 0)) {
+    return null;
+  }
+  if (!isAbsent(notApplicable) && typeof notApplicable !== "boolean") {
+    return null;
+  }
+  const score = isAbsent(value.score) ? void 0 : withinMax(value.score, maxScore ?? 1);
+  if (score === null) {
+    return null;
+  }
+  return {
+    name: value.name,
+    ...score !== void 0 ? { score } : {},
+    ...!isAbsent(maxScore) ? { maxScore } : {},
+    ...notApplicable === true ? { notApplicable } : {}
+  };
+}
+function readDetail(value) {
+  if (!isRecord(value)) {
+    return null;
+  }
+  const { itemId, correct, outcome, learnerResponse, correctResponse, weight, score } = value;
+  if (typeof itemId !== "string" || typeof correct !== "boolean" || !isResponse(learnerResponse) || !isResponse(correctResponse)) {
+    return null;
+  }
+  const checkedOutcome = OUTCOMES.find((known) => known === outcome);
+  if (!isAbsent(outcome) && checkedOutcome === void 0) {
+    return null;
+  }
+  if (!isAbsent(weight) && !isFiniteNumber(weight)) {
+    return null;
+  }
+  const checkedScore = isAbsent(score) ? void 0 : withinMax(score, 1);
+  if (checkedScore === null) {
+    return null;
+  }
+  return {
+    itemId,
+    correct,
+    learnerResponse,
+    correctResponse,
+    ...checkedOutcome !== void 0 ? { outcome: checkedOutcome } : {},
+    ...!isAbsent(weight) ? { weight } : {},
+    ...checkedScore !== void 0 ? { score: checkedScore } : {}
+  };
+}
+function readDetails(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const details = [];
+  for (const entry of value) {
+    const detail = readDetail(entry);
+    if (detail === null) {
+      return void 0;
+    }
+    details.push(detail);
+  }
+  return details;
+}
+function readGrade(value) {
+  return guarded(() => {
+    if (!isRecord(value)) {
+      return null;
+    }
+    const { maxScore, passed } = value;
+    if (!isFiniteNumber(maxScore) || maxScore <= 0 || typeof passed !== "boolean") {
+      return null;
+    }
+    const score = withinMax(value.score, maxScore);
+    if (score === null) {
+      return null;
+    }
+    const criteria = Array.isArray(value.criteria) ? value.criteria.flatMap((entry) => {
+      const criterion = readCriterion(entry);
+      return criterion === null ? [] : [criterion];
+    }) : void 0;
+    const details = readDetails(value.details);
+    const grade = {
+      score,
+      maxScore,
+      passed,
+      feedback: typeof value.feedback === "string" ? value.feedback : null,
+      ...criteria !== void 0 ? { criteria } : {},
+      ...details !== void 0 ? { details } : {}
+    };
+    return grade;
+  }, null);
+}
+function fractionOfGrade(grade) {
+  return grade.score / grade.maxScore;
+}
+function percentOfGrade(grade) {
+  return Math.round(fractionOfGrade(grade) * 100);
+}
+function readOutcome(value) {
+  if (isAbsent(value)) {
+    return void 0;
+  }
+  return guarded(
+    () => {
+      if (!isRecord(value)) {
+        return { kind: "unreadable", status: void 0 };
+      }
+      switch (value.status) {
+        case "deferred":
+          return { kind: "deferred" };
+        case "unscorable":
+          return {
+            kind: "unscorable",
+            code: typeof value.code === "string" ? value.code : void 0
+          };
+        case "scored": {
+          const grade = readGrade(value);
+          return grade === null ? { kind: "unreadable", status: "scored" } : { kind: "graded", status: "scored", grade };
+        }
+        case "graded": {
+          const grade = readGrade(value.grade);
+          return grade === null || readGrade(value) === null ? { kind: "unreadable", status: "graded" } : { kind: "graded", status: "graded", grade };
+        }
+        default:
+          return { kind: "unreadable", status: void 0 };
+      }
+    },
+    { kind: "unreadable", status: void 0 }
+  );
+}
+function readAssessResult(value) {
+  const nothing = {
+    status: "graded",
+    grade: null,
+    assessment: null,
+    recognizedText: void 0
+  };
+  return guarded(() => {
+    if (!isRecord(value)) {
+      return nothing;
+    }
+    if (value.status === "failed") {
+      return { status: "failed", retryable: value.retryable === true };
+    }
+    if (value.status === "unscorable") {
+      return {
+        status: "unscorable",
+        code: typeof value.code === "string" ? value.code : void 0
+      };
+    }
+    if (value.status !== "graded") {
+      return nothing;
+    }
+    const assessment = readEvidence(value.assessment);
+    const recognizedText = guarded(
+      () => typeof assessment?.recognizedText === "string" ? assessment.recognizedText : void 0,
+      void 0
+    );
+    return { status: "graded", grade: readGrade(value.grade), assessment, recognizedText };
+  }, nothing);
+}
+function readEvidence(value) {
+  return isRecord(value) ? value : null;
+}
+function percentOfCriterion(criterion) {
+  if (criterion.notApplicable === true || criterion.score === void 0) {
+    return void 0;
+  }
+  return Math.round(criterion.score / (criterion.maxScore ?? 1) * 100);
+}
+function readDimensions(assessment, grade) {
+  const criteria = grade?.criteria ?? [];
+  if (criteria.length > 0) {
+    return DIMENSIONS.map((dimension) => {
+      const criterion = criteria.find((entry) => entry.name === dimension);
+      return {
+        dimension,
+        percent: criterion === void 0 ? void 0 : percentOfCriterion(criterion)
+      };
+    });
+  }
+  const scores = guarded(() => isRecord(assessment) ? assessment.scores : void 0, void 0);
+  return DIMENSIONS.map((dimension) => {
+    const score = withinMax(
+      guarded(() => isRecord(scores) ? scores[dimension] : void 0, void 0),
+      100
+    );
+    return { dimension, percent: score === null ? void 0 : Math.round(score) };
+  });
+}
+var VISUALLY_HIDDEN = {
+  position: "absolute",
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  overflow: "hidden",
+  clip: "rect(0 0 0 0)",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: 0
+};
+var LEGEND_STATES = [
+  "correct",
+  "mispronounced",
+  "omitted",
+  "inserted"
+];
+function checkEvidence(assessment) {
+  try {
+    return validateSpeechAssessment(assessment);
+  } catch {
+    return {
+      success: false,
+      errors: [{ path: [], message: "The assessment could not be read.", code: "unreadable" }]
+    };
+  }
+}
+function hasDetail(word) {
+  if (word === void 0) {
+    return false;
+  }
+  return word.accuracy !== void 0 || word.syllables !== void 0 && word.syllables.length > 0 || word.phonemes !== void 0 && word.phonemes.length > 0 || word.breaks !== void 0 || typeof word.startMs === "number" && typeof word.durationMs === "number";
+}
+function past(confidence, threshold) {
+  return threshold !== void 0 && typeof confidence === "number" && Number.isFinite(confidence) && confidence > threshold;
+}
+function phonemeLabel(phoneme, index, s) {
+  return phoneme.symbol ?? s.pronunciationPhonemePosition(index + 1);
+}
+function markSentence(entry, s) {
+  switch (entry.state) {
+    case "correct":
+      return s.pronunciationWordCorrect(entry.reference);
+    case "mispronounced":
+      return s.pronunciationWordMispronounced(entry.reference);
+    case "omitted":
+      return s.pronunciationWordOmitted(entry.reference);
+    default:
+      return s.pronunciationWordInserted(entry.heard);
+  }
+}
+function PronunciationFeedback({
+  data,
+  assessment,
+  grade,
+  audioUrl,
+  breakThreshold,
+  monotoneThreshold,
+  locale,
+  theme,
+  strings
+}) {
+  const s = useLkStrings(strings);
+  const ids = useId();
+  const [openWord, setOpenWord] = useState(null);
+  const checked = useMemo(() => checkEvidence(assessment), [assessment]);
+  const devError = useMemo(
+    () => isDevelopment() && !checked.success ? new ActivitySchemaError("read-aloud", checked.errors) : null,
+    [checked]
+  );
+  const words = useMemo(
+    () => checked.success ? alignReadAloud(data, checked.data) : null,
+    [checked, data]
+  );
+  const reading = useMemo(
+    () => grade === void 0 || grade === null ? void 0 : readGrade(grade),
+    [grade]
+  );
+  const dimensions = useMemo(() => readDimensions(assessment, reading), [assessment, reading]);
+  const audioRef = useRef(null);
+  const stopRef = useRef(null);
+  const playback = usePlaybackRefusal(audioUrl);
+  const playable = audioUrl !== void 0 && !playback.refused;
+  useEffect(
+    () => () => {
+      if (stopRef.current !== null) {
+        clearTimeout(stopRef.current);
+      }
+    },
+    []
+  );
+  if (devError) {
+    throw devError;
+  }
+  const playWord = (startMs, durationMs) => {
+    const element = audioRef.current;
+    if (element === null) {
+      return;
+    }
+    if (stopRef.current !== null) {
+      clearTimeout(stopRef.current);
+    }
+    element.currentTime = startMs / 1e3;
+    try {
+      void element.play().catch((error) => {
+        if (isSourceRefusal(error)) {
+          playback.refuse(element);
+        }
+      });
+    } catch {
+    }
+    stopRef.current = setTimeout(() => {
+      stopRef.current = null;
+      element.pause();
+    }, durationMs);
+  };
+  const contentLang = typeof data.locale === "string" ? data.locale : void 0;
+  const contentDir = localeDirectionOf(data.locale);
+  const alphabet = checked.success ? checked.data.phonemeAlphabet : void 0;
+  const monotone = checked.success ? checked.data.prosody?.monotoneConfidence : void 0;
+  const evidenceWords = checked.success ? checked.data.words : [];
+  return /* @__PURE__ */ jsxs(
+    "section",
+    {
+      className: "lk-pf",
+      "aria-label": s.pronunciationFeedbackLabel,
+      lang: locale,
+      style: theme,
+      children: [
+        reading !== void 0 ? (
+          // `.lk-pf-grade` is load-bearing beyond the skin: `<ReadAloud>` looks
+          // for it after the commit to decide whether it must render the score
+          // itself, so a grade is never lost between the two components. It
+          // hands this panel only a grade it has already read, so the block it
+          // finds always carries the score.
+          //
+          // `data-passed` only where there is a verdict: a grade that could not
+          // be read has none, and styling it as a fail would invent one.
+          /* @__PURE__ */ jsxs(
+            "div",
+            {
+              className: "lk-pf-grade",
+              ...reading !== null ? { "data-passed": String(reading.passed) } : {},
+              children: [
+                /* @__PURE__ */ jsx("p", { className: "lk-pf-score", children: reading === null ? s.couldNotBeGraded : s.scoreAnnouncement(percentOfGrade(reading), reading.passed) }),
+                reading?.feedback ? /* @__PURE__ */ jsx("p", { className: "lk-pf-grade-feedback", dir: "auto", children: reading.feedback }) : null
+              ]
+            }
+          )
+        ) : null,
+        /* @__PURE__ */ jsx("dl", { className: "lk-pf-dimensions", children: dimensions.map(({ dimension, percent }) => /* @__PURE__ */ jsxs("div", { className: "lk-pf-dimension", "data-dimension": dimension, children: [
+          /* @__PURE__ */ jsx("dt", { className: "lk-pf-dimension-name", children: s.pronunciationDimension(dimension) }),
+          /* @__PURE__ */ jsx("dd", { className: "lk-pf-dimension-score", children: percent === void 0 ? s.pronunciationNotAssessed : `${percent}%` })
+        ] }, dimension)) }),
+        words !== null ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("ol", { className: "lk-pf-words", "aria-label": s.pronunciationWordsLabel, dir: contentDir, children: words.map((entry, index) => {
+            const sentence = markSentence(entry, s);
+            const shown = entry.state === "inserted" ? entry.heard : entry.reference;
+            const word = entry.wordIndex === void 0 ? void 0 : evidenceWords.at(entry.wordIndex);
+            const open = openWord === index;
+            const panelId = `${ids}-w${index}`;
+            return /* @__PURE__ */ jsxs(
+              "li",
+              {
+                className: "lk-pf-word",
+                "data-state": entry.state,
+                children: [
+                  /* @__PURE__ */ jsx("span", { className: "lk-visually-hidden", style: VISUALLY_HIDDEN, children: sentence }),
+                  /* @__PURE__ */ jsx(
+                    "span",
+                    {
+                      className: "lk-pf-word-text",
+                      "aria-hidden": "true",
+                      dir: contentDir ?? "auto",
+                      lang: contentLang,
+                      children: shown
+                    }
+                  ),
+                  hasDetail(word) ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                    /* @__PURE__ */ jsx(
+                      "button",
+                      {
+                        type: "button",
+                        className: "lk-pf-word-toggle",
+                        "aria-expanded": open,
+                        "aria-controls": panelId,
+                        onClick: () => setOpenWord(open ? null : index),
+                        children: s.pronunciationWordDetails(shown)
+                      }
+                    ),
+                    open ? /* @__PURE__ */ jsxs("div", { id: panelId, className: "lk-pf-word-detail", children: [
+                      /* @__PURE__ */ jsxs("dl", { className: "lk-pf-word-facts", children: [
+                        /* @__PURE__ */ jsx("dt", { children: s.pronunciationDimension("accuracy") }),
+                        /* @__PURE__ */ jsx("dd", { children: word.accuracy === void 0 ? s.pronunciationNotAssessed : `${Math.round(word.accuracy)}%` }),
+                        word.syllables !== void 0 && word.syllables.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                          /* @__PURE__ */ jsx("dt", { children: s.pronunciationSyllables }),
+                          /* @__PURE__ */ jsx("dd", { children: /* @__PURE__ */ jsx("ul", { className: "lk-pf-syllables", children: word.syllables.map((syllable, position) => /* @__PURE__ */ jsx(
+                            "li",
+                            {
+                              dir: contentDir ?? "auto",
+                              lang: contentLang,
+                              children: syllable.grapheme === void 0 ? syllable.text : s.pronunciationSyllableSpelling(
+                                syllable.text,
+                                syllable.grapheme
+                              )
+                            },
+                            position
+                          )) }) })
+                        ] }) : null,
+                        word.phonemes !== void 0 && word.phonemes.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                          /* @__PURE__ */ jsx("dt", { children: s.pronunciationPhonemes }),
+                          /* @__PURE__ */ jsx("dd", { children: /* @__PURE__ */ jsx("ul", { className: "lk-pf-phonemes", children: word.phonemes.map((phoneme, position) => /* @__PURE__ */ jsxs(
+                            "li",
+                            {
+                              className: "lk-pf-phoneme",
+                              children: [
+                                /* @__PURE__ */ jsx("span", { className: "lk-pf-phoneme-symbol", children: phonemeLabel(phoneme, position, s) }),
+                                phoneme.heardAs !== void 0 && phoneme.heardAs.length > 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
+                                  /* @__PURE__ */ jsx("span", { className: "lk-pf-heard-label", children: s.pronunciationHeardAs }),
+                                  /* @__PURE__ */ jsx("ul", { className: "lk-pf-heard-as", children: phoneme.heardAs.map((candidate, rank) => /* @__PURE__ */ jsx(
+                                    "li",
+                                    {
+                                      children: candidate.symbol
+                                    },
+                                    rank
+                                  )) })
+                                ] }) : null
+                              ]
+                            },
+                            position
+                          )) }) })
+                        ] }) : null
+                      ] }),
+                      playable && typeof word.startMs === "number" && typeof word.durationMs === "number" ? /* @__PURE__ */ jsx(
+                        "button",
+                        {
+                          type: "button",
+                          className: "lk-pf-word-play",
+                          onClick: () => playWord(word.startMs, word.durationMs),
+                          children: s.pronunciationPlayWord(shown)
+                        }
+                      ) : null,
+                      past(word.breaks?.unexpected, breakThreshold) ? /* @__PURE__ */ jsx("p", { className: "lk-pf-break", "data-break": "unexpected", children: s.pronunciationBreakUnexpected }) : null,
+                      past(word.breaks?.missing, breakThreshold) ? /* @__PURE__ */ jsx("p", { className: "lk-pf-break", "data-break": "missing", children: s.pronunciationBreakMissing }) : null
+                    ] }) : null
+                  ] }) : null
+                ]
+              },
+              index
+            );
+          }) }),
+          /* @__PURE__ */ jsx("ul", { className: "lk-pf-legend", children: LEGEND_STATES.map((state) => /* @__PURE__ */ jsx("li", { "data-state": state, children: s.pronunciationLegend(state) }, state)) }),
+          alphabet === "ipa" ? /* @__PURE__ */ jsx("p", { className: "lk-pf-alphabet", children: s.pronunciationIpaNote }) : null
+        ] }) : null,
+        past(monotone, monotoneThreshold) ? /* @__PURE__ */ jsx("p", { className: "lk-pf-monotone", role: "note", children: s.pronunciationMonotone }) : null,
+        audioUrl === void 0 ? null : playback.refused ? /* @__PURE__ */ jsx("p", { className: "lk-pf-audio-unavailable", role: "note", children: s.readAloudPlaybackUnavailable }) : (
+          // biome-ignore lint/a11y/useMediaCaption: the learner's own take has no caption track to offer, and this element is never played as content — it carries no controls and exists only so one word can be replayed from a button that names it
+          /* @__PURE__ */ jsx(
+            "audio",
+            {
+              ref: audioRef,
+              className: "lk-pf-audio",
+              src: audioUrl,
+              preload: "metadata",
+              onError: (event) => playback.refuse(event.currentTarget)
+            }
+          )
+        )
+      ]
+    }
+  );
+}
+function PronunciationFeedback2(props) {
+  const strings = useLkStrings(props.strings);
+  return /* @__PURE__ */ jsx(ActivityErrorBoundary, { strings, children: /* @__PURE__ */ jsx(PronunciationFeedback, { ...props }) });
+}
+
+export { PronunciationFeedback2 as PronunciationFeedback, VISUALLY_HIDDEN, fractionOfGrade, markSentence, percentOfGrade, readAssessResult, readEvidence, readOutcome, usePlaybackRefusal };
+//# sourceMappingURL=chunk-TUVEJLOT.js.map
+//# sourceMappingURL=chunk-TUVEJLOT.js.map